diff options
Diffstat (limited to 'Documentation')
213 files changed, 5094 insertions, 796 deletions
diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index 1fe9a553c37b..831f19a32e08 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -101,6 +101,16 @@ Description: devices that support receiving integrity metadata. +What: /sys/block/<disk>/partscan +Date: May 2024 +Contact: Christoph Hellwig <hch@lst.de> +Description: + The /sys/block/<disk>/partscan files reports if partition + scanning is enabled for the disk. It returns "1" if partition + scanning is enabled, or "0" if not. The value type is a 32-bit + unsigned integer, but only "0" and "1" are valid values. + + What: /sys/block/<disk>/<partition>/alignment_offset Date: April 2009 Contact: Martin K. Petersen <martin.petersen@oracle.com> @@ -584,18 +594,6 @@ Description: the data. If no such restriction exists, this file will contain '0'. This file is writable for testing purposes. - -What: /sys/block/<disk>/queue/throttle_sample_time -Date: March 2017 -Contact: linux-block@vger.kernel.org -Description: - [RW] This is the time window that blk-throttle samples data, in - millisecond. blk-throttle makes decision based on the - samplings. Lower time means cgroups have more smooth throughput, - but higher CPU overhead. This exists only when - CONFIG_BLK_DEV_THROTTLING_LOW is enabled. - - What: /sys/block/<disk>/queue/virt_boundary_mask Date: April 2021 Contact: linux-block@vger.kernel.org diff --git a/Documentation/Makefile b/Documentation/Makefile index b68f8c816897..a961692baa12 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -28,6 +28,10 @@ BUILDDIR = $(obj)/output PDFLATEX = xelatex LATEXOPTS = -interaction=batchmode -no-shell-escape +# For denylisting "variable font" files +# Can be overridden by setting as an env variable +FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf + ifeq ($(findstring 1, $(KBUILD_VERBOSE)),) SPHINXOPTS += "-q" endif @@ -151,10 +155,11 @@ pdfdocs: else # HAVE_PDFLATEX +pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF) pdfdocs: latexdocs @$(srctree)/scripts/sphinx-pre-install --version-check $(foreach var,$(SPHINXDIRS), \ - $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ + $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \ ) diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 872ac665223f..94838c65c7d9 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -427,7 +427,7 @@ their assorted primitives. This section shows a simple use of the core RCU API to protect a global pointer to a dynamically allocated structure. More-typical -uses of RCU may be found in listRCU.rst, arrayRCU.rst, and NMI-RCU.rst. +uses of RCU may be found in listRCU.rst and NMI-RCU.rst. :: struct foo { @@ -510,8 +510,8 @@ So, to sum up: data item. See checklist.rst for additional rules to follow when using RCU. -And again, more-typical uses of RCU may be found in listRCU.rst, -arrayRCU.rst, and NMI-RCU.rst. +And again, more-typical uses of RCU may be found in listRCU.rst +and NMI-RCU.rst. .. _4_whatisRCU: diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 17e6e9565156..eaf9e66e472a 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1572,6 +1572,15 @@ PAGE_SIZE multiple when read back. pglazyfreed (npn) Amount of reclaimed lazyfree pages + zswpin + Number of pages moved in to memory from zswap. + + zswpout + Number of pages moved out of memory to zswap. + + zswpwb + Number of pages written from zswap to swap. + thp_fault_alloc (npn) Number of transparent hugepages which were allocated to satisfy a page fault. This counter is not present when CONFIG_TRANSPARENT_HUGEPAGE diff --git a/Documentation/admin-guide/hw-vuln/core-scheduling.rst b/Documentation/admin-guide/hw-vuln/core-scheduling.rst index cf1eeefdfc32..a92e10ec402e 100644 --- a/Documentation/admin-guide/hw-vuln/core-scheduling.rst +++ b/Documentation/admin-guide/hw-vuln/core-scheduling.rst @@ -67,8 +67,8 @@ arg4: will be performed for all tasks in the task group of ``pid``. arg5: - userspace pointer to an unsigned long for storing the cookie returned by - ``PR_SCHED_CORE_GET`` command. Should be 0 for all other commands. + userspace pointer to an unsigned long long for storing the cookie returned + by ``PR_SCHED_CORE_GET`` command. Should be 0 for all other commands. In order for a process to push a cookie to, or pull a cookie from a process, it is required to have the ptrace access mode: `PTRACE_MODE_READ_REALCREDS` to the diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index cce768afec6b..25a04cda4c2c 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -138,11 +138,10 @@ associated with the source address of the indirect branch. Specifically, the BHB might be shared across privilege levels even in the presence of Enhanced IBRS. -Currently the only known real-world BHB attack vector is via -unprivileged eBPF. Therefore, it's highly recommended to not enable -unprivileged eBPF, especially when eIBRS is used (without retpolines). -For a full mitigation against BHB attacks, it's recommended to use -retpolines (or eIBRS combined with retpolines). +Previously the only known real-world BHB attack vector was via unprivileged +eBPF. Further research has found attacks that don't require unprivileged eBPF. +For a full mitigation against BHB attacks it is recommended to set BHI_DIS_S or +use the BHB clearing sequence. Attack scenarios ---------------- @@ -430,6 +429,23 @@ The possible values in this file are: 'PBRSB-eIBRS: Not affected' CPU is not affected by PBRSB =========================== ======================================================= + - Branch History Injection (BHI) protection status: + +.. list-table:: + + * - BHI: Not affected + - System is not affected + * - BHI: Retpoline + - System is protected by retpoline + * - BHI: BHI_DIS_S + - System is protected by BHI_DIS_S + * - BHI: SW loop, KVM SW loop + - System is protected by software clearing sequence + * - BHI: Vulnerable + - System is vulnerable to BHI + * - BHI: Vulnerable, KVM: SW loop + - System is vulnerable; KVM is protected by software clearing sequence + Full mitigation might require a microcode update from the CPU vendor. When the necessary microcode is not available, the kernel will report vulnerability. @@ -484,7 +500,11 @@ Spectre variant 2 Systems which support enhanced IBRS (eIBRS) enable IBRS protection once at boot, by setting the IBRS bit, and they're automatically protected against - Spectre v2 variant attacks. + some Spectre v2 variant attacks. The BHB can still influence the choice of + indirect branch predictor entry, and although branch predictor entries are + isolated between modes when eIBRS is enabled, the BHB itself is not isolated + between modes. Systems which support BHI_DIS_S will set it to protect against + BHI attacks. On Intel's enhanced IBRS systems, this includes cross-thread branch target injections on SMT systems (STIBP). In other words, Intel eIBRS enables @@ -638,6 +658,18 @@ kernel command line. spectre_v2=off. Spectre variant 1 mitigations cannot be disabled. + spectre_bhi= + + [X86] Control mitigation of Branch History Injection + (BHI) vulnerability. This setting affects the deployment + of the HW BHI control and the SW BHB clearing sequence. + + on + (default) Enable the HW or SW mitigation as + needed. + off + Disable the mitigation. + For spectre_v2_user see Documentation/admin-guide/kernel-parameters.txt Mitigation selection guide diff --git a/Documentation/admin-guide/hw-vuln/srso.rst b/Documentation/admin-guide/hw-vuln/srso.rst index e715bfc09879..4bd3ce3ba171 100644 --- a/Documentation/admin-guide/hw-vuln/srso.rst +++ b/Documentation/admin-guide/hw-vuln/srso.rst @@ -135,7 +135,7 @@ and does not want to suffer the performance impact, one can always disable the mitigation with spec_rstack_overflow=off. Similarly, 'Mitigation: IBPB' is another full mitigation type employing -an indrect branch prediction barrier after having applied the required +an indirect branch prediction barrier after having applied the required microcode patch for one's system. This mitigation comes also at a performance cost. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 3f390cc5f77e..fe39954ca058 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -3423,6 +3423,9 @@ arch-independent options, each of which is an aggregation of existing arch-specific options. + Note, "mitigations" is supported if and only if the + kernel was built with CPU_MITIGATIONS=y. + off Disable all optional CPU mitigations. This improves system performance, but it may also @@ -3444,6 +3447,7 @@ retbleed=off [X86] spec_rstack_overflow=off [X86] spec_store_bypass_disable=off [X86,PPC] + spectre_bhi=off [X86] spectre_v2_user=off [X86] srbds=off [X86,INTEL] ssbd=force-off [ARM64] @@ -4169,13 +4173,11 @@ page_alloc.shuffle= [KNL] Boolean flag to control whether the page allocator - should randomize its free lists. The randomization may - be automatically enabled if the kernel detects it is - running on a platform with a direct-mapped memory-side - cache, and this parameter can be used to - override/disable that behavior. The state of the flag - can be read from sysfs at: + should randomize its free lists. This parameter can be + used to enable/disable page randomization. The state of + the flag can be read from sysfs at: /sys/module/page_alloc/parameters/shuffle. + This parameter is only available if CONFIG_SHUFFLE_PAGE_ALLOCATOR=y. page_owner= [KNL,EARLY] Boot-time page_owner enabling option. Storage of the information about who allocated @@ -4590,9 +4592,10 @@ norid [S390] ignore the RID field and force use of one PCI domain per PCI function - pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power + pcie_aspm= [PCIE] Forcibly enable or ignore PCIe Active State Power Management. - off Disable ASPM. + off Don't touch ASPM configuration at all. Leave any + configuration done by firmware unchanged. force Enable ASPM even on devices that claim not to support it. WARNING: Forcing ASPM on may cause system lockups. @@ -4780,7 +4783,9 @@ prot_virt= [S390] enable hosting protected virtual machines isolated from the hypervisor (if hardware supports - that). + that). If enabled, the default kernel base address + might be overridden even when Kernel Address Space + Layout Randomization is disabled. Format: <bool> psi= [KNL] Enable or disable pressure stall information @@ -5091,6 +5096,20 @@ delay, memory pressure or callback list growing too big. + rcutree.rcu_normal_wake_from_gp= [KNL] + Reduces a latency of synchronize_rcu() call. This approach + maintains its own track of synchronize_rcu() callers, so it + does not interact with regular callbacks because it does not + use a call_rcu[_hurry]() path. Please note, this is for a + normal grace period. + + How to enable it: + + echo 1 > /sys/module/rcutree/parameters/rcu_normal_wake_from_gp + or pass a boot parameter "rcutree.rcu_normal_wake_from_gp=1" + + Default is 0. + rcuscale.gp_async= [KNL] Measure performance of asynchronous grace-period primitives such as call_rcu(). @@ -6064,6 +6083,15 @@ sonypi.*= [HW] Sony Programmable I/O Control Device driver See Documentation/admin-guide/laptops/sonypi.rst + spectre_bhi= [X86] Control mitigation of Branch History Injection + (BHI) vulnerability. This setting affects the + deployment of the HW BHI control and the SW BHB + clearing sequence. + + on - (default) Enable the HW or SW mitigation + as needed. + off - Disable the mitigation. + spectre_v2= [X86,EARLY] Control mitigation of Spectre variant 2 (indirect branch speculation) vulnerability. The default operation protects the kernel from @@ -6600,7 +6628,7 @@ To turn off having tracepoints sent to printk, echo 0 > /proc/sys/kernel/tracepoint_printk Note, echoing 1 into this file without the - tracepoint_printk kernel cmdline option has no effect. + tp_printk kernel cmdline option has no effect. The tp_printk_stop_on_boot (see below) can also be used to stop the printing of events to console at @@ -6736,6 +6764,7 @@ - "tpm" - "tee" - "caam" + - "dcp" If not specified then it defaults to iterating through the trust source list starting with TPM and assigns the first trust source as a backend which is initialized @@ -6751,6 +6780,18 @@ If not specified, "default" is used. In this case, the RNG's choice is left to each individual trust source. + trusted.dcp_use_otp_key + This is intended to be used in combination with + trusted.source=dcp and will select the DCP OTP key + instead of the DCP UNIQUE key blob encryption. + + trusted.dcp_skip_zk_test + This is intended to be used in combination with + trusted.source=dcp and will disable the check if the + blob key is all zeros. This is helpful for situations where + having this key zero'ed is acceptable. E.g. in testing + scenarios. + tsc= Disable clocksource stability checks for TSC. Format: <string> [x86] reliable: mark tsc clocksource as reliable, this @@ -7311,7 +7352,7 @@ This can be changed after boot by writing to the matching /sys/module/workqueue/parameters file. All workqueues with the "default" affinity scope will be - updated accordignly. + updated accordingly. workqueue.debug_force_rr_cpu Workqueue used to implicitly guarantee that work diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index a639cac12477..ad8e7a41f3b5 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -308,7 +308,7 @@ limited by the ``advisor_max_cpu`` parameter. In addition there is also the ``advisor_target_scan_time`` parameter. This parameter sets the target time to scan all the KSM candidate pages. The parameter ``advisor_target_scan_time`` decides how aggressive the scan time advisor scans candidate pages. Lower -values make the scan time advisor to scan more aggresively. This is the most +values make the scan time advisor to scan more aggressively. This is the most important parameter for the configuration of the scan time advisor. The initial value and the maximum value can be changed with diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index b42132969e31..13632671adae 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -155,7 +155,7 @@ Setting this parameter to 100 will disable the hysteresis. Some users cannot tolerate the swapping that comes with zswap store failures and zswap writebacks. Swapping can be disabled entirely (without disabling -zswap itself) on a cgroup-basis as follows: +zswap itself) on a cgroup-basis as follows:: echo 0 > /sys/fs/cgroup/<cgroup-name>/memory.zswap.writeback @@ -166,7 +166,7 @@ writeback (because the same pages might be rejected again and again). When there is a sizable amount of cold memory residing in the zswap pool, it can be advantageous to proactively write these cold pages to swap and reclaim the memory for other use cases. By default, the zswap shrinker is disabled. -User can enable it as follows: +User can enable it as follows:: echo Y > /sys/module/zswap/parameters/shrinker_enabled diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst index 76b246ecf21b..946518355a2c 100644 --- a/Documentation/admin-guide/reporting-regressions.rst +++ b/Documentation/admin-guide/reporting-regressions.rst @@ -42,12 +42,12 @@ The important basics -------------------- -What is a "regression" and what is the "no regressions rule"? +What is a "regression" and what is the "no regressions" rule? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It's a regression if some application or practical use case running fine with one Linux kernel works worse or not at all with a newer version compiled using a -similar configuration. The "no regressions rule" forbids this to take place; if +similar configuration. The "no regressions" rule forbids this to take place; if it happens by accident, developers that caused it are expected to quickly fix the issue. @@ -173,7 +173,7 @@ Additional details about regressions ------------------------------------ -What is the goal of the "no regressions rule"? +What is the goal of the "no regressions" rule? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Users should feel safe when updating kernel versions and not have to worry @@ -199,8 +199,8 @@ Exceptions to this rule are extremely rare; in the past developers almost always turned out to be wrong when they assumed a particular situation was warranting an exception. -Who ensures the "no regressions" is actually followed? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Who ensures the "no regressions" rule is actually followed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The subsystem maintainers should take care of that, which are watched and supported by the tree maintainers -- e.g. Linus Torvalds for mainline and diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index d3504826f401..c389d4fd7599 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -29,7 +29,7 @@ The essence of the process (aka 'TL;DR') ======================================== *[If you are new to building or bisecting Linux, ignore this section and head -over to the* ":ref:`step-by-step guide<introguide_bissbs>`" *below. It utilizes +over to the* ':ref:`step-by-step guide <introguide_bissbs>`' *below. It utilizes the same commands as this section while describing them in brief fashion. The steps are nevertheless easy to follow and together with accompanying entries in a reference section mention many alternatives, pitfalls, and additional @@ -38,8 +38,8 @@ aspects, all of which might be essential in your present case.]* **In case you want to check if a bug is present in code currently supported by developers**, execute just the *preparations* and *segment 1*; while doing so, consider the newest Linux kernel you regularly use to be the 'working' kernel. -In the following example that's assumed to be 6.0.13, which is why the sources -of 6.0 will be used to prepare the .config file. +In the following example that's assumed to be 6.0, which is why its sources +will be used to prepare the .config file. **In case you face a regression**, follow the steps at least till the end of *segment 2*. Then you can submit a preliminary report -- or continue with @@ -61,7 +61,7 @@ will be considered the 'good' release and used to prepare the .config file. cd ~/linux/ git remote add -t master stable \ https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git - git checkout --detach v6.0 + git switch --detach v6.0 # * Hint: if you used an existing clone, ensure no stale .config is around. make olddefconfig # * Ensure the former command picked the .config of the 'working' kernel. @@ -87,7 +87,7 @@ will be considered the 'good' release and used to prepare the .config file. a) Checking out latest mainline code:: cd ~/linux/ - git checkout --force --detach mainline/master + git switch --discard-changes --detach mainline/master b) Build, install, and boot a kernel:: @@ -125,7 +125,7 @@ will be considered the 'good' release and used to prepare the .config file. a) Start by checking out the sources of the 'good' version:: cd ~/linux/ - git checkout --force --detach v6.0 + git switch --discard-changes --detach v6.0 b) Build, install, and boot a kernel as described earlier in *segment 1, section b* -- just feel free to skip the 'du' commands, as you have a rough @@ -136,8 +136,7 @@ will be considered the 'good' release and used to prepare the .config file. * **Segment 3**: perform and validate the bisection. - a) In case your 'broken' version is a stable/longterm release, add the Git - branch holding it:: + a) Retrieve the sources for your 'bad' version:: git remote set-branches --add stable linux-6.1.y git fetch stable @@ -157,11 +156,12 @@ will be considered the 'good' release and used to prepare the .config file. works with the newly built kernel. If it does, tell Git by executing ``git bisect good``; if it does not, run ``git bisect bad`` instead. - All three commands will make Git checkout another commit; then re-execute + All three commands will make Git check out another commit; then re-execute this step (e.g. build, install, boot, and test a kernel to then tell Git the outcome). Do so again and again until Git shows which commit broke things. If you run short of disk space during this process, check the - "Supplementary tasks" section below. + section 'Complementary tasks: cleanup during and after the process' + below. d) Once your finished the bisection, put a few things away:: @@ -172,14 +172,17 @@ will be considered the 'good' release and used to prepare the .config file. e) Try to verify the bisection result:: - git checkout --force --detach mainline/master + git switch --discard-changes --detach mainline/master git revert --no-edit cafec0cacaca0 + cp ~/kernel-config-working .config + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted' This is optional, as some commits are impossible to revert. But if the second command worked flawlessly, build, install, and boot one more kernel - kernel, which should not show the regression. + kernel; just this time skip the first command copying the base .config file + over, as that already has been taken care off. -* **Supplementary tasks**: cleanup during and after the process. +* **Complementary tasks**: cleanup during and after the process. a) To avoid running out of disk space during a bisection, you might need to remove some kernels you built earlier. You most likely want to keep those @@ -202,13 +205,25 @@ will be considered the 'good' release and used to prepare the .config file. the kernels you built earlier and later you might want to keep around for a week or two. +* **Optional task**: test a debug patch or a proposed fix later:: + + git fetch mainline + git switch --discard-changes --detach mainline/master + git apply /tmp/foobars-proposed-fix-v1.patch + cp ~/kernel-config-working .config + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1' + + Build, install, and boot a kernel as described in *segment 1, section b* -- + but this time omit the first command copying the build configuration over, + as that has been taken care of already. + .. _introguide_bissbs: Step-by-step guide on how to verify bugs and bisect regressions =============================================================== This guide describes how to set up your own Linux kernels for investigating bugs -or regressions you intent to report. How far you want to follow the instructions +or regressions you intend to report. How far you want to follow the instructions depends on your issue: Execute all steps till the end of *segment 1* to **verify if your kernel problem @@ -221,15 +236,17 @@ report; instead of the latter your could also head straight on and follow *segment 3* to **perform a bisection** for a full-fledged regression report developers are obliged to act upon. - :ref:`Preparations: set up everything to build your own kernels.<introprep_bissbs>` + :ref:`Preparations: set up everything to build your own kernels <introprep_bissbs>`. - :ref:`Segment 1: try to reproduce the problem with the latest codebase.<introlatestcheck_bissbs>` + :ref:`Segment 1: try to reproduce the problem with the latest codebase <introlatestcheck_bissbs>`. - :ref:`Segment 2: check if the kernels you build work fine.<introworkingcheck_bissbs>` + :ref:`Segment 2: check if the kernels you build work fine <introworkingcheck_bissbs>`. - :ref:`Segment 3: perform a bisection and validate the result.<introbisect_bissbs>` + :ref:`Segment 3: perform a bisection and validate the result <introbisect_bissbs>`. - :ref:`Supplementary tasks: cleanup during and after following this guide.<introclosure_bissbs>` + :ref:`Complementary tasks: cleanup during and after following this guide <introclosure_bissbs>`. + + :ref:`Optional tasks: test reverts, patches, or later versions <introoptional_bissbs>`. The steps in each segment illustrate the important aspects of the process, while a comprehensive reference section holds additional details for almost all of the @@ -240,24 +257,35 @@ to get things rolling again. For further details on how to report Linux kernel issues or regressions check out Documentation/admin-guide/reporting-issues.rst, which works in conjunction with this document. It among others explains why you need to verify bugs with -the latest 'mainline' kernel, even if you face a problem with a kernel from a -'stable/longterm' series; for users facing a regression it also explains that -sending a preliminary report after finishing segment 2 might be wise, as the -regression and its culprit might be known already. For further details on -what actually qualifies as a regression check out -Documentation/admin-guide/reporting-regressions.rst. +the latest 'mainline' kernel (e.g. versions like 6.0, 6.1-rc1, or 6.1-rc6), +even if you face a problem with a kernel from a 'stable/longterm' series +(say 6.0.13). + +For users facing a regression that document also explains why sending a +preliminary report after segment 2 might be wise, as the regression and its +culprit might be known already. For further details on what actually qualifies +as a regression check out Documentation/admin-guide/reporting-regressions.rst. + +If you run into any problems while following this guide or have ideas how to +improve it, :ref:`please let the kernel developers know <submit_improvements>`. .. _introprep_bissbs: Preparations: set up everything to build your own kernels --------------------------------------------------------- +The following steps lay the groundwork for all further tasks. + +Note: the instructions assume you are building and testing on the same +machine; if you want to compile the kernel on another system, check +:ref:`Build kernels on a different machine <buildhost_bis>` below. + .. _backup_bissbs: * Create a fresh backup and put system repair and restore tools at hand, just to be prepared for the unlikely case of something going sideways. - [:ref:`details<backup_bisref>`] + [:ref:`details <backup_bisref>`] .. _vanilla_bissbs: @@ -265,7 +293,7 @@ Preparations: set up everything to build your own kernels builds them automatically. That includes but is not limited to DKMS, openZFS, VirtualBox, and Nvidia's graphics drivers (including the GPLed kernel module). - [:ref:`details<vanilla_bisref>`] + [:ref:`details <vanilla_bisref>`] .. _secureboot_bissbs: @@ -276,48 +304,49 @@ Preparations: set up everything to build your own kernels their restrictions through a process initiated by ``mokutil --disable-validation``. - [:ref:`details<secureboot_bisref>`] + [:ref:`details <secureboot_bisref>`] .. _rangecheck_bissbs: * Determine the kernel versions considered 'good' and 'bad' throughout this - guide. + guide: - Do you follow this guide to verify if a bug is present in the code developers - care for? Then consider the mainline release your 'working' kernel (the newest - one you regularly use) is based on to be the 'good' version; if your 'working' - kernel for example is 6.0.11, then your 'good' kernel is 6.0. + * Do you follow this guide to verify if a bug is present in the code the + primary developers care for? Then consider the version of the newest kernel + you regularly use currently as 'good' (e.g. 6.0, 6.0.13, or 6.1-rc2). - In case you face a regression, it depends on the version range where the - regression was introduced: + * Do you face a regression, e.g. something broke or works worse after + switching to a newer kernel version? In that case it depends on the version + range during which the problem appeared: - * Something which used to work in Linux 6.0 broke when switching to Linux - 6.1-rc1? Then henceforth regard 6.0 as the last known 'good' version - and 6.1-rc1 as the first 'bad' one. + * Something regressed when updating from a stable/longterm release + (say 6.0.13) to a newer mainline series (like 6.1-rc7 or 6.1) or a + stable/longterm version based on one (say 6.1.5)? Then consider the + mainline release your working kernel is based on to be the 'good' + version (e.g. 6.0) and the first version to be broken as the 'bad' one + (e.g. 6.1-rc7, 6.1, or 6.1.5). Note, at this point it is merely assumed + that 6.0 is fine; this hypothesis will be checked in segment 2. - * Some function stopped working when updating from 6.0.11 to 6.1.4? Then for - the time being consider 6.0 as the last 'good' version and 6.1.4 as - the 'bad' one. Note, at this point it is merely assumed that 6.0 is fine; - this assumption will be checked in segment 2. + * Something regressed when switching from one mainline version (say 6.0) to + a later one (like 6.1-rc1) or a stable/longterm release based on it + (say 6.1.5)? Then regard the last working version (e.g. 6.0) as 'good' and + the first broken (e.g. 6.1-rc1 or 6.1.5) as 'bad'. - * A feature you used in 6.0.11 does not work at all or worse in 6.1.13? In - that case you want to bisect within a stable/longterm series: consider - 6.0.11 as the last known 'good' version and 6.0.13 as the first 'bad' - one. Note, in this case you still want to compile and test a mainline kernel - as explained in segment 1: the outcome will determine if you need to report - your issue to the regular developers or the stable team. + * Something regressed when updating within a stable/longterm series (say + from 6.0.13 to 6.0.15)? Then consider those versions as 'good' and 'bad' + (e.g. 6.0.13 and 6.0.15), as you need to bisect within that series. *Note, do not confuse 'good' version with 'working' kernel; the latter term throughout this guide will refer to the last kernel that has been working fine.* - [:ref:`details<rangecheck_bisref>`] + [:ref:`details <rangecheck_bisref>`] .. _bootworking_bissbs: * Boot into the 'working' kernel and briefly use the apparently broken feature. - [:ref:`details<bootworking_bisref>`] + [:ref:`details <bootworking_bisref>`] .. _diskspace_bissbs: @@ -327,7 +356,7 @@ Preparations: set up everything to build your own kernels debug symbols: both explain approaches reducing the amount of space, which should allow you to master these tasks with about 4 Gigabytes free space. - [:ref:`details<diskspace_bisref>`] + [:ref:`details <diskspace_bisref>`] .. _buildrequires_bissbs: @@ -337,7 +366,7 @@ Preparations: set up everything to build your own kernels reference section shows how to quickly install those on various popular Linux distributions. - [:ref:`details<buildrequires_bisref>`] + [:ref:`details <buildrequires_bisref>`] .. _sources_bissbs: @@ -360,14 +389,23 @@ Preparations: set up everything to build your own kernels git remote add -t master stable \ https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git - [:ref:`details<sources_bisref>`] + [:ref:`details <sources_bisref>`] + +.. _stablesources_bissbs: + +* Is one of the versions you earlier established as 'good' or 'bad' a stable or + longterm release (say 6.1.5)? Then download the code for the series it belongs + to ('linux-6.1.y' in this example):: + + git remote set-branches --add stable linux-6.1.y + git fetch stable .. _oldconfig_bissbs: * Start preparing a kernel build configuration (the '.config' file). Before doing so, ensure you are still running the 'working' kernel an earlier - step told you to boot; if you are unsure, check the current kernel release + step told you to boot; if you are unsure, check the current kernelrelease identifier using ``uname -r``. Afterwards check out the source code for the version earlier established as @@ -375,7 +413,7 @@ Preparations: set up everything to build your own kernels the version number in this and all later Git commands needs to be prefixed with a 'v':: - git checkout --detach v6.0 + git switch --discard-changes --detach v6.0 Now create a build configuration file:: @@ -398,7 +436,7 @@ Preparations: set up everything to build your own kernels 'make olddefconfig' again and check if it now picked up the right config file as base. - [:ref:`details<oldconfig_bisref>`] + [:ref:`details <oldconfig_bisref>`] .. _localmodconfig_bissbs: @@ -432,7 +470,7 @@ Preparations: set up everything to build your own kernels spending much effort on, as long as it boots and allows to properly test the feature that causes trouble. - [:ref:`details<localmodconfig_bisref>`] + [:ref:`details <localmodconfig_bisref>`] .. _tagging_bissbs: @@ -442,7 +480,7 @@ Preparations: set up everything to build your own kernels ./scripts/config --set-str CONFIG_LOCALVERSION '-local' ./scripts/config -e CONFIG_LOCALVERSION_AUTO - [:ref:`details<tagging_bisref>`] + [:ref:`details <tagging_bisref>`] .. _debugsymbols_bissbs: @@ -461,7 +499,7 @@ Preparations: set up everything to build your own kernels ./scripts/config -d DEBUG_INFO -d DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT \ -d DEBUG_INFO_DWARF4 -d DEBUG_INFO_DWARF5 -e CONFIG_DEBUG_INFO_NONE - [:ref:`details<debugsymbols_bisref>`] + [:ref:`details <debugsymbols_bisref>`] .. _configmods_bissbs: @@ -471,14 +509,14 @@ Preparations: set up everything to build your own kernels * Are you running Debian? Then you want to avoid known problems by performing additional adjustments explained in the reference section. - [:ref:`details<configmods_distros_bisref>`]. + [:ref:`details <configmods_distros_bisref>`]. * If you want to influence other aspects of the configuration, do so now using your preferred tool. Note, to use make targets like 'menuconfig' or 'nconfig', you will need to install the development files of ncurses; for 'xconfig' you likewise need the Qt5 or Qt6 headers. - [:ref:`details<configmods_individual_bisref>`]. + [:ref:`details <configmods_individual_bisref>`]. .. _saveconfig_bissbs: @@ -488,7 +526,7 @@ Preparations: set up everything to build your own kernels make olddefconfig cp .config ~/kernel-config-working - [:ref:`details<saveconfig_bisref>`] + [:ref:`details <saveconfig_bisref>`] .. _introlatestcheck_bissbs: @@ -498,16 +536,30 @@ Segment 1: try to reproduce the problem with the latest codebase The following steps verify if the problem occurs with the code currently supported by developers. In case you face a regression, it also checks that the problem is not caused by some .config change, as reporting the issue then would -be a waste of time. [:ref:`details<introlatestcheck_bisref>`] +be a waste of time. [:ref:`details <introlatestcheck_bisref>`] .. _checkoutmaster_bissbs: -* Check out the latest Linux codebase:: +* Check out the latest Linux codebase. - cd ~/linux/ - git checkout --force --detach mainline/master + * Are your 'good' and 'bad' versions from the same stable or longterm series? + Then check the `front page of kernel.org <https://kernel.org/>`_: if it + lists a release from that series without an '[EOL]' tag, checkout the series + latest version ('linux-6.1.y' in the following example):: + + cd ~/linux/ + git switch --discard-changes --detach stable/linux-6.1.y + + Your series is unsupported, if is not listed or carrying a 'end of life' + tag. In that case you might want to check if a successor series (say + linux-6.2.y) or mainline (see next point) fix the bug. - [:ref:`details<checkoutmaster_bisref>`] + * In all other cases, run:: + + cd ~/linux/ + git switch --discard-changes --detach mainline/master + + [:ref:`details <checkoutmaster_bisref>`] .. _build_bissbs: @@ -522,7 +574,7 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] reference section for alternatives, which obviously will require other steps to install as well. - [:ref:`details<build_bisref>`] + [:ref:`details <build_bisref>`] .. _install_bissbs: @@ -555,7 +607,7 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] down: if you will build more kernels as described in segment 2 and 3, you will have to perform those again after executing ``command -v installkernel [...]``. - [:ref:`details<install_bisref>`] + [:ref:`details <install_bisref>`] .. _storagespace_bissbs: @@ -568,7 +620,7 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] Write down or remember those two values for later: they enable you to prevent running out of disk space accidentally during a bisection. - [:ref:`details<storagespace_bisref>`] + [:ref:`details <storagespace_bisref>`] .. _kernelrelease_bissbs: @@ -595,7 +647,7 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] If that command does not return '0', check the reference section, as the cause for this might interfere with your testing. - [:ref:`details<tainted_bisref>`] + [:ref:`details <tainted_bisref>`] .. _recheckbroken_bissbs: @@ -603,21 +655,19 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] out the instructions in the reference section to ensure nothing went sideways during your tests. - [:ref:`details<recheckbroken_bisref>`] + [:ref:`details <recheckbroken_bisref>`] .. _recheckstablebroken_bissbs: -* Are you facing a problem within a stable/longterm series, but failed to - reproduce it with the mainline kernel you just built? One that according to - the `front page of kernel.org <https://kernel.org/>`_ is still supported? Then - check if the latest codebase for the particular series might already fix the - problem. To do so, add the stable series Git branch for your 'good' kernel - (again, this here is assumed to be 6.0) and check out the latest version:: +* Did you just built a stable or longterm kernel? And were you able to reproduce + the regression with it? Then you should test the latest mainline codebase as + well, because the result determines which developers the bug must be submitted + to. + + To prepare that test, check out current mainline:: cd ~/linux/ - git remote set-branches --add stable linux-6.0.y - git fetch stable - git checkout --force --detach linux-6.0.y + git switch --discard-changes --detach mainline/master Now use the checked out code to build and install another kernel using the commands the earlier steps already described in more detail:: @@ -639,14 +689,16 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`] uname -r cat /proc/sys/kernel/tainted - Now verify if this kernel is showing the problem. + Now verify if this kernel is showing the problem. If it does, then you need + to report the bug to the primary developers; if it does not, report it to the + stable team. See Documentation/admin-guide/reporting-issues.rst for details. - [:ref:`details<recheckstablebroken_bisref>`] + [:ref:`details <recheckstablebroken_bisref>`] Do you follow this guide to verify if a problem is present in the code currently supported by Linux kernel developers? Then you are done at this point. If you later want to remove the kernel you just built, check out -:ref:`Supplementary tasks: cleanup during and after following this guide<introclosure_bissbs>`. +:ref:`Complementary tasks: cleanup during and after following this guide <introclosure_bissbs>`. In case you face a regression, move on and execute at least the next segment as well. @@ -658,7 +710,7 @@ Segment 2: check if the kernels you build work fine In case of a regression, you now want to ensure the trimmed configuration file you created earlier works as expected; a bisection with the .config file -otherwise would be a waste of time. [:ref:`details<introworkingcheck_bisref>`] +otherwise would be a waste of time. [:ref:`details <introworkingcheck_bisref>`] .. _recheckworking_bissbs: @@ -669,7 +721,7 @@ otherwise would be a waste of time. [:ref:`details<introworkingcheck_bisref>`] 'good' (once again assumed to be 6.0 here):: cd ~/linux/ - git checkout --detach v6.0 + git switch --discard-changes --detach v6.0 Now use the checked out code to configure, build, and install another kernel using the commands the previous subsection explained in more detail:: @@ -693,7 +745,7 @@ otherwise would be a waste of time. [:ref:`details<introworkingcheck_bisref>`] Now check if this kernel works as expected; if not, consult the reference section for further instructions. - [:ref:`details<recheckworking_bisref>`] + [:ref:`details <recheckworking_bisref>`] .. _introbisect_bissbs: @@ -703,18 +755,11 @@ Segment 3: perform the bisection and validate the result With all the preparations and precaution builds taken care of, you are now ready to begin the bisection. This will make you build quite a few kernels -- usually about 15 in case you encountered a regression when updating to a newer series -(say from 6.0.11 to 6.1.3). But do not worry, due to the trimmed build +(say from 6.0.13 to 6.1.5). But do not worry, due to the trimmed build configuration created earlier this works a lot faster than many people assume: overall on average it will often just take about 10 to 15 minutes to compile each kernel on commodity x86 machines. -* In case your 'bad' version is a stable/longterm release (say 6.1.5), add its - stable branch, unless you already did so earlier:: - - cd ~/linux/ - git remote set-branches --add stable linux-6.1.y - git fetch stable - .. _bisectstart_bissbs: * Start the bisection and tell Git about the versions earlier established as @@ -725,7 +770,7 @@ each kernel on commodity x86 machines. git bisect good v6.0 git bisect bad v6.1.5 - [:ref:`details<bisectstart_bisref>`] + [:ref:`details <bisectstart_bisref>`] .. _bisectbuild_bissbs: @@ -745,7 +790,7 @@ each kernel on commodity x86 machines. If compilation fails for some reason, run ``git bisect skip`` and restart executing the stack of commands from the beginning. - In case you skipped the "test latest codebase" step in the guide, check its + In case you skipped the 'test latest codebase' step in the guide, check its description as for why the 'df [...]' and 'make -s kernelrelease [...]' commands are here. @@ -754,7 +799,7 @@ each kernel on commodity x86 machines. totally normal to see release identifiers like '6.0-rc1-local-gcafec0cacaca0' if you bisect between versions 6.1 and 6.2 for example. - [:ref:`details<bisectbuild_bisref>`] + [:ref:`details <bisectbuild_bisref>`] .. _bisecttest_bissbs: @@ -794,7 +839,7 @@ each kernel on commodity x86 machines. might need to scroll up to see the message mentioning the culprit; alternatively, run ``git bisect log > ~/bisection-log``. - [:ref:`details<bisecttest_bisref>`] + [:ref:`details <bisecttest_bisref>`] .. _bisectlog_bissbs: @@ -806,7 +851,7 @@ each kernel on commodity x86 machines. cp .config ~/bisection-config-culprit git bisect reset - [:ref:`details<bisectlog_bisref>`] + [:ref:`details <bisectlog_bisref>`] .. _revert_bissbs: @@ -823,16 +868,16 @@ each kernel on commodity x86 machines. Begin by checking out the latest codebase depending on the range you bisected: * Did you face a regression within a stable/longterm series (say between - 6.0.11 and 6.0.13) that does not happen in mainline? Then check out the + 6.0.13 and 6.0.15) that does not happen in mainline? Then check out the latest codebase for the affected series like this:: git fetch stable - git checkout --force --detach linux-6.0.y + git switch --discard-changes --detach linux-6.0.y * In all other cases check out latest mainline:: git fetch mainline - git checkout --force --detach mainline/master + git switch --discard-changes --detach mainline/master If you bisected a regression within a stable/longterm series that also happens in mainline, there is one more thing to do: look up the mainline @@ -846,27 +891,33 @@ each kernel on commodity x86 machines. git revert --no-edit cafec0cacaca0 - If that fails, give up trying and move on to the next step. But if it works, - build a kernel again using the familiar command sequence:: + If that fails, give up trying and move on to the next step; if it works, + adjust the tag to facilitate the identification and prevent accidentally + overwriting another kernel:: cp ~/kernel-config-working .config + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted' + + Build a kernel using the familiar command sequence, just without copying the + the base .config over:: + make olddefconfig && - make -j $(nproc --all) && + make -j $(nproc --all) # * Check if the free space suffices holding another kernel: df -h /boot/ /lib/modules/ sudo make modules_install command -v installkernel && sudo make install - Make -s kernelrelease | tee -a ~/kernels-built + make -s kernelrelease | tee -a ~/kernels-built reboot - Now check one last time if the feature that made you perform a bisection work - with that kernel. + Now check one last time if the feature that made you perform a bisection works + with that kernel: if everything went well, it should not show the regression. - [:ref:`details<revert_bisref>`] + [:ref:`details <revert_bisref>`] .. _introclosure_bissbs: -Supplementary tasks: cleanup during and after the bisection +Complementary tasks: cleanup during and after the bisection ----------------------------------------------------------- During and after following this guide you might want or need to remove some of @@ -903,7 +954,7 @@ space might run out. kernel image and related files behind; in that case remove them as described in the reference section. - [:ref:`details<makeroom_bisref>`] + [:ref:`details <makeroom_bisref>`] .. _finishingtouch_bissbs: @@ -926,18 +977,99 @@ space might run out. the version considered 'good', and the last three or four you compiled during the actual bisection process. - [:ref:`details<finishingtouch_bisref>`] + [:ref:`details <finishingtouch_bisref>`] + +.. _introoptional_bissbs: + +Optional: test reverts, patches, or later versions +-------------------------------------------------- + +While or after reporting a bug, you might want or potentially will be asked to +test reverts, debug patches, proposed fixes, or other versions. In that case +follow these instructions. + +* Update your Git clone and check out the latest code. + + * In case you want to test mainline, fetch its latest changes before checking + its code out:: + + git fetch mainline + git switch --discard-changes --detach mainline/master + + * In case you want to test a stable or longterm kernel, first add the branch + holding the series you are interested in (6.2 in the example), unless you + already did so earlier:: + + git remote set-branches --add stable linux-6.2.y + + Then fetch the latest changes and check out the latest version from the + series:: + + git fetch stable + git switch --discard-changes --detach stable/linux-6.2.y + +* Copy your kernel build configuration over:: + + cp ~/kernel-config-working .config + +* Your next step depends on what you want to do: + + * In case you just want to test the latest codebase, head to the next step, + you are already all set. + + * In case you want to test if a revert fixes an issue, revert one or multiple + changes by specifying their commit ids:: + + git revert --no-edit cafec0cacaca0 + + Now give that kernel a special tag to facilitates its identification and + prevent accidentally overwriting another kernel:: + + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted' + + * In case you want to test a patch, store the patch in a file like + '/tmp/foobars-proposed-fix-v1.patch' and apply it like this:: + + git apply /tmp/foobars-proposed-fix-v1.patch + + In case of multiple patches, repeat this step with the others. + + Now give that kernel a special tag to facilitates its identification and + prevent accidentally overwriting another kernel:: + + ./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1' + +* Build a kernel using the familiar commands, just without copying the kernel + build configuration over, as that has been taken care of already:: + + make olddefconfig && + make -j $(nproc --all) + # * Check if the free space suffices holding another kernel: + df -h /boot/ /lib/modules/ + sudo make modules_install + command -v installkernel && sudo make install + make -s kernelrelease | tee -a ~/kernels-built + reboot + +* Now verify you booted the newly built kernel and check it. + +[:ref:`details <introoptional_bisref>`] .. _submit_improvements: -This concludes the step-by-step guide. +Conclusion +---------- + +You have reached the end of the step-by-step guide. Did you run into trouble following any of the above steps not cleared up by the reference section below? Did you spot errors? Or do you have ideas how to -improve the guide? Then please take a moment and let the maintainer of this +improve the guide? + +If any of that applies, please take a moment and let the maintainer of this document know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is -vital to improve this document further, which is in everybody's interest, as it +vital to improve this text further, which is in everybody's interest, as it will enable more people to master the task described here -- and hopefully also improve similar guides inspired by this one. @@ -948,10 +1080,20 @@ Reference section for the step-by-step guide This section holds additional information for almost all the items in the above step-by-step guide. +Preparations for building your own kernels +------------------------------------------ + + *The steps in this section lay the groundwork for all further tests.* + [:ref:`... <introprep_bissbs>`] + +The steps in all later sections of this guide depend on those described here. + +[:ref:`back to step-by-step guide <introprep_bissbs>`]. + .. _backup_bisref: Prepare for emergencies ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ *Create a fresh backup and put system repair and restore tools at hand.* [:ref:`... <backup_bissbs>`] @@ -966,7 +1108,7 @@ for something going sideways, even if that should not happen. .. _vanilla_bisref: Remove anything related to externally maintained kernel modules ---------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Remove all software that depends on externally developed kernel drivers or builds them automatically.* [:ref:`...<vanilla_bissbs>`] @@ -984,7 +1126,7 @@ explains in more detail. .. _secureboot_bisref: Deal with techniques like Secure Boot -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *On platforms with 'Secure Boot' or similar techniques, prepare everything to ensure the system will permit your self-compiled kernel to boot later.* @@ -1021,7 +1163,7 @@ Afterwards, permit MokManager to reboot the machine. .. _bootworking_bisref: Boot the last kernel that was working -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Boot into the last working kernel and briefly recheck if the feature that regressed really works.* [:ref:`...<bootworking_bissbs>`] @@ -1034,7 +1176,7 @@ the right thing. .. _diskspace_bisref: Space requirements ------------------- +~~~~~~~~~~~~~~~~~~ *Ensure to have enough free space for building Linux.* [:ref:`... <diskspace_bissbs>`] @@ -1052,32 +1194,32 @@ space by quite a few gigabytes. .. _rangecheck_bisref: Bisection range ---------------- +~~~~~~~~~~~~~~~ *Determine the kernel versions considered 'good' and 'bad' throughout this guide.* [:ref:`...<rangecheck_bissbs>`] Establishing the range of commits to be checked is mostly straightforward, except when a regression occurred when switching from a release of one stable -series to a release of a later series (e.g. from 6.0.11 to 6.1.4). In that case +series to a release of a later series (e.g. from 6.0.13 to 6.1.5). In that case Git will need some hand holding, as there is no straight line of descent. That's because with the release of 6.0 mainline carried on to 6.1 while the stable series 6.0.y branched to the side. It's therefore theoretically possible -that the issue you face with 6.1.4 only worked in 6.0.11, as it was fixed by a +that the issue you face with 6.1.5 only worked in 6.0.13, as it was fixed by a commit that went into one of the 6.0.y releases, but never hit mainline or the 6.1.y series. Thankfully that normally should not happen due to the way the stable/longterm maintainers maintain the code. It's thus pretty safe to assume 6.0 as a 'good' kernel. That assumption will be tested anyway, as that kernel will be built and tested in the segment '2' of this guide; Git would force you -to do this as well, if you tried bisecting between 6.0.11 and 6.1.13. +to do this as well, if you tried bisecting between 6.0.13 and 6.1.15. [:ref:`back to step-by-step guide <rangecheck_bissbs>`] .. _buildrequires_bisref: Install build requirements --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ *Install all software required to build a Linux kernel.* [:ref:`...<buildrequires_bissbs>`] @@ -1117,7 +1259,7 @@ These commands install a few packages that are often, but not always needed. You for example might want to skip installing the development headers for ncurses, which you will only need in case you later might want to adjust the kernel build configuration using make the targets 'menuconfig' or 'nconfig'; likewise omit -the headers of Qt6 is you do not plan to adjust the .config using 'xconfig'. +the headers of Qt6 if you do not plan to adjust the .config using 'xconfig'. You furthermore might need additional libraries and their development headers for tasks not covered in this guide -- for example when building utilities from @@ -1128,7 +1270,7 @@ the kernel's tools/ directory. .. _sources_bisref: Download the sources using Git ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Retrieve the Linux mainline sources.* [:ref:`...<sources_bissbs>`] @@ -1148,7 +1290,7 @@ work better for you: .. _sources_bundle_bisref: Downloading Linux mainline sources using a bundle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""""""""""""""""""""""""""" Use the following commands to retrieve the Linux mainline sources using a bundle:: @@ -1184,7 +1326,7 @@ First, execute the following command to retrieve the latest mainline codebase:: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git Now deepen your clone's history to the second predecessor of the mainline -release of your 'good' version. In case the latter are 6.0 or 6.0.11, 5.19 would +release of your 'good' version. In case the latter are 6.0 or 6.0.13, 5.19 would be the first predecessor and 5.18 the second -- hence deepen the history up to that version:: @@ -1219,7 +1361,7 @@ Note, shallow clones have a few peculiar characteristics: .. _oldconfig_bisref: Start defining the build configuration for your kernel ------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Start preparing a kernel build configuration (the '.config' file).* [:ref:`... <oldconfig_bissbs>`] @@ -1279,7 +1421,7 @@ that file to the build machine and store it as ~/linux/.config; afterwards run .. _localmodconfig_bisref: Trim the build configuration for your kernel --------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Disable any kernel modules apparently superfluous for your setup.* [:ref:`... <localmodconfig_bissbs>`] @@ -1328,7 +1470,7 @@ step-by-step guide mentions:: .. _tagging_bisref: Tag the kernels about to be build ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Ensure all the kernels you will build are clearly identifiable using a special tag and a unique version identifier.* [:ref:`... <tagging_bissbs>`] @@ -1344,7 +1486,7 @@ confusing during the bisection. .. _debugsymbols_bisref: Decide to enable or disable debug symbols ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Decide how to handle debug symbols.* [:ref:`... <debugsymbols_bissbs>`] @@ -1373,7 +1515,7 @@ explains this process in more detail. .. _configmods_bisref: Adjust build configuration --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ *Check if you may want or need to adjust some other kernel configuration options:* @@ -1384,7 +1526,7 @@ kernel configuration options. .. _configmods_distros_bisref: Distro specific adjustments -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""""" *Are you running* [:ref:`... <configmods_bissbs>`] @@ -1409,7 +1551,7 @@ when following this guide on a few commodity distributions. .. _configmods_individual_bisref: Individual adjustments -~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""" *If you want to influence the other aspects of the configuration, do so now.* [:ref:`... <configmods_bissbs>`] @@ -1426,13 +1568,13 @@ is missing. .. _saveconfig_bisref: Put the .config file aside --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ *Reprocess the .config after the latest changes and store it in a safe place.* [:ref:`... <saveconfig_bissbs>`] Put the .config you prepared aside, as you want to copy it back to the build -directory every time during this guide before you start building another +directory every time during this guide before you start building another kernel. That's because going back and forth between different versions can alter .config files in odd ways; those occasionally cause side effects that could confuse testing or in some cases render the result of your bisection @@ -1442,8 +1584,8 @@ meaningless. .. _introlatestcheck_bisref: -Try to reproduce the regression ------------------------------------------ +Try to reproduce the problem with the latest codebase +----------------------------------------------------- *Verify the regression is not caused by some .config change and check if it still occurs with the latest codebase.* [:ref:`... <introlatestcheck_bissbs>`] @@ -1490,28 +1632,28 @@ highly recommended for these reasons: Your report might be ignored if you send it to the wrong party -- and even when you get a reply there is a decent chance that developers tell you to - evaluate which of the two cases it is before they take a closer look. + evaluate which of the two cases it is before they take a closer look. [:ref:`back to step-by-step guide <introlatestcheck_bissbs>`] .. _checkoutmaster_bisref: Check out the latest Linux codebase ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Check out the latest Linux codebase.* - [:ref:`... <introlatestcheck_bissbs>`] + [:ref:`... <checkoutmaster_bissbs>`] In case you later want to recheck if an ever newer codebase might fix the problem, remember to run that ``git fetch --shallow-exclude [...]`` command again mentioned earlier to update your local Git repository. -[:ref:`back to step-by-step guide <introlatestcheck_bissbs>`] +[:ref:`back to step-by-step guide <checkoutmaster_bissbs>`] .. _build_bisref: Build your kernel ------------------ +~~~~~~~~~~~~~~~~~ *Build the image and the modules of your first kernel using the config file you prepared.* [:ref:`... <build_bissbs>`] @@ -1521,7 +1663,7 @@ yourself. Another subsection explains how to directly package your kernel up as deb, rpm or tar file. Dealing with build errors -~~~~~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""""""" When a build error occurs, it might be caused by some aspect of your machine's setup that often can be fixed quickly; other times though the problem lies in @@ -1552,11 +1694,11 @@ by modifying your search terms or using another line from the error messages. In the end, most issues you run into have likely been encountered and reported by others already. That includes issues where the cause is not your -system, but lies in the code. If you run into one of those, you might thus find a -solution (e.g. a patch) or workaround for your issue, too. +system, but lies in the code. If you run into one of those, you might thus find +a solution (e.g. a patch) or workaround for your issue, too. Package your kernel up -~~~~~~~~~~~~~~~~~~~~~~ +"""""""""""""""""""""" The step-by-step guide uses the default make targets (e.g. 'bzImage' and 'modules' on x86) to build the image and the modules of your kernel, which later @@ -1587,7 +1729,7 @@ distribution's kernel packages. .. _install_bisref: Put the kernel in place ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ *Install the kernel you just built.* [:ref:`... <install_bissbs>`] @@ -1630,7 +1772,7 @@ process. Afterwards add your kernel to your bootloader configuration and reboot. .. _storagespace_bisref: Storage requirements per kernel -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Check how much storage space the kernel, its modules, and other related files like the initramfs consume.* [:ref:`... <storagespace_bissbs>`] @@ -1651,7 +1793,7 @@ need to look in different places. .. _tainted_bisref: Check if your newly built kernel considers itself 'tainted' ------------------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Check if the kernel marked itself as 'tainted'.* [:ref:`... <tainted_bissbs>`] @@ -1670,7 +1812,7 @@ interest, as your testing might be flawed otherwise. .. _recheckbroken_bisref: Check the kernel built from a recent mainline codebase ------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Verify if your bug occurs with the newly built kernel.* [:ref:`... <recheckbroken_bissbs>`] @@ -1696,7 +1838,7 @@ the kernel you built from the latest codebase. These are the most frequent: .. _recheckstablebroken_bisref: Check the kernel built from the latest stable/longterm codebase ---------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Are you facing a regression within a stable/longterm release, but failed to reproduce it with the kernel you just built using the latest mainline sources? @@ -1741,7 +1883,7 @@ ensure the kernel version you assumed to be 'good' earlier in the process (e.g. .. _recheckworking_bisref: Build your own version of the 'good' kernel -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Build your own variant of the working kernel and check if the feature that regressed works as expected with it.* [:ref:`... <recheckworking_bissbs>`] @@ -1767,15 +1909,25 @@ multitude of reasons why this might happen. Some ideas where to look: Note, if you found and fixed problems with the .config file, you want to use it to build another kernel from the latest codebase, as your earlier tests with -mainline and the latest version from an affected stable/longterm series were most -likely flawed. +mainline and the latest version from an affected stable/longterm series were +most likely flawed. [:ref:`back to step-by-step guide <recheckworking_bissbs>`] +Perform a bisection and validate the result +------------------------------------------- + + *With all the preparations and precaution builds taken care of, you are now + ready to begin the bisection.* [:ref:`... <introbisect_bissbs>`] + +The steps in this segment perform and validate the bisection. + +[:ref:`back to step-by-step guide <introbisect_bissbs>`]. + .. _bisectstart_bisref: Start the bisection -------------------- +~~~~~~~~~~~~~~~~~~~ *Start the bisection and tell Git about the versions earlier established as 'good' and 'bad'.* [:ref:`... <bisectstart_bissbs>`] @@ -1789,7 +1941,7 @@ for you to test. .. _bisectbuild_bisref: Build a kernel from the bisection point ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *Build, install, and boot a kernel from the code Git checked out using the same commands you used earlier.* [:ref:`... <bisectbuild_bissbs>`] @@ -1817,7 +1969,7 @@ There are two things worth of note here: .. _bisecttest_bisref: Bisection checkpoint --------------------- +~~~~~~~~~~~~~~~~~~~~ *Check if the feature that regressed works in the kernel you just built.* [:ref:`... <bisecttest_bissbs>`] @@ -1831,7 +1983,7 @@ will be for nothing. .. _bisectlog_bisref: Put the bisection log away --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ *Store Git's bisection log and the current .config file in a safe place.* [:ref:`... <bisectlog_bissbs>`] @@ -1851,7 +2003,7 @@ ask for it after you report the regression. .. _revert_bisref: Try reverting the culprit -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ *Try reverting the culprit on top of the latest codebase to see if this fixes your regression.* [:ref:`... <revert_bissbs>`] @@ -1869,14 +2021,20 @@ succeeds, test that kernel version instead. [:ref:`back to step-by-step guide <revert_bissbs>`] +Cleanup steps during and after following this guide +--------------------------------------------------- -Supplementary tasks: cleanup during and after the bisection ------------------------------------------------------------ + *During and after following this guide you might want or need to remove some + of the kernels you installed.* [:ref:`... <introclosure_bissbs>`] + +The steps in this section describe clean-up procedures. + +[:ref:`back to step-by-step guide <introclosure_bissbs>`]. .. _makeroom_bisref: Cleaning up during the bisection --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *To remove one of the kernels you installed, look up its 'kernelrelease' identifier.* [:ref:`... <makeroom_bissbs>`] @@ -1911,13 +2069,13 @@ Now remove the boot entry for the kernel from your bootloader's configuration; the steps to do that vary quite a bit between Linux distributions. Note, be careful with wildcards like '*' when deleting files or directories -for kernels manually: you might accidentally remove files of a 6.0.11 kernel +for kernels manually: you might accidentally remove files of a 6.0.13 kernel when all you want is to remove 6.0 or 6.0.1. [:ref:`back to step-by-step guide <makeroom_bissbs>`] Cleaning up after the bisection -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _finishingtouch_bisref: @@ -1932,26 +2090,105 @@ build artifacts and the Linux sources, but will leave the Git repository (~/linux/.git/) behind -- a simple ``git reset --hard`` thus will bring the sources back. -Removing the repository as well would likely be unwise at this point: there is a -decent chance developers will ask you to build another kernel to perform -additional tests. This is often required to debug an issue or check proposed -fixes. Before doing so you want to run the ``git fetch mainline`` command again -followed by ``git checkout mainline/master`` to bring your clone up to date and -checkout the latest codebase. Then apply the patch using ``git apply -<filename>`` or ``git am <filename>`` and build yet another kernel using the -familiar commands. +Removing the repository as well would likely be unwise at this point: there +is a decent chance developers will ask you to build another kernel to +perform additional tests -- like testing a debug patch or a proposed fix. +Details on how to perform those can be found in the section :ref:`Optional +tasks: test reverts, patches, or later versions <introoptional_bissbs>`. Additional tests are also the reason why you want to keep the ~/kernel-config-working file around for a few weeks. [:ref:`back to step-by-step guide <finishingtouch_bissbs>`] +.. _introoptional_bisref: -Additional reading material -=========================== +Test reverts, patches, or later versions +---------------------------------------- + + *While or after reporting a bug, you might want or potentially will be asked + to test reverts, patches, proposed fixes, or other versions.* + [:ref:`... <introoptional_bissbs>`] + +All the commands used in this section should be pretty straight forward, so +there is not much to add except one thing: when setting a kernel tag as +instructed, ensure it is not much longer than the one used in the example, as +problems will arise if the kernelrelease identifier exceeds 63 characters. + +[:ref:`back to step-by-step guide <introoptional_bissbs>`]. + + +Additional information +====================== + +.. _buildhost_bis: + +Build kernels on a different machine +------------------------------------ + +To compile kernels on another system, slightly alter the step-by-step guide's +instructions: + +* Start following the guide on the machine where you want to install and test + the kernels later. + +* After executing ':ref:`Boot into the working kernel and briefly use the + apparently broken feature <bootworking_bissbs>`', save the list of loaded + modules to a file using ``lsmod > ~/test-machine-lsmod``. Then locate the + build configuration for the running kernel (see ':ref:`Start defining the + build configuration for your kernel <oldconfig_bisref>`' for hints on where + to find it) and store it as '~/test-machine-config-working'. Transfer both + files to the home directory of your build host. + +* Continue the guide on the build host (e.g. with ':ref:`Ensure to have enough + free space for building [...] <diskspace_bissbs>`'). + +* When you reach ':ref:`Start preparing a kernel build configuration[...] + <oldconfig_bissbs>`': before running ``make olddefconfig`` for the first time, + execute the following command to base your configuration on the one from the + test machine's 'working' kernel:: + + cp ~/test-machine-config-working ~/linux/.config + +* During the next step to ':ref:`disable any apparently superfluous kernel + modules <localmodconfig_bissbs>`' use the following command instead:: -Further sources ---------------- + yes '' | make localmodconfig LSMOD=~/lsmod_foo-machine localmodconfig + +* Continue the guide, but ignore the instructions outlining how to compile, + install, and reboot into a kernel every time they come up. Instead build + like this:: + + cp ~/kernel-config-working .config + make olddefconfig && + make -j $(nproc --all) targz-pkg + + This will generate a gzipped tar file whose name is printed in the last + line shown; for example, a kernel with the kernelrelease identifier + '6.0.0-rc1-local-g928a87efa423' built for x86 machines usually will + be stored as '~/linux/linux-6.0.0-rc1-local-g928a87efa423-x86.tar.gz'. + + Copy that file to your test machine's home directory. + +* Switch to the test machine to check if you have enough space to hold another + kernel. Then extract the file you transferred:: + + sudo tar -xvzf ~/linux-6.0.0-rc1-local-g928a87efa423-x86.tar.gz -C / + + Afterwards :ref:`generate the initramfs and add the kernel to your boot + loader's configuration <install_bisref>`; on some distributions the following + command will take care of both these tasks:: + + sudo /sbin/installkernel 6.0.0-rc1-local-g928a87efa423 /boot/vmlinuz-6.0.0-rc1-local-g928a87efa423 + + Now reboot and ensure you started the intended kernel. + +This approach even works when building for another architecture: just install +cross-compilers and add the appropriate parameters to every invocation of make +(e.g. ``make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- [...]``). + +Additional reading material +--------------------------- * The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and `fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_ diff --git a/Documentation/arch/m68k/buddha-driver.rst b/Documentation/arch/m68k/buddha-driver.rst index 20e401413991..5d1bc824978b 100644 --- a/Documentation/arch/m68k/buddha-driver.rst +++ b/Documentation/arch/m68k/buddha-driver.rst @@ -173,7 +173,7 @@ When accessing IDE registers with A6=1 (for example $84x), the timing will always be mode 0 8-bit compatible, no matter what you have selected in the speed register: -781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. +781ns select, IOR/IOW after 4 clock cycles (=314ns) active. All the timings with a very short select-signal (the 355ns fast accesses) depend on the accelerator card used in the diff --git a/Documentation/arch/s390/index.rst b/Documentation/arch/s390/index.rst index 73c79bf586fd..e75a6e5d2505 100644 --- a/Documentation/arch/s390/index.rst +++ b/Documentation/arch/s390/index.rst @@ -8,6 +8,7 @@ s390 Architecture cds 3270 driver-model + mm monreader qeth s390dbf diff --git a/Documentation/arch/s390/mm.rst b/Documentation/arch/s390/mm.rst new file mode 100644 index 000000000000..084adad5eef9 --- /dev/null +++ b/Documentation/arch/s390/mm.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +Memory Management +================= + +Virtual memory layout +===================== + +.. note:: + + - Some aspects of the virtual memory layout setup are not + clarified (number of page levels, alignment, DMA memory). + + - Unused gaps in the virtual memory layout could be present + or not - depending on how partucular system is configured. + No page tables are created for the unused gaps. + + - The virtual memory regions are tracked or untracked by KASAN + instrumentation, as well as the KASAN shadow memory itself is + created only when CONFIG_KASAN configuration option is enabled. + +:: + + ============================================================================= + | Physical | Virtual | VM area description + ============================================================================= + +- 0 --------------+- 0 --------------+ + | | S390_lowcore | Low-address memory + | +- 8 KB -----------+ + | | | + | | | + | | ... unused gap | KASAN untracked + | | | + +- AMODE31_START --+- AMODE31_START --+ .amode31 rand. phys/virt start + |.amode31 text/data|.amode31 text/data| KASAN untracked + +- AMODE31_END ----+- AMODE31_END ----+ .amode31 rand. phys/virt end (<2GB) + | | | + | | | + +- __kaslr_offset_phys | kernel rand. phys start + | | | + | kernel text/data | | + | | | + +------------------+ | kernel phys end + | | | + | | | + | | | + | | | + +- ident_map_size -+ | + | | + | ... unused gap | KASAN untracked + | | + +- __identity_base + identity mapping start (>= 2GB) + | | + | identity | phys == virt - __identity_base + | mapping | virt == phys + __identity_base + | | + | | KASAN tracked + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + +---- vmemmap -----+ 'struct page' array start + | | + | virtually mapped | + | memory map | KASAN untracked + | | + +- __abs_lowcore --+ + | | + | Absolute Lowcore | KASAN untracked + | | + +- __memcpy_real_area + | | + | Real Memory Copy| KASAN untracked + | | + +- VMALLOC_START --+ vmalloc area start + | | KASAN untracked or + | vmalloc area | KASAN shallowly populated in case + | | CONFIG_KASAN_VMALLOC=y + +- MODULES_VADDR --+ modules area start + | | KASAN allocated per module or + | modules area | KASAN shallowly populated in case + | | CONFIG_KASAN_VMALLOC=y + +- __kaslr_offset -+ kernel rand. virt start + | | KASAN tracked + | kernel text/data | phys == (kvirt - __kaslr_offset) + + | | __kaslr_offset_phys + +- kernel .bss end + kernel rand. virt end + | | + | ... unused gap | KASAN untracked + | | + +------------------+ UltraVisor Secure Storage limit + | | + | ... unused gap | KASAN untracked + | | + +KASAN_SHADOW_START+ KASAN shadow memory start + | | + | KASAN shadow | KASAN untracked + | | + +------------------+ ASCE limit diff --git a/Documentation/arch/s390/vfio-ap.rst b/Documentation/arch/s390/vfio-ap.rst index 929ee1c1c940..ea744cbc8687 100644 --- a/Documentation/arch/s390/vfio-ap.rst +++ b/Documentation/arch/s390/vfio-ap.rst @@ -380,6 +380,36 @@ matrix device. control_domains: A read-only file for displaying the control domain numbers assigned to the vfio_ap mediated device. + ap_config: + A read/write file that, when written to, allows all three of the + vfio_ap mediated device's ap matrix masks to be replaced in one shot. + Three masks are given, one for adapters, one for domains, and one for + control domains. If the given state cannot be set then no changes are + made to the vfio-ap mediated device. + + The format of the data written to ap_config is as follows: + {amask},{dmask},{cmask}\n + + \n is a newline character. + + amask, dmask, and cmask are masks identifying which adapters, domains, + and control domains should be assigned to the mediated device. + + The format of a mask is as follows: + 0xNN..NN + + Where NN..NN is 64 hexadecimal characters representing a 256-bit value. + The leftmost (highest order) bit represents adapter/domain 0. + + For an example set of masks that represent your mdev's current + configuration, simply cat ap_config. + + Setting an adapter or domain number greater than the maximum allowed for + the system will result in an error. + + This attribute is intended to be used by automation. End users would be + better served using the respective assign/unassign attributes for + adapters, domains, and control domains. * functions: @@ -550,7 +580,7 @@ These are the steps: following Kconfig elements selected: * IOMMU_SUPPORT * S390 - * ZCRYPT + * AP * VFIO * KVM diff --git a/Documentation/arch/sparc/oradax/dax-hv-api.txt b/Documentation/arch/sparc/oradax/dax-hv-api.txt index 7ecd0bf4957b..ef1a4c2bf08b 100644 --- a/Documentation/arch/sparc/oradax/dax-hv-api.txt +++ b/Documentation/arch/sparc/oradax/dax-hv-api.txt @@ -41,7 +41,7 @@ Chapter 36. Coprocessor services submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would not be a guarantee that a future submission would succeed. - The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual + The availability of DAX coprocessor command service is indicated by the presence of the DAX virtual device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst index 3712d81cb50c..6c245582d8fb 100644 --- a/Documentation/arch/x86/resctrl.rst +++ b/Documentation/arch/x86/resctrl.rst @@ -574,7 +574,7 @@ Memory b/w domain is L3 cache. MB:<cache_id0>=bandwidth0;<cache_id1>=bandwidth1;... Memory bandwidth Allocation specified in MiBps ---------------------------------------------- +---------------------------------------------- Memory bandwidth domain is L3 cache. :: diff --git a/Documentation/arch/x86/xstate.rst b/Documentation/arch/x86/xstate.rst index ae5c69e48b11..cec05ac464c1 100644 --- a/Documentation/arch/x86/xstate.rst +++ b/Documentation/arch/x86/xstate.rst @@ -138,7 +138,7 @@ Note this example does not include the sigaltstack preparation. Dynamic features in signal frames --------------------------------- -Dynamcally enabled features are not written to the signal frame upon signal +Dynamically enabled features are not written to the signal frame upon signal entry if the feature is in its initial configuration. This differs from non-dynamic features which are always written regardless of their configuration. Signal handlers can examine the XSAVE buffer's XSTATE_BV diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index d7adc6d543db..bee3b1bca9a7 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -171,14 +171,14 @@ The rule of thumb: - RMW operations that are conditional are unordered on FAILURE, otherwise the above rules apply. -Except of course when an operation has an explicit ordering like: +Except of course when a successful operation has an explicit ordering like: {}_relaxed: unordered {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE {}_release: the W of the RMW (or atomic_set) is a RELEASE Where 'unordered' is against other memory locations. Address dependencies are -not defeated. +not defeated. Conditional operations are still unordered on FAILURE. Fully ordered primitives are ordered against everything prior and everything subsequent. Therefore a fully ordered primitive is like having an smp_mb() diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-api/dma-api-howto.rst index e8a55f9d61db..0bf31b6c4383 100644 --- a/Documentation/core-api/dma-api-howto.rst +++ b/Documentation/core-api/dma-api-howto.rst @@ -203,13 +203,33 @@ setting the DMA mask fails. In this manner, if a user of your driver reports that performance is bad or that the device is not even detected, you can ask them for the kernel messages to find out exactly why. -The standard 64-bit addressing device would do something like this:: +The 24-bit addressing device would do something like this:: - if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) { + if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(24))) { dev_warn(dev, "mydev: No suitable DMA available\n"); goto ignore_this_device; } +The standard 64-bit addressing device would do something like this:: + + dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)) + +dma_set_mask_and_coherent() never return fail when DMA_BIT_MASK(64). Typical +error code like:: + + /* Wrong code */ + if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) + dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32)) + +dma_set_mask_and_coherent() will never return failure when bigger than 32. +So typical code like:: + + /* Recommended code */ + if (support_64bit) + dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64)); + else + dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32)); + If the device only supports 32-bit addressing for descriptors in the coherent allocations, but supports full 64-bits for streaming mappings it would look like this:: diff --git a/Documentation/core-api/entry.rst b/Documentation/core-api/entry.rst index e12f22ab33c7..a15f9b1767a2 100644 --- a/Documentation/core-api/entry.rst +++ b/Documentation/core-api/entry.rst @@ -18,7 +18,7 @@ exceptions`_, `NMI and NMI-like exceptions`_. Non-instrumentable code - noinstr --------------------------------- -Most instrumentation facilities depend on RCU, so intrumentation is prohibited +Most instrumentation facilities depend on RCU, so instrumentation is prohibited for entry code before RCU starts watching and exit code after RCU stops watching. In addition, many architectures must save and restore register state, which means that (for example) a breakpoint in the breakpoint entry code would diff --git a/Documentation/core-api/printk-index.rst b/Documentation/core-api/printk-index.rst index 3062f37d119b..1979c5dd32fe 100644 --- a/Documentation/core-api/printk-index.rst +++ b/Documentation/core-api/printk-index.rst @@ -4,7 +4,7 @@ Printk Index ============ -There are many ways how to monitor the state of the system. One important +There are many ways to monitor the state of the system. One important source of information is the system log. It provides a lot of information, including more or less important warnings and error messages. @@ -101,7 +101,7 @@ their own wrappers adding __printk_index_emit(). Only few subsystem specific wrappers have been updated so far, for example, dev_printk(). As a result, the printk formats from -some subsystes can be missing in the printk index. +some subsystems can be missing in the printk index. Subsystem specific prefix diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index ed73c612174d..bcc370c876be 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -671,7 +671,7 @@ configuration, worker pools and how workqueues map to the pools: :: events_unbound unbound 9 9 10 10 8 events_freezable percpu 0 2 4 6 events_power_efficient percpu 0 2 4 6 - events_freezable_power_ percpu 0 2 4 6 + events_freezable_pwr_ef percpu 0 2 4 6 rcu_gp percpu 0 2 4 6 rcu_par_gp percpu 0 2 4 6 slub_flushwq percpu 0 2 4 6 @@ -694,7 +694,7 @@ Use tools/workqueue/wq_monitor.py to monitor workqueue operations: :: events_unbound 38306 0 0.1 - 7 - - events_freezable 0 0 0.0 0 0 - - events_power_efficient 29598 0 0.2 0 0 - - - events_freezable_power_ 10 0 0.0 0 0 - - + events_freezable_pwr_ef 10 0 0.0 0 0 - - sock_diag_events 0 0 0.0 0 0 - - total infl CPUtime CPUhog CMW/RPR mayday rescued @@ -704,7 +704,7 @@ Use tools/workqueue/wq_monitor.py to monitor workqueue operations: :: events_unbound 38322 0 0.1 - 7 - - events_freezable 0 0 0.0 0 0 - - events_power_efficient 29603 0 0.2 0 0 - - - events_freezable_power_ 10 0 0.0 0 0 - - + events_freezable_pwr_ef 10 0 0.0 0 0 - - sock_diag_events 0 0 0.0 0 0 - - ... diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 94b6802ab0ab..02143f060b22 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -91,6 +91,16 @@ the below options are available: behaviour when encountering a data race is deemed safe. Please see `"Marking Shared-Memory Accesses" in the LKMM`_ for more information. +* Similar to ``data_race(...)``, the type qualifier ``__data_racy`` can be used + to document that all data races due to accesses to a variable are intended + and should be ignored by KCSAN:: + + struct foo { + ... + int __data_racy stats_counter; + ... + }; + * Disabling data race detection for entire functions can be accomplished by using the function attribute ``__no_kcsan``:: diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst index 0aaf6ea53608..1619e5e5cc9c 100644 --- a/Documentation/dev-tools/testing-overview.rst +++ b/Documentation/dev-tools/testing-overview.rst @@ -104,6 +104,8 @@ Some of these tools are listed below: KASAN and can be used in production. See Documentation/dev-tools/kfence.rst * lockdep is a locking correctness validator. See Documentation/locking/lockdep-design.rst +* Runtime Verification (RV) supports checking specific behaviours for a given + subsystem. See Documentation/trace/rv/runtime-verification.rst * There are several other pieces of debug instrumentation in the kernel, many of which can be found in lib/Kconfig.debug diff --git a/Documentation/devicetree/bindings/access-controllers/access-controllers.yaml b/Documentation/devicetree/bindings/access-controllers/access-controllers.yaml new file mode 100644 index 000000000000..99e2865f0e46 --- /dev/null +++ b/Documentation/devicetree/bindings/access-controllers/access-controllers.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/access-controllers/access-controllers.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic Domain Access Controllers + +maintainers: + - Oleksii Moisieiev <oleksii_moisieiev@epam.com> + +description: |+ + Common access controllers properties + + Access controllers are in charge of stating which of the hardware blocks under + their responsibility (their domain) can be accesssed by which compartment. A + compartment can be a cluster of CPUs (or coprocessors), a range of addresses + or a group of hardware blocks. An access controller's domain is the set of + resources covered by the access controller. + + This device tree binding can be used to bind devices to their access + controller provided by access-controllers property. In this case, the device + is a consumer and the access controller is the provider. + + An access controller can be represented by any node in the device tree and + can provide one or more configuration parameters, needed to control parameters + of the consumer device. A consumer node can refer to the provider by phandle + and a set of phandle arguments, specified by '#access-controller-cells' + property in the access controller node. + + Access controllers are typically used to set/read the permissions of a + hardware block and grant access to it. Any of which depends on the access + controller. The capabilities of each access controller are defined by the + binding of the access controller device. + + Each node can be a consumer for the several access controllers. + +# always select the core schema +select: true + +properties: + "#access-controller-cells": + description: + Number of cells in an access-controllers specifier; + Can be any value as specified by device tree binding documentation + of a particular provider. The node is an access controller. + + access-controller-names: + $ref: /schemas/types.yaml#/definitions/string-array + description: + A list of access-controllers names, sorted in the same order as + access-controllers entries. Consumer drivers will use + access-controller-names to match with existing access-controllers entries. + + access-controllers: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + A list of access controller specifiers, as defined by the + bindings of the access-controllers provider. + +additionalProperties: true + +examples: + - | + clock_controller: access-controllers@50000 { + reg = <0x50000 0x400>; + #access-controller-cells = <2>; + }; + + bus_controller: bus@60000 { + reg = <0x60000 0x10000>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + #access-controller-cells = <3>; + + uart4: serial@60100 { + reg = <0x60100 0x400>; + clocks = <&clk_serial>; + access-controllers = <&clock_controller 1 2>, + <&bus_controller 1 3 5>; + access-controller-names = "clock", "bus"; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml index 4cc4e6754681..d925e7a3b5ef 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.yaml @@ -53,6 +53,7 @@ properties: - description: BCM4709 based boards items: - enum: + - asus,rt-ac3200 - asus,rt-ac87u - buffalo,wxr-1900dhp - linksys,ea9200 @@ -67,6 +68,7 @@ properties: items: - enum: - asus,rt-ac3100 + - asus,rt-ac5300 - asus,rt-ac88u - dlink,dir-885l - dlink,dir-890l diff --git a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml index 39e3c248f5b7..1f84407a73e4 100644 --- a/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml +++ b/Documentation/devicetree/bindings/arm/bcm/raspberrypi,bcm2835-firmware.yaml @@ -46,6 +46,30 @@ properties: - compatible - "#clock-cells" + gpio: + type: object + additionalProperties: false + + properties: + compatible: + const: raspberrypi,firmware-gpio + + gpio-controller: true + + "#gpio-cells": + const: 2 + description: + The first cell is the pin number, and the second cell is used to + specify the gpio polarity (GPIO_ACTIVE_HIGH or GPIO_ACTIVE_LOW). + + gpio-line-names: + minItems: 8 + + required: + - compatible + - gpio-controller + - "#gpio-cells" + reset: type: object additionalProperties: false @@ -96,6 +120,12 @@ examples: #clock-cells = <1>; }; + expgpio: gpio { + compatible = "raspberrypi,firmware-gpio"; + gpio-controller; + #gpio-cells = <2>; + }; + reset: reset { compatible = "raspberrypi,firmware-reset"; #reset-cells = <1>; diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 0027201e19f8..6d185d09cb6a 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -813,6 +813,14 @@ properties: - const: tq,imx6ull-tqma6ull2l # MCIMX6Y2, LGA SoM variant - const: fsl,imx6ull + - description: Seeed Stuido i.MX6ULL SoM on dev boards + items: + - enum: + - seeed,imx6ull-seeed-npi-emmc + - seeed,imx6ull-seeed-npi-nand + - const: seeed,imx6ull-seeed-npi + - const: fsl,imx6ull + - description: i.MX6ULZ based Boards items: - enum: @@ -1050,6 +1058,7 @@ properties: - enum: - beacon,imx8mp-beacon-kit # i.MX8MP Beacon Development Kit - dmo,imx8mp-data-modul-edm-sbc # i.MX8MP eDM SBC + - emcraft,imx8mp-navqp # i.MX8MP Emcraft Systems NavQ+ Kit - fsl,imx8mp-evk # i.MX8MP EVK Board - gateworks,imx8mp-gw71xx-2x # i.MX8MP Gateworks Board - gateworks,imx8mp-gw72xx-2x # i.MX8MP Gateworks Board @@ -1218,7 +1227,6 @@ properties: - enum: - einfochips,imx8qxp-ai_ml # i.MX8QXP AI_ML Board - fsl,imx8qxp-mek # i.MX8QXP MEK Board - - toradex,colibri-imx8x # Colibri iMX8X Modules - const: fsl,imx8qxp - description: i.MX8DXL based Boards @@ -1227,7 +1235,7 @@ properties: - fsl,imx8dxl-evk # i.MX8DXL EVK Board - const: fsl,imx8dxl - - description: i.MX8QXP Boards with Toradex Colibri iMX8X Modules + - description: i.MX8QXP/i.MX8DX Boards with Toradex Colibri iMX8X Modules items: - enum: - toradex,colibri-imx8x-aster # Colibri iMX8X Module on Aster Board @@ -1235,7 +1243,9 @@ properties: - toradex,colibri-imx8x-iris # Colibri iMX8X Module on Iris Board - toradex,colibri-imx8x-iris-v2 # Colibri iMX8X Module on Iris Board V2 - const: toradex,colibri-imx8x - - const: fsl,imx8qxp + - enum: + - fsl,imx8qxp + - fsl,imx8dx - description: TQMa8Xx is a series of SOM featuring NXP i.MX8X system-on-chip @@ -1536,6 +1546,12 @@ properties: - nxp,s32g274a-rdb2 - const: nxp,s32g2 + - description: S32G3 based Boards + items: + - enum: + - nxp,s32g399a-rdb3 + - const: nxp,s32g3 + - description: S32V234 based Boards items: - enum: diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml index c24ad0968f3e..7f06b1080244 100644 --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.yaml @@ -61,10 +61,6 @@ properties: mboxes: minItems: 2 - ti,system-reboot-controller: - description: Determines If system reboot can be triggered by SoC reboot - type: boolean - ti,host-id: $ref: /schemas/types.yaml#/definitions/uint32 description: | @@ -94,7 +90,6 @@ examples: - | pmmc: system-controller@2921800 { compatible = "ti,k2g-sci"; - ti,system-reboot-controller; mbox-names = "rx", "tx"; mboxes = <&msgmgr 5 2>, <&msgmgr 0 0>; diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 66beaac60e1d..ae885414b181 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -137,6 +137,7 @@ properties: - microsoft,dempsey - microsoft,makepeace - microsoft,moneypenny + - motorola,falcon - samsung,s3ve3g - const: qcom,msm8226 @@ -184,13 +185,16 @@ properties: - oneplus,bacon - samsung,klte - sony,xperia-castor + - sony,xperia-leo - const: qcom,msm8974pro - const: qcom,msm8974 - items: - - const: qcom,msm8916-mtp - - const: qcom,msm8916-mtp/1 - - const: qcom,msm8916 + - enum: + - samsung,kltechn + - const: samsung,klte + - const: qcom,msm8974pro + - const: qcom,msm8974 - items: - enum: @@ -200,6 +204,8 @@ properties: - gplus,fl8005a - huawei,g7 - longcheer,l8910 + - longcheer,l8150 + - qcom,msm8916-mtp - samsung,a3u-eur - samsung,a5u-eur - samsung,e5 @@ -221,11 +227,6 @@ properties: - const: qcom,msm8916 - items: - - const: longcheer,l8150 - - const: qcom,msm8916-v1-qrd/9-v1 - - const: qcom,msm8916 - - - items: - enum: - motorola,potter - xiaomi,daisy @@ -1003,6 +1004,7 @@ properties: - qcom,sm8550-hdk - qcom,sm8550-mtp - qcom,sm8550-qrd + - sony,pdx234 - const: qcom,sm8550 - items: diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index fcf7316ecd74..e04c213a0dee 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -49,6 +49,11 @@ properties: - anbernic,rg-arc-s - const: rockchip,rk3566 + - description: ArmSoM Sige7 board + items: + - const: armsom,sige7 + - const: rockchip,rk3588 + - description: Asus Tinker board items: - const: asus,rk3288-tinker @@ -198,6 +203,13 @@ properties: - const: firefly,rk3568-roc-pc - const: rockchip,rk3568 + - description: Forlinx FET3588-C SoM + items: + - enum: + - forlinx,ok3588-c + - const: forlinx,fet3588-c + - const: rockchip,rk3588 + - description: FriendlyElec NanoPi R2 series boards items: - enum: @@ -236,6 +248,11 @@ properties: - const: friendlyarm,nanopc-t6 - const: rockchip,rk3588 + - description: GameForce Chi + items: + - const: gameforce,chi + - const: rockchip,rk3326 + - description: GeekBuying GeekBox items: - const: geekbuying,geekbox @@ -631,7 +648,7 @@ properties: - const: phytec,rk3288-phycore-som - const: rockchip,rk3288 - - description: Pine64 PinebookPro + - description: Pine64 Pinebook Pro items: - const: pine64,pinebook-pro - const: rockchip,rk3399 @@ -644,7 +661,7 @@ properties: - const: pine64,pinenote - const: rockchip,rk3566 - - description: Pine64 PinePhonePro + - description: Pine64 PinePhone Pro items: - const: pine64,pinephone-pro - const: rockchip,rk3399 @@ -682,7 +699,7 @@ properties: - const: pine64,quartzpro64 - const: rockchip,rk3588 - - description: Pine64 SoQuartz SoM + - description: Pine64 SOQuartz items: - enum: - pine64,soquartz-blade @@ -700,12 +717,17 @@ properties: - powkiddy,x55 - const: rockchip,rk3566 + - description: Protonic MECSBC board + items: + - const: prt,mecsbc + - const: rockchip,rk3568 + - description: QNAP TS-433-4G 4-Bay NAS items: - const: qnap,ts433 - const: rockchip,rk3568 - - description: Radxa Compute Module 3(CM3) + - description: Radxa Compute Module 3 (CM3) items: - enum: - radxa,cm3-io @@ -767,22 +789,27 @@ properties: - const: radxa,rockpis - const: rockchip,rk3308 - - description: Radxa Rock2 Square + - description: Radxa Rock 2 Square items: - const: radxa,rock2-square - const: rockchip,rk3288 - - description: Radxa ROCK3 Model A + - description: Radxa ROCK 3A items: - const: radxa,rock3a - const: rockchip,rk3568 - - description: Radxa ROCK 5 Model A + - description: Radxa ROCK 3C + items: + - const: radxa,rock-3c + - const: rockchip,rk3566 + + - description: Radxa ROCK 5A items: - const: radxa,rock-5a - const: rockchip,rk3588s - - description: Radxa ROCK 5 Model B + - description: Radxa ROCK 5B items: - const: radxa,rock-5b - const: rockchip,rk3588 @@ -927,6 +954,11 @@ properties: - const: turing,rk1 - const: rockchip,rk3588 + - description: WolfVision PF5 mainboard + items: + - const: wolfvision,rk3568-pf5 + - const: rockchip,rk3568 + - description: Xunlong Orange Pi 5 Plus items: - const: xunlong,orangepi-5-plus diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index 09d835db6db5..c6d0d8d81ed4 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -56,6 +56,21 @@ properties: - const: anbernic,rg-nano - const: allwinner,sun8i-v3s + - description: Anbernic RG35XX (2024) + - items: + - const: anbernic,rg35xx-2024 + - const: allwinner,sun50i-h700 + + - description: Anbernic RG35XX Plus + - items: + - const: anbernic,rg35xx-plus + - const: allwinner,sun50i-h700 + + - description: Anbernic RG35XX H + - items: + - const: anbernic,rg35xx-h + - const: allwinner,sun50i-h700 + - description: Amarula A64 Relic items: - const: amarula,a64-relic @@ -774,6 +789,11 @@ properties: - const: pocketbook,touch-lux-3 - const: allwinner,sun5i-a13 + - description: PocketBook 614 Plus + items: + - const: pocketbook,614-plus + - const: allwinner,sun5i-a13 + - description: Point of View Protab2-IPS9 items: - const: pov,protab2-ips9 @@ -860,6 +880,11 @@ properties: - const: allwinner,sl631 - const: allwinner,sun8i-v3 + - description: Tanix TX1 + items: + - const: oranth,tanix-tx1 + - const: allwinner,sun50i-h616 + - description: Tanix TX6 items: - const: oranth,tanix-tx6 diff --git a/Documentation/devicetree/bindings/bus/st,stm32-etzpc.yaml b/Documentation/devicetree/bindings/bus/st,stm32-etzpc.yaml new file mode 100644 index 000000000000..d12b62a3a5a8 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/st,stm32-etzpc.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/st,stm32-etzpc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STM32 Extended TrustZone protection controller + +description: | + The ETZPC configures TrustZone security in a SoC having bus masters and + devices with programmable-security attributes (securable resources). + +maintainers: + - Gatien Chevallier <gatien.chevallier@foss.st.com> + +select: + properties: + compatible: + contains: + const: st,stm32-etzpc + required: + - compatible + +properties: + compatible: + items: + - const: st,stm32-etzpc + - const: simple-bus + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + + "#access-controller-cells": + const: 1 + description: + Contains the firewall ID associated to the peripheral. + +patternProperties: + "^.*@[0-9a-f]+$": + description: Peripherals + type: object + + additionalProperties: true + + required: + - access-controllers + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - "#access-controller-cells" + - ranges + +additionalProperties: false + +examples: + - | + // In this example, the usart2 device refers to rifsc as its access + // controller. + // Access rights are verified before creating devices. + + #include <dt-bindings/interrupt-controller/arm-gic.h> + #include <dt-bindings/clock/stm32mp13-clks.h> + #include <dt-bindings/reset/stm32mp13-resets.h> + + etzpc: bus@5c007000 { + compatible = "st,stm32-etzpc", "simple-bus"; + reg = <0x5c007000 0x400>; + #address-cells = <1>; + #size-cells = <1>; + #access-controller-cells = <1>; + ranges; + + usart2: serial@4c001000 { + compatible = "st,stm32h7-uart"; + reg = <0x4c001000 0x400>; + interrupts-extended = <&exti 27 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc USART2_K>; + resets = <&rcc USART2_R>; + wakeup-source; + dmas = <&dmamux1 43 0x400 0x5>, + <&dmamux1 44 0x400 0x1>; + dma-names = "rx", "tx"; + access-controllers = <&etzpc 17>; + }; + }; diff --git a/Documentation/devicetree/bindings/bus/st,stm32mp25-rifsc.yaml b/Documentation/devicetree/bindings/bus/st,stm32mp25-rifsc.yaml new file mode 100644 index 000000000000..20acd1a6b173 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/st,stm32mp25-rifsc.yaml @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bus/st,stm32mp25-rifsc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STM32 Resource isolation framework security controller + +maintainers: + - Gatien Chevallier <gatien.chevallier@foss.st.com> + +description: | + Resource isolation framework (RIF) is a comprehensive set of hardware blocks + designed to enforce and manage isolation of STM32 hardware resources like + memory and peripherals. + + The RIFSC (RIF security controller) is composed of three sets of registers, + each managing a specific set of hardware resources: + - RISC registers associated with RISUP logic (resource isolation device unit + for peripherals), assign all non-RIF aware peripherals to zero, one or + any security domains (secure, privilege, compartment). + - RIMC registers: associated with RIMU logic (resource isolation master + unit), assign all non RIF-aware bus master to one security domain by + setting secure, privileged and compartment information on the system bus. + Alternatively, the RISUP logic controlling the device port access to a + peripheral can assign target bus attributes to this peripheral master port + (supported attribute: CID). + - RISC registers associated with RISAL logic (resource isolation device unit + for address space - Lite version), assign address space subregions to one + security domains (secure, privilege, compartment). + +select: + properties: + compatible: + contains: + const: st,stm32mp25-rifsc + required: + - compatible + +properties: + compatible: + items: + - const: st,stm32mp25-rifsc + - const: simple-bus + + reg: + maxItems: 1 + + "#address-cells": + const: 1 + + "#size-cells": + const: 1 + + ranges: true + + "#access-controller-cells": + const: 1 + description: + Contains the firewall ID associated to the peripheral. + +patternProperties: + "^.*@[0-9a-f]+$": + description: Peripherals + type: object + + additionalProperties: true + + required: + - access-controllers + +required: + - compatible + - reg + - "#address-cells" + - "#size-cells" + - "#access-controller-cells" + - ranges + +additionalProperties: false + +examples: + - | + // In this example, the usart2 device refers to rifsc as its domain + // controller. + // Access rights are verified before creating devices. + + #include <dt-bindings/interrupt-controller/arm-gic.h> + + rifsc: bus@42080000 { + compatible = "st,stm32mp25-rifsc", "simple-bus"; + reg = <0x42080000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + #access-controller-cells = <1>; + ranges; + + usart2: serial@400e0000 { + compatible = "st,stm32h7-uart"; + reg = <0x400e0000 0x400>; + interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ck_flexgen_08>; + access-controllers = <&rifsc 32>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml index 1d2bcea41c85..caf442ead24b 100644 --- a/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml +++ b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml @@ -30,16 +30,18 @@ properties: - google,gs101-cmu-top - google,gs101-cmu-apm - google,gs101-cmu-misc + - google,gs101-cmu-hsi0 + - google,gs101-cmu-hsi2 - google,gs101-cmu-peric0 - google,gs101-cmu-peric1 clocks: minItems: 1 - maxItems: 3 + maxItems: 5 clock-names: minItems: 1 - maxItems: 3 + maxItems: 5 "#clock-cells": const: 1 @@ -76,6 +78,55 @@ allOf: properties: compatible: contains: + const: google,gs101-cmu-hsi0 + + then: + properties: + clocks: + items: + - description: External reference clock (24.576 MHz) + - description: HSI0 bus clock (from CMU_TOP) + - description: DPGTC (from CMU_TOP) + - description: USB DRD controller clock (from CMU_TOP) + - description: USB Display Port debug clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: bus + - const: dpgtc + - const: usb31drd + - const: usbdpdbg + + - if: + properties: + compatible: + contains: + enum: + - google,gs101-cmu-hsi2 + + then: + properties: + clocks: + items: + - description: External reference clock (24.576 MHz) + - description: High Speed Interface bus clock (from CMU_TOP) + - description: High Speed Interface pcie clock (from CMU_TOP) + - description: High Speed Interface ufs clock (from CMU_TOP) + - description: High Speed Interface mmc clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: bus + - const: pcie + - const: ufs + - const: mmc + + - if: + properties: + compatible: + contains: const: google,gs101-cmu-misc then: diff --git a/Documentation/devicetree/bindings/clock/keystone-gate.txt b/Documentation/devicetree/bindings/clock/keystone-gate.txt index c5aa187026e3..43f6fb6c9392 100644 --- a/Documentation/devicetree/bindings/clock/keystone-gate.txt +++ b/Documentation/devicetree/bindings/clock/keystone-gate.txt @@ -1,5 +1,3 @@ -Status: Unstable - ABI compatibility may be broken in the future - Binding for Keystone gate control driver which uses PSC controller IP. This binding uses the common clock binding[1]. diff --git a/Documentation/devicetree/bindings/clock/keystone-pll.txt b/Documentation/devicetree/bindings/clock/keystone-pll.txt index 9a3fbc665606..69b0eb7c03c9 100644 --- a/Documentation/devicetree/bindings/clock/keystone-pll.txt +++ b/Documentation/devicetree/bindings/clock/keystone-pll.txt @@ -1,5 +1,3 @@ -Status: Unstable - ABI compatibility may be broken in the future - Binding for keystone PLLs. The main PLL IP typically has a multiplier, a divider and a post divider. The additional PLL IPs like ARMPLL, DDRPLL and PAPLL are controlled by the memory mapped register where as the Main diff --git a/Documentation/devicetree/bindings/clock/ti/adpll.txt b/Documentation/devicetree/bindings/clock/ti/adpll.txt index 4c8a2ce2cd70..3122360adcf3 100644 --- a/Documentation/devicetree/bindings/clock/ti/adpll.txt +++ b/Documentation/devicetree/bindings/clock/ti/adpll.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments ADPLL clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped ADPLL with two to three selectable input clocks and three to four children. diff --git a/Documentation/devicetree/bindings/clock/ti/apll.txt b/Documentation/devicetree/bindings/clock/ti/apll.txt index ade4dd4c30f0..bbd505c1199d 100644 --- a/Documentation/devicetree/bindings/clock/ti/apll.txt +++ b/Documentation/devicetree/bindings/clock/ti/apll.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments APLL clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped APLL with usually two selectable input clocks (reference clock and bypass clock), with analog phase locked diff --git a/Documentation/devicetree/bindings/clock/ti/autoidle.txt b/Documentation/devicetree/bindings/clock/ti/autoidle.txt index 7c735dde9fe9..05645a10a9e3 100644 --- a/Documentation/devicetree/bindings/clock/ti/autoidle.txt +++ b/Documentation/devicetree/bindings/clock/ti/autoidle.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments autoidle clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register mapped clock which can be put to idle automatically by hardware based on the usage and a configuration bit setting. Autoidle clock is never an individual diff --git a/Documentation/devicetree/bindings/clock/ti/clockdomain.txt b/Documentation/devicetree/bindings/clock/ti/clockdomain.txt index 9c6199249ce5..edf0b5d42768 100644 --- a/Documentation/devicetree/bindings/clock/ti/clockdomain.txt +++ b/Documentation/devicetree/bindings/clock/ti/clockdomain.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments clockdomain. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1] in consumer role. Every clock on TI SoC belongs to one clockdomain, but software only needs this information for specific clocks which require diff --git a/Documentation/devicetree/bindings/clock/ti/composite.txt b/Documentation/devicetree/bindings/clock/ti/composite.txt index 33ac7c9ad053..6f7e1331b546 100644 --- a/Documentation/devicetree/bindings/clock/ti/composite.txt +++ b/Documentation/devicetree/bindings/clock/ti/composite.txt @@ -1,7 +1,5 @@ Binding for TI composite clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped composite clock with multiple different sub-types; diff --git a/Documentation/devicetree/bindings/clock/ti/divider.txt b/Documentation/devicetree/bindings/clock/ti/divider.txt index 9b13b32974f9..4d7c76f0b356 100644 --- a/Documentation/devicetree/bindings/clock/ti/divider.txt +++ b/Documentation/devicetree/bindings/clock/ti/divider.txt @@ -1,7 +1,5 @@ Binding for TI divider clock -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped adjustable clock rate divider that does not gate and has only one input clock or parent. By default the value programmed into diff --git a/Documentation/devicetree/bindings/clock/ti/dpll.txt b/Documentation/devicetree/bindings/clock/ti/dpll.txt index 37a7cb6ad07d..14a1b72c2e71 100644 --- a/Documentation/devicetree/bindings/clock/ti/dpll.txt +++ b/Documentation/devicetree/bindings/clock/ti/dpll.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments DPLL clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped DPLL with usually two selectable input clocks (reference clock and bypass clock), with digital phase locked diff --git a/Documentation/devicetree/bindings/clock/ti/fapll.txt b/Documentation/devicetree/bindings/clock/ti/fapll.txt index c19b3f253b8c..88986ef39ddd 100644 --- a/Documentation/devicetree/bindings/clock/ti/fapll.txt +++ b/Documentation/devicetree/bindings/clock/ti/fapll.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments FAPLL clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped FAPLL with usually two selectable input clocks (reference clock and bypass clock), and one or more child diff --git a/Documentation/devicetree/bindings/clock/ti/fixed-factor-clock.txt b/Documentation/devicetree/bindings/clock/ti/fixed-factor-clock.txt index 518e3c142276..dc69477b6e98 100644 --- a/Documentation/devicetree/bindings/clock/ti/fixed-factor-clock.txt +++ b/Documentation/devicetree/bindings/clock/ti/fixed-factor-clock.txt @@ -1,7 +1,5 @@ Binding for TI fixed factor rate clock sources. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1], and also uses the autoidle support from TI autoidle clock [2]. diff --git a/Documentation/devicetree/bindings/clock/ti/gate.txt b/Documentation/devicetree/bindings/clock/ti/gate.txt index 4982615c01b9..a8e0335b006a 100644 --- a/Documentation/devicetree/bindings/clock/ti/gate.txt +++ b/Documentation/devicetree/bindings/clock/ti/gate.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments gate clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. This clock is quite much similar to the basic gate-clock [2], however, it supports a number of additional features. If no register diff --git a/Documentation/devicetree/bindings/clock/ti/interface.txt b/Documentation/devicetree/bindings/clock/ti/interface.txt index d3eb5ca92a7f..85fb1f2d2d28 100644 --- a/Documentation/devicetree/bindings/clock/ti/interface.txt +++ b/Documentation/devicetree/bindings/clock/ti/interface.txt @@ -1,7 +1,5 @@ Binding for Texas Instruments interface clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. This clock is quite much similar to the basic gate-clock [2], however, it supports a number of additional features, including diff --git a/Documentation/devicetree/bindings/clock/ti/mux.txt b/Documentation/devicetree/bindings/clock/ti/mux.txt index b33f641f1043..cd56d3c1c09f 100644 --- a/Documentation/devicetree/bindings/clock/ti/mux.txt +++ b/Documentation/devicetree/bindings/clock/ti/mux.txt @@ -1,7 +1,5 @@ Binding for TI mux clock. -Binding status: Unstable - ABI compatibility may be broken in the future - This binding uses the common clock binding[1]. It assumes a register-mapped multiplexer with multiple input clock signals or parents, one of which can be selected as output. This clock does not diff --git a/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-aes.yaml b/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-aes.yaml new file mode 100644 index 000000000000..cb47ae2889b6 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-aes.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/nvidia,tegra234-se-aes.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Security Engine for AES algorithms + +description: + The Tegra Security Engine accelerates the following AES encryption/decryption + algorithms - AES-ECB, AES-CBC, AES-OFB, AES-XTS, AES-CTR, AES-GCM, AES-CCM, + AES-CMAC + +maintainers: + - Akhil R <akhilrajeev@nvidia.com> + +properties: + compatible: + const: nvidia,tegra234-se-aes + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: true + +required: + - compatible + - reg + - clocks + - iommus + +additionalProperties: false + +examples: + - | + #include <dt-bindings/memory/tegra234-mc.h> + #include <dt-bindings/clock/tegra234-clock.h> + + crypto@15820000 { + compatible = "nvidia,tegra234-se-aes"; + reg = <0x15820000 0x10000>; + clocks = <&bpmp TEGRA234_CLK_SE>; + iommus = <&smmu TEGRA234_SID_SES_SE1>; + dma-coherent; + }; +... diff --git a/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-hash.yaml b/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-hash.yaml new file mode 100644 index 000000000000..f57ef10645e2 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/nvidia,tegra234-se-hash.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/nvidia,tegra234-se-hash.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra Security Engine for HASH algorithms + +description: + The Tegra Security HASH Engine accelerates the following HASH functions - + SHA1, SHA224, SHA256, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 + HMAC(SHA224), HMAC(SHA256), HMAC(SHA384), HMAC(SHA512) + +maintainers: + - Akhil R <akhilrajeev@nvidia.com> + +properties: + compatible: + const: nvidia,tegra234-se-hash + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + iommus: + maxItems: 1 + + dma-coherent: true + +required: + - compatible + - reg + - clocks + - iommus + +additionalProperties: false + +examples: + - | + #include <dt-bindings/memory/tegra234-mc.h> + #include <dt-bindings/clock/tegra234-clock.h> + + crypto@15840000 { + compatible = "nvidia,tegra234-se-hash"; + reg = <0x15840000 0x10000>; + clocks = <&bpmp TEGRA234_CLK_SE>; + iommus = <&smmu TEGRA234_SID_SES_SE2>; + dma-coherent; + }; +... diff --git a/Documentation/devicetree/bindings/crypto/omap-sham.txt b/Documentation/devicetree/bindings/crypto/omap-sham.txt deleted file mode 100644 index ad9115569611..000000000000 --- a/Documentation/devicetree/bindings/crypto/omap-sham.txt +++ /dev/null @@ -1,28 +0,0 @@ -OMAP SoC SHA crypto Module - -Required properties: - -- compatible : Should contain entries for this and backward compatible - SHAM versions: - - "ti,omap2-sham" for OMAP2 & OMAP3. - - "ti,omap4-sham" for OMAP4 and AM33XX. - - "ti,omap5-sham" for OMAP5, DRA7 and AM43XX. -- ti,hwmods: Name of the hwmod associated with the SHAM module -- reg : Offset and length of the register set for the module -- interrupts : the interrupt-specifier for the SHAM module. - -Optional properties: -- dmas: DMA specifiers for the rx dma. See the DMA client binding, - Documentation/devicetree/bindings/dma/dma.txt -- dma-names: DMA request name. Should be "rx" if a dma is present. - -Example: - /* AM335x */ - sham: sham@53100000 { - compatible = "ti,omap4-sham"; - ti,hwmods = "sham"; - reg = <0x53100000 0x200>; - interrupts = <109>; - dmas = <&edma 36>; - dma-names = "rx"; - }; diff --git a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml index e91bc7dc6ad3..0304f074cf08 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml @@ -15,6 +15,7 @@ properties: - enum: - qcom,sa8775p-inline-crypto-engine - qcom,sc7180-inline-crypto-engine + - qcom,sc7280-inline-crypto-engine - qcom,sm8450-inline-crypto-engine - qcom,sm8550-inline-crypto-engine - qcom,sm8650-inline-crypto-engine diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml index 0ddeb8a9a7a0..27354658d054 100644 --- a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml +++ b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.yaml @@ -46,6 +46,10 @@ properties: power-domains: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml index ac480765cde0..822318414095 100644 --- a/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml +++ b/Documentation/devicetree/bindings/crypto/st,stm32-hash.yaml @@ -51,6 +51,10 @@ properties: power-domains: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/crypto/starfive,jh7110-crypto.yaml b/Documentation/devicetree/bindings/crypto/starfive,jh7110-crypto.yaml index 71a2876bd6e4..7ccb6e1641d0 100644 --- a/Documentation/devicetree/bindings/crypto/starfive,jh7110-crypto.yaml +++ b/Documentation/devicetree/bindings/crypto/starfive,jh7110-crypto.yaml @@ -12,7 +12,9 @@ maintainers: properties: compatible: - const: starfive,jh7110-crypto + enum: + - starfive,jh7110-crypto + - starfive,jh8100-crypto reg: maxItems: 1 @@ -28,7 +30,10 @@ properties: - const: ahb interrupts: - maxItems: 1 + minItems: 1 + items: + - description: SHA2 module irq + - description: SM3 module irq resets: maxItems: 1 @@ -54,6 +59,27 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + const: starfive,jh7110-crypto + + then: + properties: + interrupts: + maxItems: 1 + + - if: + properties: + compatible: + const: starfive,jh8100-crypto + + then: + properties: + interrupts: + minItems: 2 + examples: - | crypto: crypto@16000000 { diff --git a/Documentation/devicetree/bindings/crypto/ti,omap-sham.yaml b/Documentation/devicetree/bindings/crypto/ti,omap-sham.yaml new file mode 100644 index 000000000000..d69b50228009 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/ti,omap-sham.yaml @@ -0,0 +1,56 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/crypto/ti,omap-sham.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OMAP SoC SHA crypto Module + +maintainers: + - Animesh Agarwal <animeshagarwal28@gmail.com> + +properties: + compatible: + enum: + - ti,omap2-sham + - ti,omap4-sham + - ti,omap5-sham + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dmas: + maxItems: 1 + + dma-names: + const: rx + + ti,hwmods: + description: Name of the hwmod associated with the SHAM module + $ref: /schemas/types.yaml#/definitions/string + enum: [sham] + +dependencies: + dmas: [dma-names] + +additionalProperties: false + +required: + - compatible + - ti,hwmods + - reg + - interrupts + +examples: + - | + sham@53100000 { + compatible = "ti,omap4-sham"; + ti,hwmods = "sham"; + reg = <0x53100000 0x200>; + interrupts = <109>; + dmas = <&edma 36>; + dma-names = "rx"; + }; diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml index c0d6a4fdff97..e6dc5494baee 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8150-mdss.yaml @@ -53,6 +53,15 @@ patternProperties: compatible: const: qcom,sm8150-dpu + "^displayport-controller@[0-9a-f]+$": + type: object + additionalProperties: true + + properties: + compatible: + contains: + const: qcom,sm8150-dp + "^dsi@[0-9a-f]+$": type: object additionalProperties: true diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index a95445f40870..397e810008bd 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -348,15 +348,6 @@ properties: # Yes Optoelectronics YTC700TLAG-05-201C 7" TFT LCD panel - yes-optoelectronics,ytc700tlag-05-201c - backlight: true - ddc-i2c-bus: true - enable-gpios: true - port: true - power-supply: true - no-hpd: true - hpd-gpios: true - data-mapping: true - if: not: properties: @@ -367,7 +358,7 @@ then: properties: data-mapping: false -additionalProperties: false +unevaluatedProperties: false required: - compatible diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml index 94c5242c03b2..3563378a01af 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml @@ -182,6 +182,15 @@ allOf: compatible: contains: enum: + - nvidia,tegra194-host1x + then: + properties: + dma-coherent: true + - if: + properties: + compatible: + contains: + enum: - nvidia,tegra234-host1x then: properties: @@ -226,6 +235,8 @@ allOf: use. Should be a mapping of IDs 0..n to IOMMU entries corresponding to usable stream IDs. + dma-coherent: true + required: - reg-names diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml index 329847ef096a..ff935a0068ec 100644 --- a/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml +++ b/Documentation/devicetree/bindings/dma/st,stm32-dma.yaml @@ -82,6 +82,10 @@ properties: description: if defined, it indicates that the controller supports memory-to-memory transfer + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml b/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml index e722fbcd8a5f..ddf82bf1e71a 100644 --- a/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml +++ b/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml @@ -28,6 +28,10 @@ properties: resets: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst index a9bdd2b59dca..8a68331075a0 100644 --- a/Documentation/devicetree/bindings/dts-coding-style.rst +++ b/Documentation/devicetree/bindings/dts-coding-style.rst @@ -144,6 +144,8 @@ Example:: #dma-cells = <1>; clocks = <&clock_controller 0>, <&clock_controller 1>; clock-names = "bus", "host"; + #address-cells = <1>; + #size-cells = <1>; vendor,custom-property = <2>; status = "disabled"; diff --git a/Documentation/devicetree/bindings/eeprom/at24.yaml b/Documentation/devicetree/bindings/eeprom/at24.yaml index 1812ef31d5f1..3c36cd0510de 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.yaml +++ b/Documentation/devicetree/bindings/eeprom/at24.yaml @@ -69,14 +69,10 @@ properties: - items: pattern: c32$ - items: - pattern: c32d-wl$ - - items: pattern: cs32$ - items: pattern: c64$ - items: - pattern: c64d-wl$ - - items: pattern: cs64$ - items: pattern: c128$ @@ -136,6 +132,7 @@ properties: - renesas,r1ex24128 - samsung,s524ad0xd1 - const: atmel,24c128 + - pattern: '^atmel,24c(32|64)d-wl$' # Actual vendor is st label: description: Descriptive name of the EEPROM. diff --git a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml index 4591523b51a0..7de2c29606e5 100644 --- a/Documentation/devicetree/bindings/firmware/arm,scmi.yaml +++ b/Documentation/devicetree/bindings/firmware/arm,scmi.yaml @@ -247,6 +247,37 @@ properties: reg: const: 0x18 + protocol@19: + type: object + allOf: + - $ref: '#/$defs/protocol-node' + - $ref: /schemas/pinctrl/pinctrl.yaml + + unevaluatedProperties: false + + properties: + reg: + const: 0x19 + + patternProperties: + '-pins$': + type: object + allOf: + - $ref: /schemas/pinctrl/pincfg-node.yaml# + - $ref: /schemas/pinctrl/pinmux-node.yaml# + unevaluatedProperties: false + + description: + A pin multiplexing sub-node describes how to configure a + set of pins in some desired function. + A single sub-node may define several pin configurations. + This sub-node is using the default pinctrl bindings to configure + pin multiplexing and using SCMI protocol to apply a specified + configuration. + + required: + - reg + additionalProperties: false $defs: @@ -355,7 +386,7 @@ examples: scmi_dvfs: protocol@13 { reg = <0x13>; - #clock-cells = <1>; + #power-domain-cells = <1>; mboxes = <&mhuB 1 0>, <&mhuB 1 1>; @@ -401,6 +432,25 @@ examples: scmi_powercap: protocol@18 { reg = <0x18>; }; + + scmi_pinctrl: protocol@19 { + reg = <0x19>; + + i2c2-pins { + groups = "g_i2c2_a", "g_i2c2_b"; + function = "f_i2c2"; + }; + + mdio-pins { + groups = "g_avb_mdio"; + drive-strength = <24>; + }; + + keys_pins: keys-pins { + pins = "gpio_5_17", "gpio_5_20", "gpio_5_22", "gpio_2_1"; + bias-pull-up; + }; + }; }; }; @@ -468,7 +518,7 @@ examples: reg = <0x13>; linaro,optee-channel-id = <1>; shmem = <&cpu_optee_lpri0>; - #clock-cells = <1>; + #power-domain-cells = <1>; }; scmi_clk0: protocol@14 { diff --git a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt deleted file mode 100644 index ce97265e23ba..000000000000 --- a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt +++ /dev/null @@ -1,30 +0,0 @@ -Raspberry Pi GPIO expander - -The Raspberry Pi 3 GPIO expander is controlled by the VC4 firmware. The -firmware exposes a mailbox interface that allows the ARM core to control the -GPIO lines on the expander. - -The Raspberry Pi GPIO expander node must be a child node of the Raspberry Pi -firmware node. - -Required properties: - -- compatible : Should be "raspberrypi,firmware-gpio" -- gpio-controller : Marks the device node as a gpio controller -- #gpio-cells : Should be two. The first cell is the pin number, and - the second cell is used to specify the gpio polarity: - 0 = active high - 1 = active low - -Example: - -firmware: firmware-rpi { - compatible = "raspberrypi,bcm2835-firmware"; - mboxes = <&mailbox>; - - expgpio: gpio { - compatible = "raspberrypi,firmware-gpio"; - gpio-controller; - #gpio-cells = <2>; - }; -}; diff --git a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml index 1b31b87c1800..8fd8be76875e 100644 --- a/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/st,stm32-i2c.yaml @@ -127,6 +127,10 @@ properties: wakeup-source: true + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml index 995cbf8cefc6..ec34c48d4878 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.yaml @@ -93,6 +93,10 @@ properties: '#size-cells': const: 0 + access-controllers: + minItems: 1 + maxItems: 2 + allOf: - if: properties: diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml index 1970503389aa..c1b1324fa132 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-dfsdm-adc.yaml @@ -59,6 +59,10 @@ properties: If not, SPI CLKOUT frequency will not be accurate. maximum: 20000000 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml index 04045b932bd2..b15de4eb209c 100644 --- a/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml +++ b/Documentation/devicetree/bindings/iio/dac/st,stm32-dac.yaml @@ -45,6 +45,10 @@ properties: '#size-cells': const: 0 + access-controllers: + minItems: 1 + maxItems: 2 + additionalProperties: false required: diff --git a/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml b/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml index c13c10c8d65d..eed0df9d3a23 100644 --- a/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml +++ b/Documentation/devicetree/bindings/iio/health/maxim,max30102.yaml @@ -42,7 +42,7 @@ allOf: properties: compatible: contains: - const: maxim,max30100 + const: maxim,max30102 then: properties: maxim,green-led-current-microamp: false diff --git a/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml b/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml index 2314a9a14650..1d930d9e10fd 100644 --- a/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml +++ b/Documentation/devicetree/bindings/media/cec/st,stm32-cec.yaml @@ -29,6 +29,10 @@ properties: - const: cec - const: hdmi-cec + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml index 6b3e413cedb2..34147127192f 100644 --- a/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32-dcmi.yaml @@ -36,6 +36,10 @@ properties: resets: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + port: $ref: /schemas/graph.yaml#/$defs/port-base unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml index b8611bc8756c..73726c65cfb9 100644 --- a/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml +++ b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml @@ -30,6 +30,10 @@ properties: clocks: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/memory-controllers/samsung,s5pv210-dmc.yaml b/Documentation/devicetree/bindings/memory-controllers/samsung,s5pv210-dmc.yaml new file mode 100644 index 000000000000..c0e47055f28c --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/samsung,s5pv210-dmc.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/memory-controllers/samsung,s5pv210-dmc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Samsung S5Pv210 SoC Dynamic Memory Controller + +maintainers: + - Krzysztof Kozlowski <krzk@kernel.org> + +description: + Dynamic Memory Controller interfaces external JEDEC DDR-type SDRAM. + +properties: + compatible: + const: samsung,s5pv210-dmc + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + memory-controller@f0000000 { + compatible = "samsung,s5pv210-dmc"; + reg = <0xf0000000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml index 84ac6f50a6fc..706e45eb4d27 100644 --- a/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/st,stm32-fmc2-ebi.yaml @@ -50,6 +50,10 @@ properties: Reflects the memory layout with four integer values per bank. Format: <bank-number> 0 <address of the bank> <size> + access-controllers: + minItems: 1 + maxItems: 2 + patternProperties: "^.*@[0-4],[a-f0-9]+$": additionalProperties: true diff --git a/Documentation/devicetree/bindings/mfd/st,stm32-lptimer.yaml b/Documentation/devicetree/bindings/mfd/st,stm32-lptimer.yaml index 27329c5dc38e..d41308856408 100644 --- a/Documentation/devicetree/bindings/mfd/st,stm32-lptimer.yaml +++ b/Documentation/devicetree/bindings/mfd/st,stm32-lptimer.yaml @@ -44,6 +44,10 @@ properties: wakeup-source: true + access-controllers: + minItems: 1 + maxItems: 2 + pwm: type: object additionalProperties: false diff --git a/Documentation/devicetree/bindings/mfd/st,stm32-timers.yaml b/Documentation/devicetree/bindings/mfd/st,stm32-timers.yaml index f84e09a5743b..b0e438ff4950 100644 --- a/Documentation/devicetree/bindings/mfd/st,stm32-timers.yaml +++ b/Documentation/devicetree/bindings/mfd/st,stm32-timers.yaml @@ -67,6 +67,10 @@ properties: "#size-cells": const: 0 + access-controllers: + minItems: 1 + maxItems: 2 + pwm: type: object additionalProperties: false diff --git a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml index 940b12688167..8f62e2c7fa64 100644 --- a/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml +++ b/Documentation/devicetree/bindings/mmc/arm,pl18x.yaml @@ -79,6 +79,10 @@ properties: - const: rx - const: tx + access-controllers: + minItems: 1 + maxItems: 2 + power-domains: true resets: diff --git a/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml index 528ef3572b62..055a3351880b 100644 --- a/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml +++ b/Documentation/devicetree/bindings/net/bluetooth/qualcomm-bluetooth.yaml @@ -94,6 +94,10 @@ properties: local-bd-address: true + qcom,local-bd-address-broken: + type: boolean + description: + boot firmware is incorrectly passing the address in big-endian order required: - compatible diff --git a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml index f9ffb963d6b1..c4887522e8fe 100644 --- a/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml +++ b/Documentation/devicetree/bindings/net/can/bosch,m_can.yaml @@ -118,6 +118,10 @@ properties: phys: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/mediatek,net.yaml b/Documentation/devicetree/bindings/net/mediatek,net.yaml index e74502a0afe8..3202dc7967c5 100644 --- a/Documentation/devicetree/bindings/net/mediatek,net.yaml +++ b/Documentation/devicetree/bindings/net/mediatek,net.yaml @@ -337,8 +337,8 @@ allOf: minItems: 4 clocks: - minItems: 34 - maxItems: 34 + minItems: 24 + maxItems: 24 clock-names: items: @@ -351,18 +351,6 @@ allOf: - const: ethwarp_wocpu1 - const: ethwarp_wocpu0 - const: esw - - const: netsys0 - - const: netsys1 - - const: sgmii_tx250m - - const: sgmii_rx250m - - const: sgmii2_tx250m - - const: sgmii2_rx250m - - const: top_usxgmii0_sel - - const: top_usxgmii1_sel - - const: top_sgm0_sel - - const: top_sgm1_sel - - const: top_xfi_phy0_xtal_sel - - const: top_xfi_phy1_xtal_sel - const: top_eth_gmii_sel - const: top_eth_refck_50m_sel - const: top_eth_sys_200m_sel @@ -375,16 +363,10 @@ allOf: - const: top_netsys_sync_250m_sel - const: top_netsys_ppefb_250m_sel - const: top_netsys_warp_sel - - const: wocpu1 - - const: wocpu0 - const: xgp1 - const: xgp2 - const: xgp3 - mediatek,sgmiisys: - minItems: 2 - maxItems: 2 - patternProperties: "^mac@[0-1]$": type: object diff --git a/Documentation/devicetree/bindings/net/stm32-dwmac.yaml b/Documentation/devicetree/bindings/net/stm32-dwmac.yaml index fc8c96b08d7d..f2714b5b6cf4 100644 --- a/Documentation/devicetree/bindings/net/stm32-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/stm32-dwmac.yaml @@ -93,6 +93,10 @@ properties: select RCC clock instead of ETH_REF_CLK. type: boolean + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - clocks diff --git a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml index 24a3dbde223b..ceea122ae1a6 100644 --- a/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml +++ b/Documentation/devicetree/bindings/phy/phy-stm32-usbphyc.yaml @@ -55,6 +55,10 @@ properties: description: number of clock cells for ck_usbo_48m consumer const: 0 + access-controllers: + minItems: 1 + maxItems: 2 + # Required child nodes: patternProperties: diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml index d476de82e5c3..4d5a957fa232 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rzg2l-pinctrl.yaml @@ -120,7 +120,9 @@ additionalProperties: slew-rate: true gpio-hog: true gpios: true + input: true input-enable: true + output-enable: true output-high: true output-low: true line-name: true diff --git a/Documentation/devicetree/bindings/pwm/mediatek,pwm-disp.yaml b/Documentation/devicetree/bindings/pwm/mediatek,pwm-disp.yaml index afcdeed4e88a..bc813fe74fab 100644 --- a/Documentation/devicetree/bindings/pwm/mediatek,pwm-disp.yaml +++ b/Documentation/devicetree/bindings/pwm/mediatek,pwm-disp.yaml @@ -52,6 +52,9 @@ properties: - const: main - const: mm + power-domains: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml index 05f4ad2c7d3a..6ceaffb45dc9 100644 --- a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml +++ b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.yaml @@ -30,6 +30,10 @@ properties: vdda-supply: description: phandle to the vdda input analog voltage. + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/remoteproc/ti,davinci-rproc.txt b/Documentation/devicetree/bindings/remoteproc/ti,davinci-rproc.txt index 25f8658e216f..48a49c516b62 100644 --- a/Documentation/devicetree/bindings/remoteproc/ti,davinci-rproc.txt +++ b/Documentation/devicetree/bindings/remoteproc/ti,davinci-rproc.txt @@ -1,9 +1,6 @@ TI Davinci DSP devices ======================= -Binding status: Unstable - Subject to changes for DT representation of clocks - and resets - The TI Davinci family of SoCs usually contains a TI DSP Core sub-system that is used to offload some of the processor-intensive tasks or algorithms, for achieving various system level goals. diff --git a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml index 717f6b321f88..340d01d481d1 100644 --- a/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml +++ b/Documentation/devicetree/bindings/rng/st,stm32-rng.yaml @@ -37,6 +37,10 @@ properties: description: If set, the RNG configuration in RNG_CR, RNG_HTCR and RNG_NSCR will be locked. + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml b/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml index 65cb2e5c5eee..eb2992a447d7 100644 --- a/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml +++ b/Documentation/devicetree/bindings/serial/atmel,at91-usart.yaml @@ -8,7 +8,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Atmel Universal Synchronous Asynchronous Receiver/Transmitter (USART) maintainers: - - Richard Genoud <richard.genoud@gmail.com> + - Richard Genoud <richard.genoud@bootlin.com> properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml index 62f97da1b2fd..2ed526139269 100644 --- a/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml +++ b/Documentation/devicetree/bindings/serial/st,stm32-uart.yaml @@ -73,6 +73,10 @@ properties: enum: [1, 2, 4, 8, 12, 14, 16] default: 8 + access-controllers: + minItems: 1 + maxItems: 2 + allOf: - $ref: rs485.yaml# - $ref: serial.yaml# diff --git a/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-dcfg.yaml b/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-dcfg.yaml index 397f75909b20..ce1a6505eb51 100644 --- a/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-dcfg.yaml +++ b/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-dcfg.yaml @@ -51,7 +51,7 @@ properties: ranges: true patternProperties: - "^clock-controller@[0-9a-z]+$": + "^clock-controller@[0-9a-f]+$": $ref: /schemas/clock/fsl,flexspi-clock.yaml# required: diff --git a/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-scfg.yaml b/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-scfg.yaml index 8d088b5fe823..a6a511b00a12 100644 --- a/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-scfg.yaml +++ b/Documentation/devicetree/bindings/soc/fsl/fsl,layerscape-scfg.yaml @@ -41,7 +41,7 @@ properties: ranges: true patternProperties: - "^interrupt-controller@[a-z0-9]+$": + "^interrupt-controller@[a-f0-9]+$": $ref: /schemas/interrupt-controller/fsl,ls-extirq.yaml# required: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml index 4310bae6c58e..4512390f90f0 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml @@ -58,20 +58,6 @@ patternProperties: required: - compatible -allOf: - - if: - not: - properties: - compatible: - contains: - enum: - - qcom,sm8450-pmic-glink - - qcom,sm8550-pmic-glink - - qcom,x1e80100-pmic-glink - then: - properties: - orientation-gpios: false - additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml index 74bb92e31554..fd6db0ca98eb 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,wcnss.yaml @@ -116,8 +116,8 @@ examples: bluetooth { compatible = "qcom,wcnss-bt"; - /* BD address 00:11:22:33:44:55 */ - local-bd-address = [ 55 44 33 22 11 00 ]; + /* Updated by boot firmware (little-endian order) */ + local-bd-address = [ 00 00 00 00 00 00 ]; }; wifi { diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g057-sys.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g057-sys.yaml new file mode 100644 index 000000000000..ebbf0c9109ce --- /dev/null +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,r9a09g057-sys.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/renesas/renesas,r9a09g057-sys.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas RZ/V2H(P) System Controller (SYS) + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +description: | + The RZ/V2H(P) SYS (System Controller) controls the overall + configuration of the LSI and supports the following functions, + - Trust zone control + - Extend access by specific masters to address beyond 4GB space + - GBETH configuration + - Control of settings and states of SRAM/PCIe/CM33/CA55/CR8/xSPI/ADC/TSU + - LSI version + - WDT stop control + - General registers + +properties: + compatible: + const: renesas,r9a09g057-sys + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + +required: + - compatible + - reg + - clocks + - resets + +additionalProperties: false + +examples: + - | + sys: system-controller@10430000 { + compatible = "renesas,r9a09g057-sys"; + reg = <0x10430000 0x10000>; + clocks = <&cpg 1>; + resets = <&cpg 1>; + }; diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml index c1ce4da2dc32..09d3ce97efa2 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml @@ -513,6 +513,14 @@ properties: - renesas,rzv2mevk2 # RZ/V2M Eval Board v2.0 - const: renesas,r9a09g011 + - description: RZ/V2H(P) (R9A09G057) + items: + - enum: + - renesas,r9a09g057h41 # RZ/V2H + - renesas,r9a09g057h42 # RZ/V2H with Mali-G31 support + - renesas,r9a09g057h44 # RZ/V2HP with Mali-G31 + Mali-C55 support + - const: renesas,r9a09g057 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml index 0b87c266760c..79798c747476 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml @@ -171,6 +171,7 @@ allOf: unevaluatedProperties: false pcie-phy: + type: object description: Documentation/devicetree/bindings/phy/rockchip-pcie-phy.txt diff --git a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml index c0c6ce8fc786..3ca220582897 100644 --- a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml @@ -15,6 +15,7 @@ properties: - items: - enum: - google,gs101-apm-sysreg + - google,gs101-hsi2-sysreg - google,gs101-peric0-sysreg - google,gs101-peric1-sysreg - samsung,exynos3-sysreg @@ -72,6 +73,7 @@ allOf: compatible: contains: enum: + - google,gs101-hsi2-sysreg - google,gs101-peric0-sysreg - google,gs101-peric1-sysreg - samsung,exynos850-cmgp-sysreg diff --git a/Documentation/devicetree/bindings/sound/rt5645.txt b/Documentation/devicetree/bindings/sound/rt5645.txt index 41a62fd2ae1f..c1fa379f5f3e 100644 --- a/Documentation/devicetree/bindings/sound/rt5645.txt +++ b/Documentation/devicetree/bindings/sound/rt5645.txt @@ -20,6 +20,11 @@ Optional properties: a GPIO spec for the external headphone detect pin. If jd-mode = 0, we will get the JD status by getting the value of hp-detect-gpios. +- cbj-sleeve-gpios: + a GPIO spec to control the external combo jack circuit to tie the sleeve/ring2 + contacts to the ground or floating. It could avoid some electric noise from the + active speaker jacks. + - realtek,in2-differential Boolean. Indicate MIC2 input are differential, rather than single-ended. @@ -68,6 +73,7 @@ codec: rt5650@1a { compatible = "realtek,rt5650"; reg = <0x1a>; hp-detect-gpios = <&gpio 19 0>; + cbj-sleeve-gpios = <&gpio 20 0>; interrupt-parent = <&gpio>; interrupts = <7 IRQ_TYPE_EDGE_FALLING>; realtek,dmic-en = "true"; diff --git a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml index b9111d375b93..8978f6bd63e5 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-i2s.yaml @@ -65,6 +65,10 @@ properties: $ref: audio-graph-port.yaml# unevaluatedProperties: false + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - "#sound-dai-cells" diff --git a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml index 59df8a832310..b46a4778807d 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-sai.yaml @@ -48,6 +48,10 @@ properties: clock-names: maxItems: 3 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml index bc48151b9adb..3dedc81ec12f 100644 --- a/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml +++ b/Documentation/devicetree/bindings/sound/st,stm32-spdifrx.yaml @@ -50,6 +50,10 @@ properties: resets: maxItems: 1 + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - "#sound-dai-cells" diff --git a/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml index 8bba965a9ae6..3f1a27efff80 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-qspi.yaml @@ -46,6 +46,10 @@ properties: - const: tx - const: rx + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml index 4bd9aeb81208..a55c8633c32c 100644 --- a/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml +++ b/Documentation/devicetree/bindings/spi/st,stm32-spi.yaml @@ -52,6 +52,10 @@ properties: - const: rx - const: tx + access-controllers: + minItems: 1 + maxItems: 2 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml index 7a4a6ab85970..ab8f28993139 100644 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml @@ -60,7 +60,7 @@ properties: be implemented in an always-on power domain." patternProperties: - '^frame@[0-9a-z]*$': + '^frame@[0-9a-f]+$': type: object additionalProperties: false description: A timer node has up to 8 frame sub-nodes, each with the following properties. diff --git a/Documentation/devicetree/bindings/tpm/tcg,tpm-tis-i2c.yaml b/Documentation/devicetree/bindings/tpm/tcg,tpm-tis-i2c.yaml index 3ab4434b7352..af7720dc4a12 100644 --- a/Documentation/devicetree/bindings/tpm/tcg,tpm-tis-i2c.yaml +++ b/Documentation/devicetree/bindings/tpm/tcg,tpm-tis-i2c.yaml @@ -32,6 +32,7 @@ properties: - enum: - infineon,slb9673 - nuvoton,npct75x + - st,st33ktpm2xi2c - const: tcg,tpm-tis-i2c - description: TPM 1.2 and 2.0 chips with vendor-specific I²C interface diff --git a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml index 10c146424baa..cd3680dc002f 100644 --- a/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml @@ -27,10 +27,13 @@ properties: - qcom,msm8996-ufshc - qcom,msm8998-ufshc - qcom,sa8775p-ufshc + - qcom,sc7180-ufshc - qcom,sc7280-ufshc + - qcom,sc8180x-ufshc - qcom,sc8280xp-ufshc - qcom,sdm845-ufshc - qcom,sm6115-ufshc + - qcom,sm6125-ufshc - qcom,sm6350-ufshc - qcom,sm8150-ufshc - qcom,sm8250-ufshc @@ -42,11 +45,11 @@ properties: - const: jedec,ufs-2.0 clocks: - minItems: 8 + minItems: 7 maxItems: 11 clock-names: - minItems: 8 + minItems: 7 maxItems: 11 dma-coherent: true @@ -117,9 +120,35 @@ allOf: compatible: contains: enum: + - qcom,sc7180-ufshc + then: + properties: + clocks: + minItems: 7 + maxItems: 7 + clock-names: + items: + - const: core_clk + - const: bus_aggr_clk + - const: iface_clk + - const: core_clk_unipro + - const: ref_clk + - const: tx_lane0_sync_clk + - const: rx_lane0_sync_clk + reg: + maxItems: 1 + reg-names: + maxItems: 1 + + - if: + properties: + compatible: + contains: + enum: - qcom,msm8998-ufshc - qcom,sa8775p-ufshc - qcom,sc7280-ufshc + - qcom,sc8180x-ufshc - qcom,sc8280xp-ufshc - qcom,sm8250-ufshc - qcom,sm8350-ufshc @@ -215,6 +244,7 @@ allOf: contains: enum: - qcom,sm6115-ufshc + - qcom,sm6125-ufshc then: properties: clocks: @@ -248,7 +278,7 @@ allOf: reg: maxItems: 1 clocks: - minItems: 8 + minItems: 7 maxItems: 8 else: properties: @@ -256,7 +286,7 @@ allOf: minItems: 1 maxItems: 2 clocks: - minItems: 8 + minItems: 7 maxItems: 11 unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/usb/dwc2.yaml b/Documentation/devicetree/bindings/usb/dwc2.yaml index 0a5c98ea711d..88c077673c8b 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.yaml +++ b/Documentation/devicetree/bindings/usb/dwc2.yaml @@ -172,6 +172,10 @@ properties: tpl-support: true + access-controllers: + minItems: 1 + maxItems: 2 + dependencies: port: [ usb-role-switch ] role-switch-default-mode: [ usb-role-switch ] diff --git a/Documentation/devicetree/bindings/usb/fsl,usbmisc.yaml b/Documentation/devicetree/bindings/usb/fsl,usbmisc.yaml index 2d3589d284b2..0a6e7ac1b37e 100644 --- a/Documentation/devicetree/bindings/usb/fsl,usbmisc.yaml +++ b/Documentation/devicetree/bindings/usb/fsl,usbmisc.yaml @@ -33,6 +33,7 @@ properties: - fsl,imx7ulp-usbmisc - fsl,imx8mm-usbmisc - fsl,imx8mn-usbmisc + - fsl,imx8ulp-usbmisc - const: fsl,imx7d-usbmisc - const: fsl,imx6q-usbmisc - items: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index b97d298b3eb6..460c729f6e30 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -151,6 +151,8 @@ patternProperties: description: ARM Ltd. "^armadeus,.*": description: ARMadeus Systems SARL + "^armsom,.*": + description: ArmSoM Technology Co., Ltd. "^arrow,.*": description: Arrow Electronics "^artesyn,.*": @@ -438,6 +440,8 @@ patternProperties: description: Dongguan EmbedFire Electronic Technology Co., Ltd. "^embest,.*": description: Shenzhen Embest Technology Co., Ltd. + "^emcraft,.*": + description: Emcraft Systems "^emlid,.*": description: Emlid, Ltd. "^emmicro,.*": @@ -1627,6 +1631,8 @@ patternProperties: description: Wondermedia Technologies, Inc. "^wobo,.*": description: Wobo + "^wolfvision,.*": + description: WolfVision GmbH "^x-powers,.*": description: X-Powers "^xen,.*": diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 5da0046f7059..204b025f1349 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -61,7 +61,7 @@ DESCRIPTION *********** -Convert a C header or source file (C_FILE), into a ReStructured Text +Convert a C header or source file (C_FILE), into a reStructuredText included via ..parsed-literal block with cross-references for the documentation files that describe the API. It accepts an optional EXCEPTIONS_FILE with describes what elements will be either ignored or diff --git a/Documentation/driver-api/crypto/iaa/iaa-crypto.rst b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst index de587cf9cbed..f4fba897d931 100644 --- a/Documentation/driver-api/crypto/iaa/iaa-crypto.rst +++ b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst @@ -179,7 +179,9 @@ has the old 'iax' device naming in place) :: # configure wq1.0 - accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --name="iaa_crypto" --device_name="crypto" iax1/wq1.0 + accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --priority=10 --name="iaa_crypto" --driver-name="crypto" iax1/wq1.0 + + accel-config config-engine iax1/engine1.0 --group-id=0 # enable IAA device iax1 @@ -321,33 +323,30 @@ driver will generate statistics which can be accessed in debugfs at:: # ls -al /sys/kernel/debug/iaa-crypto/ total 0 - drwxr-xr-x 2 root root 0 Mar 3 09:35 . - drwx------ 47 root root 0 Mar 3 09:35 .. - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_acomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_adecomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_comp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_decomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 stats_reset - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_bytes_out - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_calls - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_bytes_in - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_calls - -rw-r--r-- 1 root root 0 Mar 3 09:35 wq_stats - -Most of the above statisticss are self-explanatory. The wq_stats file -shows per-wq stats, a set for each iaa device and wq in addition to -some global stats:: + drwxr-xr-x 2 root root 0 Mar 3 07:55 . + drwx------ 53 root root 0 Mar 3 07:55 .. + -rw-r--r-- 1 root root 0 Mar 3 07:55 global_stats + -rw-r--r-- 1 root root 0 Mar 3 07:55 stats_reset + -rw-r--r-- 1 root root 0 Mar 3 07:55 wq_stats - # cat wq_stats +The global_stats file shows a set of global statistics collected since +the driver has been loaded or reset:: + + # cat global_stats global stats: - total_comp_calls: 100 - total_decomp_calls: 100 - total_comp_bytes_out: 22800 - total_decomp_bytes_in: 22800 + total_comp_calls: 4300 + total_decomp_calls: 4164 + total_sw_decomp_calls: 0 + total_comp_bytes_out: 5993989 + total_decomp_bytes_in: 5993989 total_completion_einval_errors: 0 total_completion_timeout_errors: 0 - total_completion_comp_buf_overflow_errors: 0 + total_completion_comp_buf_overflow_errors: 136 + +The wq_stats file shows per-wq stats, a set for each iaa device and wq +in addition to some global stats:: + # cat wq_stats iaa device: id: 1 n_wqs: 1 @@ -379,21 +378,36 @@ some global stats:: iaa device: id: 5 n_wqs: 1 - comp_calls: 100 - comp_bytes: 22800 - decomp_calls: 100 - decomp_bytes: 22800 + comp_calls: 1360 + comp_bytes: 1999776 + decomp_calls: 0 + decomp_bytes: 0 wqs: name: iaa_crypto - comp_calls: 100 - comp_bytes: 22800 - decomp_calls: 100 - decomp_bytes: 22800 + comp_calls: 1360 + comp_bytes: 1999776 + decomp_calls: 0 + decomp_bytes: 0 -Writing 0 to 'stats_reset' resets all the stats, including the + iaa device: + id: 7 + n_wqs: 1 + comp_calls: 2940 + comp_bytes: 3994213 + decomp_calls: 4164 + decomp_bytes: 5993989 + wqs: + name: iaa_crypto + comp_calls: 2940 + comp_bytes: 3994213 + decomp_calls: 4164 + decomp_bytes: 5993989 + ... + +Writing to 'stats_reset' resets all the stats, including the per-device and per-wq stats:: - # echo 0 > stats_reset + # echo 1 > stats_reset # cat wq_stats global stats: total_comp_calls: 0 @@ -536,12 +550,20 @@ The below script automatically does that:: echo "End Disable IAA" + echo "Reload iaa_crypto module" + + rmmod iaa_crypto + modprobe iaa_crypto + + echo "End Reload iaa_crypto module" + # # configure iaa wqs and devices # echo "Configure IAA" for ((i = 1; i < ${num_iaa} * 2; i += 2)); do - accel-config config-wq --group-id=0 --mode=dedicated --size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver_name="crypto" iax${i}/wq${i} + accel-config config-wq --group-id=0 --mode=dedicated --wq-size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver-name="crypto" iax${i}/wq${i}.0 + accel-config config-engine iax${i}/engine${i}.0 --group-id=0 done echo "End Configure IAA" @@ -552,10 +574,10 @@ The below script automatically does that:: echo "Enable IAA" for ((i = 1; i < ${num_iaa} * 2; i += 2)); do - echo enable iaa iaa${i} - accel-config enable-device iaa${i} - echo enable wq iaa${i}/wq${i}.0 - accel-config enable-wq iaa${i}/wq${i}.0 + echo enable iaa iax${i} + accel-config enable-device iax${i} + echo enable wq iax${i}/wq${i}.0 + accel-config enable-wq iax${i}/wq${i}.0 done echo "End Enable IAA" diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index 3eac11b7eb01..b33ebe1ec9ed 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -196,8 +196,8 @@ eisa_bus.disable_dev virtual_root.force_probe Force the probing code to probe EISA slots even when it cannot find an EISA compliant mainboard (nothing appears on slot 0). Defaults to 0 - (don't force), and set to 1 (force probing) when either - CONFIG_ALPHA_JENSEN or CONFIG_EISA_VLB_PRIMING are set. + (don't force), and set to 1 (force probing) when + CONFIG_EISA_VLB_PRIMING is set. Random notes ============ diff --git a/Documentation/driver-api/mtd/nand_ecc.rst b/Documentation/driver-api/mtd/nand_ecc.rst index 74347c14a70b..a0d681f26a2e 100644 --- a/Documentation/driver-api/mtd/nand_ecc.rst +++ b/Documentation/driver-api/mtd/nand_ecc.rst @@ -462,7 +462,7 @@ statements is reduced. This is also reflected in the assembly code. Analysis 3 ========== -Very weird. Guess it has to do with caching or instruction parallellism +Very weird. Guess it has to do with caching or instruction parallelism or so. I also tried on an eeePC (Celeron, clocked at 900 Mhz). Interesting observation was that this one is only 30% slower (according to time) executing the code as my 3Ghz D920 processor. diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 64b231d125e0..ec92ea2c82cd 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -259,7 +259,7 @@ attributes for Serial Attached SCSI, a variant of SATA aimed at large high-end systems. The SAS transport class contains common code to deal with SAS HBAs, an -aproximated representation of SAS topologies in the driver model, and +approximated representation of SAS topologies in the driver model, and various sysfs attributes to expose these topologies and management interfaces to userspace. diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index fb41768696ec..89f9c37bb979 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -422,7 +422,7 @@ USBDEVFS_CONNECTINFO USBDEVFS_GET_SPEED Returns the speed of the device. The speed is returned as a - nummerical value in accordance with enum usb_device_speed + numerical value in accordance with enum usb_device_speed File modification time is not updated by this request. diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst b/Documentation/driver-api/virtio/writing_virtio_drivers.rst index e14c58796d25..e5de6f5d061a 100644 --- a/Documentation/driver-api/virtio/writing_virtio_drivers.rst +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst @@ -97,7 +97,6 @@ like this:: static struct virtio_driver virtio_dummy_driver = { .driver.name = KBUILD_MODNAME, - .driver.owner = THIS_MODULE, .id_table = id_table, .probe = virtio_dummy_probe, .remove = virtio_dummy_remove, diff --git a/Documentation/driver-api/wbrf.rst b/Documentation/driver-api/wbrf.rst index f48bfa029813..6b18833e2e69 100644 --- a/Documentation/driver-api/wbrf.rst +++ b/Documentation/driver-api/wbrf.rst @@ -68,7 +68,7 @@ The expected flow for the consumers: can be enabled for the device. 2. Call `amd_wbrf_register_notifier` to register for notification of frequency band change(add or remove) from other producers. -3. Call the `amd_wbrf_retrieve_freq_band` initally to retrieve +3. Call the `amd_wbrf_retrieve_freq_band` initially to retrieve current active frequency bands considering some producers may broadcast such information before the consumer is up. 4. On receiving a notification for frequency band change, run diff --git a/Documentation/filesystems/bcachefs/index.rst b/Documentation/filesystems/bcachefs/index.rst new file mode 100644 index 000000000000..e2bd61ccd96f --- /dev/null +++ b/Documentation/filesystems/bcachefs/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================== +bcachefs Documentation +====================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + errorcodes diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst index 05ea387bc9fb..6fdf0b02df43 100644 --- a/Documentation/filesystems/directory-locking.rst +++ b/Documentation/filesystems/directory-locking.rst @@ -44,7 +44,7 @@ For our purposes all operations fall in 6 classes: * decide which of the source and target need to be locked. The source needs to be locked if it's a non-directory, target - if it's a non-directory or about to be removed. - * take the locks that need to be taken (exlusive), in inode pointer order + * take the locks that need to be taken (exclusive), in inode pointer order if need to take both (that can happen only when both source and target are non-directories - the source because it wouldn't need to be locked otherwise and the target because mixing directory and non-directory is @@ -234,7 +234,7 @@ among the children, in some order. But that is also impossible, since neither of the children is a descendent of another. That concludes the proof, since the set of operations with the -properties requiered for a minimal deadlock can not exist. +properties required for a minimal deadlock can not exist. Note that the check for having a common ancestor in cross-directory rename is crucial - without it a deadlock would be possible. Indeed, diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 0ea1e44fa028..1f9b4c905a6a 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -69,6 +69,7 @@ Documentation for filesystem implementations. afs autofs autofs-mount-control + bcachefs/index befs bfs btrfs diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 1be76ef117b3..f2b44c2400c6 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -858,7 +858,7 @@ be misspelled d_alloc_anon(). **mandatory** -[should've been added in 2016] stale comment in finish_open() nonwithstanding, +[should've been added in 2016] stale comment in finish_open() notwithstanding, failure exits in ->atomic_open() instances should *NOT* fput() the file, no matter what. Everything is handled by the caller. @@ -989,7 +989,7 @@ This mechanism would only work for a single device so the block layer couldn't find the owning superblock of any additional devices. In the old mechanism reusing or creating a superblock for a racing mount(2) and -umount(2) relied on the file_system_type as the holder. This was severly +umount(2) relied on the file_system_type as the holder. This was severely underdocumented however: (1) Any concurrent mounter that managed to grab an active reference on an diff --git a/Documentation/index.rst b/Documentation/index.rst index 5298611e00ee..f9f525f4c0dd 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -107,7 +107,7 @@ Other documentation There are several unsorted documents that don't seem to fit on other parts of the documentation body, or may require some adjustments and/or conversion -to ReStructured Text format, or are simply too old. +to reStructuredText format, or are simply too old. .. toctree:: :maxdepth: 1 diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index b1d97fafddcf..bb5c44f8bd1c 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -178,7 +178,7 @@ yet. Bug reports are always welcome at the issue tracker below! - ``LLVM=1`` * - s390 - Maintained - - ``CC=clang`` + - ``LLVM=1`` (LLVM >= 18.1.0), ``CC=clang`` (LLVM < 18.1.0) * - um (User Mode) - Maintained - ``LLVM=1`` diff --git a/Documentation/litmus-tests/README b/Documentation/litmus-tests/README index 658d37860d39..6c666f3422ea 100644 --- a/Documentation/litmus-tests/README +++ b/Documentation/litmus-tests/README @@ -21,6 +21,51 @@ Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus Test that atomic_set() cannot break the atomicity of atomic RMWs. NOTE: Require herd7 7.56 or later which supports "(void)expr". +cmpxchg-fail-ordered-1.litmus + Demonstrate that a failing cmpxchg() operation acts as a full barrier + when followed by smp_mb__after_atomic(). + +cmpxchg-fail-ordered-2.litmus + Demonstrate that a failing cmpxchg() operation acts as an acquire + operation when followed by smp_mb__after_atomic(). + +cmpxchg-fail-unordered-1.litmus + Demonstrate that a failing cmpxchg() operation does not act as a + full barrier. + +cmpxchg-fail-unordered-2.litmus + Demonstrate that a failing cmpxchg() operation does not act as an + acquire operation. + + +locking (/locking directory) +---------------------------- + +DCL-broken.litmus + Demonstrates that double-checked locking needs more than just + the obvious lock acquisitions and releases. + +DCL-fixed.litmus + Demonstrates corrected double-checked locking that uses + smp_store_release() and smp_load_acquire() in addition to the + obvious lock acquisitions and releases. + +RM-broken.litmus + Demonstrates problems with "roach motel" locking, where code is + freely moved into lock-based critical sections. This example also + shows how to use the "filter" clause to discard executions that + would be excluded by other code not modeled in the litmus test. + Note also that this "roach motel" optimization is emulated by + physically moving P1()'s two reads from x under the lock. + + What is a roach motel? This is from an old advertisement for + a cockroach trap, much later featured in one of the "Men in + Black" movies. "The roaches check in. They don't check out." + +RM-fixed.litmus + The counterpart to RM-broken.litmus, showing P0()'s two loads from + x safely outside of the critical section. + RCU (/rcu directory) -------------------- diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus new file mode 100644 index 000000000000..c0f93dc07105 --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus @@ -0,0 +1,35 @@ +C cmpxchg-fail-ordered-1 + +(* + * Result: Never + * + * Demonstrate that a failing cmpxchg() operation will act as a full + * barrier when followed by smp_mb__after_atomic(). + *) + +{} + +P0(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(z, 1, 0); + smp_mb__after_atomic(); + r0 = READ_ONCE(*y); +} + +P1(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*y, 1); + r1 = cmpxchg(z, 1, 0); + smp_mb__after_atomic(); + r0 = READ_ONCE(*x); +} + +locations[0:r1;1:r1] +exists (0:r0=0 /\ 1:r0=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus new file mode 100644 index 000000000000..5c06054f4694 --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus @@ -0,0 +1,30 @@ +C cmpxchg-fail-ordered-2 + +(* + * Result: Never + * + * Demonstrate use of smp_mb__after_atomic() to make a failing cmpxchg + * operation have acquire ordering. + *) + +{} + +P0(int *x, int *y) +{ + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(y, 0, 1); +} + +P1(int *x, int *y) +{ + int r1; + int r2; + + r1 = cmpxchg(y, 0, 1); + smp_mb__after_atomic(); + r2 = READ_ONCE(*x); +} + +exists (0:r1=0 /\ 1:r1=1 /\ 1:r2=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus new file mode 100644 index 000000000000..39ea1f56a28d --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus @@ -0,0 +1,34 @@ +C cmpxchg-fail-unordered-1 + +(* + * Result: Sometimes + * + * Demonstrate that a failing cmpxchg() operation does not act as a + * full barrier. (In contrast, a successful cmpxchg() does act as a + * full barrier.) + *) + +{} + +P0(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(z, 1, 0); + r0 = READ_ONCE(*y); +} + +P1(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*y, 1); + r1 = cmpxchg(z, 1, 0); + r0 = READ_ONCE(*x); +} + +locations[0:r1;1:r1] +exists (0:r0=0 /\ 1:r0=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus new file mode 100644 index 000000000000..61aab24a4a64 --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus @@ -0,0 +1,30 @@ +C cmpxchg-fail-unordered-2 + +(* + * Result: Sometimes + * + * Demonstrate that a failing cmpxchg() operation does not act as either + * an acquire release operation. (In contrast, a successful cmpxchg() + * does act as both an acquire and a release operation.) + *) + +{} + +P0(int *x, int *y) +{ + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(y, 0, 1); +} + +P1(int *x, int *y) +{ + int r1; + int r2; + + r1 = cmpxchg(y, 0, 1); + r2 = READ_ONCE(*x); +} + +exists (0:r1=0 /\ 1:r1=1 /\ 1:r2=0) diff --git a/Documentation/mm/page_owner.rst b/Documentation/mm/page_owner.rst index 0d0334cd5179..3a45a20fc05a 100644 --- a/Documentation/mm/page_owner.rst +++ b/Documentation/mm/page_owner.rst @@ -24,10 +24,10 @@ fragmentation statistics can be obtained through gfp flag information of each page. It is already implemented and activated if page owner is enabled. Other usages are more than welcome. -It can also be used to show all the stacks and their outstanding -allocations, which gives us a quick overview of where the memory is going -without the need to screen through all the pages and match the allocation -and free operation. +It can also be used to show all the stacks and their current number of +allocated base pages, which gives us a quick overview of where the memory +is going without the need to screen through all the pages and match the +allocation and free operation. page owner is disabled by default. So, if you'd like to use it, you need to add "page_owner=on" to your boot cmdline. If the kernel is built @@ -75,42 +75,45 @@ Usage cat /sys/kernel/debug/page_owner_stacks/show_stacks > stacks.txt cat stacks.txt - prep_new_page+0xa9/0x120 - get_page_from_freelist+0x7e6/0x2140 - __alloc_pages+0x18a/0x370 - new_slab+0xc8/0x580 - ___slab_alloc+0x1f2/0xaf0 - __slab_alloc.isra.86+0x22/0x40 - kmem_cache_alloc+0x31b/0x350 - __khugepaged_enter+0x39/0x100 - dup_mmap+0x1c7/0x5ce - copy_process+0x1afe/0x1c90 - kernel_clone+0x9a/0x3c0 - __do_sys_clone+0x66/0x90 - do_syscall_64+0x7f/0x160 - entry_SYSCALL_64_after_hwframe+0x6c/0x74 - stack_count: 234 + post_alloc_hook+0x177/0x1a0 + get_page_from_freelist+0xd01/0xd80 + __alloc_pages+0x39e/0x7e0 + allocate_slab+0xbc/0x3f0 + ___slab_alloc+0x528/0x8a0 + kmem_cache_alloc+0x224/0x3b0 + sk_prot_alloc+0x58/0x1a0 + sk_alloc+0x32/0x4f0 + inet_create+0x427/0xb50 + __sock_create+0x2e4/0x650 + inet_ctl_sock_create+0x30/0x180 + igmp_net_init+0xc1/0x130 + ops_init+0x167/0x410 + setup_net+0x304/0xa60 + copy_net_ns+0x29b/0x4a0 + create_new_namespaces+0x4a1/0x820 + nr_base_pages: 16 ... ... echo 7000 > /sys/kernel/debug/page_owner_stacks/count_threshold cat /sys/kernel/debug/page_owner_stacks/show_stacks> stacks_7000.txt cat stacks_7000.txt - prep_new_page+0xa9/0x120 - get_page_from_freelist+0x7e6/0x2140 - __alloc_pages+0x18a/0x370 - alloc_pages_mpol+0xdf/0x1e0 - folio_alloc+0x14/0x50 - filemap_alloc_folio+0xb0/0x100 - page_cache_ra_unbounded+0x97/0x180 - filemap_fault+0x4b4/0x1200 - __do_fault+0x2d/0x110 - do_pte_missing+0x4b0/0xa30 - __handle_mm_fault+0x7fa/0xb70 - handle_mm_fault+0x125/0x300 - do_user_addr_fault+0x3c9/0x840 - exc_page_fault+0x68/0x150 - asm_exc_page_fault+0x22/0x30 - stack_count: 8248 + post_alloc_hook+0x177/0x1a0 + get_page_from_freelist+0xd01/0xd80 + __alloc_pages+0x39e/0x7e0 + alloc_pages_mpol+0x22e/0x490 + folio_alloc+0xd5/0x110 + filemap_alloc_folio+0x78/0x230 + page_cache_ra_order+0x287/0x6f0 + filemap_get_pages+0x517/0x1160 + filemap_read+0x304/0x9f0 + xfs_file_buffered_read+0xe6/0x1d0 [xfs] + xfs_file_read_iter+0x1f0/0x380 [xfs] + __kernel_read+0x3b9/0x730 + kernel_read_file+0x309/0x4d0 + __do_sys_finit_module+0x381/0x730 + do_syscall_64+0x8d/0x150 + entry_SYSCALL_64_after_hwframe+0x62/0x6a + nr_base_pages: 20824 ... cat /sys/kernel/debug/page_owner > page_owner_full.txt diff --git a/Documentation/mm/slub.rst b/Documentation/mm/slub.rst index b517ee28a955..60d350d08362 100644 --- a/Documentation/mm/slub.rst +++ b/Documentation/mm/slub.rst @@ -80,7 +80,7 @@ to the dentry cache with:: Debugging options may require the minimum possible slab order to increase as a result of storing the metadata (for example, caches with PAGE_SIZE object -sizes). This has a higher liklihood of resulting in slab allocation errors +sizes). This has a higher likelihood of resulting in slab allocation errors in low memory situations or if there's high fragmentation of memory. To switch off debugging for such caches by default, use:: diff --git a/Documentation/netlink/specs/rt_link.yaml b/Documentation/netlink/specs/rt_link.yaml index 8e4d19adee8c..4e702ac8bf66 100644 --- a/Documentation/netlink/specs/rt_link.yaml +++ b/Documentation/netlink/specs/rt_link.yaml @@ -1144,6 +1144,12 @@ attribute-sets: - name: mcast-querier-state type: binary + - + name: fdb-n-learned + type: u32 + - + name: fdb-max-learned + type: u32 - name: linkinfo-brport-attrs name-prefix: ifla-brport- diff --git a/Documentation/networking/devlink/devlink-eswitch-attr.rst b/Documentation/networking/devlink/devlink-eswitch-attr.rst new file mode 100644 index 000000000000..08bb39ab1528 --- /dev/null +++ b/Documentation/networking/devlink/devlink-eswitch-attr.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +Devlink E-Switch Attribute +========================== + +Devlink E-Switch supports two modes of operation: legacy and switchdev. +Legacy mode operates based on traditional MAC/VLAN steering rules. Switching +decisions are made based on MAC addresses, VLANs, etc. There is limited ability +to offload switching rules to hardware. + +On the other hand, switchdev mode allows for more advanced offloading +capabilities of the E-Switch to hardware. In switchdev mode, more switching +rules and logic can be offloaded to the hardware switch ASIC. It enables +representor netdevices that represent the slow path of virtual functions (VFs) +or scalable-functions (SFs) of the device. See more information about +:ref:`Documentation/networking/switchdev.rst <switchdev>` and +:ref:`Documentation/networking/representors.rst <representors>`. + +In addition, the devlink E-Switch also comes with other attributes listed +in the following section. + +Attributes Description +====================== + +The following is a list of E-Switch attributes. + +.. list-table:: E-Switch attributes + :widths: 8 5 45 + + * - Name + - Type + - Description + * - ``mode`` + - enum + - The mode of the device. The mode can be one of the following: + + * ``legacy`` operates based on traditional MAC/VLAN steering + rules. + * ``switchdev`` allows for more advanced offloading capabilities of + the E-Switch to hardware. + * - ``inline-mode`` + - enum + - Some HWs need the VF driver to put part of the packet + headers on the TX descriptor so the e-switch can do proper + matching and steering. Support for both switchdev mode and legacy mode. + + * ``none`` none. + * ``link`` L2 mode. + * ``network`` L3 mode. + * ``transport`` L4 mode. + * - ``encap-mode`` + - enum + - The encapsulation mode of the device. Support for both switchdev mode + and legacy mode. The mode can be one of the following: + + * ``none`` Disable encapsulation support. + * ``basic`` Enable encapsulation support. + +Example Usage +============= + +.. code:: shell + + # enable switchdev mode + $ devlink dev eswitch set pci/0000:08:00.0 mode switchdev + + # set inline-mode and encap-mode + $ devlink dev eswitch set pci/0000:08:00.0 inline-mode none encap-mode basic + + # display devlink device eswitch attributes + $ devlink dev eswitch show pci/0000:08:00.0 + pci/0000:08:00.0: mode switchdev inline-mode none encap-mode basic + + # enable encap-mode with legacy mode + $ devlink dev eswitch set pci/0000:08:00.0 mode legacy inline-mode none encap-mode basic diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index e14d7a701b72..948c8c44e233 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -67,6 +67,7 @@ general. devlink-selftests devlink-trap devlink-linecard + devlink-eswitch-attr Driver-specific documentation ----------------------------- diff --git a/Documentation/networking/representors.rst b/Documentation/networking/representors.rst index decb39c19b9e..5e23386f6968 100644 --- a/Documentation/networking/representors.rst +++ b/Documentation/networking/representors.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _representors: ============================= Network Function Representors diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 7ef8de58f7f8..5d83958888e0 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 13.0.1 clang --version -Rust (optional) 1.76.0 rustc --version +Rust (optional) 1.78.0 rustc --version bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index bb2100228cc7..6e9a4597bf2c 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -252,7 +252,7 @@ an involved disclosed party. The current ambassadors list: AMD Tom Lendacky <thomas.lendacky@amd.com> Ampere Darren Hart <darren@os.amperecomputing.com> ARM Catalin Marinas <catalin.marinas@arm.com> - IBM Power Anton Blanchard <anton@linux.ibm.com> + IBM Power Michael Ellerman <ellerman@au.ibm.com> IBM Z Christian Borntraeger <borntraeger@de.ibm.com> Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <quic_tsoni@quicinc.com> diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index ce6753a674f3..49ba1410cfce 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -284,7 +284,7 @@ What else is there to known about regressions? Check out Documentation/admin-guide/reporting-regressions.rst, it covers a lot of other aspects you want might want to be aware of: - * the purpose of the "no regressions rule" + * the purpose of the "no regressions" rule * what issues actually qualify as regression diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 1704f1c686d0..edf90bbe30f4 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,29 +6,29 @@ Everything you ever wanted to know about Linux -stable releases Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: - - It or an equivalent fix must already exist in Linus' tree (upstream). - - It must be obviously correct and tested. - - It cannot be bigger than 100 lines, with context. - - It must follow the - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` - rules. - - It must either fix a real bug that bothers people or just add a device ID. - To elaborate on the former: - - - It fixes a problem like an oops, a hang, data corruption, a real security - issue, a hardware quirk, a build error (but not for things marked - CONFIG_BROKEN), or some "oh, that's not good" issue. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - No "This could be a problem..." type of things like a "theoretical race - condition", unless an explanation of how the bug can be exploited is also - provided. - - No "trivial" fixes without benefit for users (spelling changes, whitespace - cleanups, etc). +- It or an equivalent fix must already exist in Linux mainline (upstream). +- It must be obviously correct and tested. +- It cannot be bigger than 100 lines, with context. +- It must follow the + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + rules. +- It must either fix a real bug that bothers people or just add a device ID. + To elaborate on the former: + + - It fixes a problem like an oops, a hang, data corruption, a real security + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - No "This could be a problem..." type of things like a "theoretical race + condition", unless an explanation of how the bug can be exploited is also + provided. + - No "trivial" fixes without benefit for users (spelling changes, whitespace + cleanups, etc). Procedure for submitting patches to the -stable tree @@ -42,11 +42,11 @@ Procedure for submitting patches to the -stable tree There are three options to submit a change to -stable trees: - 1. Add a 'stable tag' to the description of a patch you then submit for - mainline inclusion. - 2. Ask the stable team to pick up a patch already mainlined. - 3. Submit a patch to the stable team that is equivalent to a change already - mainlined. +1. Add a 'stable tag' to the description of a patch you then submit for + mainline inclusion. +2. Ask the stable team to pick up a patch already mainlined. +3. Submit a patch to the stable team that is equivalent to a change already + mainlined. The sections below describe each of the options in more detail. @@ -68,82 +68,72 @@ Option 1 ******** To have a patch you submit for mainline inclusion later automatically picked up -for stable trees, add the tag +for stable trees, add this tag in the sign-off area:: -.. code-block:: none + Cc: stable@vger.kernel.org - Cc: stable@vger.kernel.org +Use ``Cc: stable@kernel.org`` instead when fixing unpublished vulnerabilities: +it reduces the chance of accidentally exposing the fix to the public by way of +'git send-email', as mails sent to that address are not delivered anywhere. -in the sign-off area. Once the patch is mainlined it will be applied to the -stable tree without anything else needing to be done by the author or -subsystem maintainer. +Once the patch is mainlined it will be applied to the stable tree without +anything else needing to be done by the author or subsystem maintainer. -To sent additional instructions to the stable team, use a shell-style inline -comment: +To send additional instructions to the stable team, use a shell-style inline +comment to pass arbitrary or predefined notes: - * To specify any additional patch prerequisites for cherry picking use the - following format in the sign-off area: +* Specify any additional patch prerequisites for cherry picking:: - .. code-block:: none + Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle + Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic + Cc: <stable@vger.kernel.org> # 3.3.x + Signed-off-by: Ingo Molnar <mingo@elte.hu> - Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle - Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic - Cc: <stable@vger.kernel.org> # 3.3.x - Signed-off-by: Ingo Molnar <mingo@elte.hu> + The tag sequence has the meaning of:: - The tag sequence has the meaning of: + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> - .. code-block:: none + Note that for a patch series, you do not have to list as prerequisites the + patches present in the series itself. For example, if you have the following + patch series:: - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick <this commit> + patch1 + patch2 - Note that for a patch series, you do not have to list as prerequisites the - patches present in the series itself. For example, if you have the following - patch series: + where patch2 depends on patch1, you do not have to list patch1 as + prerequisite of patch2 if you have already marked patch1 for stable + inclusion. - .. code-block:: none +* Point out kernel version prerequisites:: - patch1 - patch2 + Cc: <stable@vger.kernel.org> # 3.3.x - where patch2 depends on patch1, you do not have to list patch1 as - prerequisite of patch2 if you have already marked patch1 for stable - inclusion. + The tag has the meaning of:: - * For patches that may have kernel version prerequisites specify them using - the following format in the sign-off area: + git cherry-pick <this commit> - .. code-block:: none + For each "-stable" tree starting with the specified version. - Cc: <stable@vger.kernel.org> # 3.3.x + Note, such tagging is unnecessary if the stable team can derive the + appropriate versions from Fixes: tags. - The tag has the meaning of: +* Delay pick up of patches:: - .. code-block:: none + Cc: <stable@vger.kernel.org> # after -rc3 - git cherry-pick <this commit> +* Point out known problems:: - For each "-stable" tree starting with the specified version. + Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 - Note, such tagging is unnecessary if the stable team can derive the - appropriate versions from Fixes: tags. +There furthermore is a variant of the stable tag you can use to make the stable +team's backporting tools (e.g AUTOSEL or scripts that look for commits +containing a 'Fixes:' tag) ignore a change:: - * To delay pick up of patches, use the following format: - - .. code-block:: none - - Cc: <stable@vger.kernel.org> # after 4 weeks in mainline - - * For any other requests, just add a note to the stable tag. This for example - can be used to point out known problems: - - .. code-block:: none - - Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 + Cc: <stable+noautosel@kernel.org> # reason goes here, and must be present .. _option_2: @@ -163,17 +153,13 @@ Option 3 Send the patch, after verifying that it follows the above rules, to stable@vger.kernel.org and mention the kernel versions you wish it to be applied to. When doing so, you must note the upstream commit ID in the changelog of your -submission with a separate line above the commit text, like this: - -.. code-block:: none - - commit <sha1> upstream. +submission with a separate line above the commit text, like this:: -or alternatively: + commit <sha1> upstream. -.. code-block:: none +Or alternatively:: - [ Upstream commit <sha1> ] + [ Upstream commit <sha1> ] If the submitted patch deviates from the original upstream patch (for example because it had to be adjusted for the older API), this must be very clearly @@ -194,55 +180,55 @@ developers and by the relevant subsystem maintainer. Review cycle ------------ - - When the -stable maintainers decide for a review cycle, the patches will be - sent to the review committee, and the maintainer of the affected area of - the patch (unless the submitter is the maintainer of the area) and CC: to - the linux-kernel mailing list. - - The review committee has 48 hours in which to ACK or NAK the patch. - - If the patch is rejected by a member of the committee, or linux-kernel - members object to the patch, bringing up issues that the maintainers and - members did not realize, the patch will be dropped from the queue. - - The ACKed patches will be posted again as part of release candidate (-rc) - to be tested by developers and testers. - - Usually only one -rc release is made, however if there are any outstanding - issues, some patches may be modified or dropped or additional patches may - be queued. Additional -rc releases are then released and tested until no - issues are found. - - Responding to the -rc releases can be done on the mailing list by sending - a "Tested-by:" email with any testing information desired. The "Tested-by:" - tags will be collected and added to the release commit. - - At the end of the review cycle, the new -stable release will be released - containing all the queued and tested patches. - - Security patches will be accepted into the -stable tree directly from the - security kernel team, and not go through the normal review cycle. - Contact the kernel security team for more details on this procedure. +- When the -stable maintainers decide for a review cycle, the patches will be + sent to the review committee, and the maintainer of the affected area of + the patch (unless the submitter is the maintainer of the area) and CC: to + the linux-kernel mailing list. +- The review committee has 48 hours in which to ACK or NAK the patch. +- If the patch is rejected by a member of the committee, or linux-kernel + members object to the patch, bringing up issues that the maintainers and + members did not realize, the patch will be dropped from the queue. +- The ACKed patches will be posted again as part of release candidate (-rc) + to be tested by developers and testers. +- Usually only one -rc release is made, however if there are any outstanding + issues, some patches may be modified or dropped or additional patches may + be queued. Additional -rc releases are then released and tested until no + issues are found. +- Responding to the -rc releases can be done on the mailing list by sending + a "Tested-by:" email with any testing information desired. The "Tested-by:" + tags will be collected and added to the release commit. +- At the end of the review cycle, the new -stable release will be released + containing all the queued and tested patches. +- Security patches will be accepted into the -stable tree directly from the + security kernel team, and not go through the normal review cycle. + Contact the kernel security team for more details on this procedure. Trees ----- - - The queues of patches, for both completed versions and in progress - versions can be found at: +- The queues of patches, for both completed versions and in progress + versions can be found at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git - - The finalized and tagged releases of all stable kernels can be found - in separate branches per version at: +- The finalized and tagged releases of all stable kernels can be found + in separate branches per version at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git - - The release candidate of all stable kernel versions can be found at: +- The release candidate of all stable kernel versions can be found at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ - .. warning:: - The -stable-rc tree is a snapshot in time of the stable-queue tree and - will change frequently, hence will be rebased often. It should only be - used for testing purposes (e.g. to be consumed by CI systems). + .. warning:: + The -stable-rc tree is a snapshot in time of the stable-queue tree and + will change frequently, hence will be rebased often. It should only be + used for testing purposes (e.g. to be consumed by CI systems). Review committee ---------------- - - This is made up of a number of kernel developers who have volunteered for - this task, and a few that haven't. +- This is made up of a number of kernel developers who have volunteered for + this task, and a few that haven't. diff --git a/Documentation/rust/arch-support.rst b/Documentation/rust/arch-support.rst index 5c4fa9f5d1cd..c9137710633a 100644 --- a/Documentation/rust/arch-support.rst +++ b/Documentation/rust/arch-support.rst @@ -16,7 +16,7 @@ support corresponds to ``S`` values in the ``MAINTAINERS`` file. Architecture Level of support Constraints ============= ================ ============================================== ``arm64`` Maintained Little Endian only. -``loongarch`` Maintained - +``loongarch`` Maintained \- ``um`` Maintained ``x86_64`` only. ``x86`` Maintained ``x86_64`` only. ============= ================ ============================================== diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst index 081397827a7e..4bb6ac12d482 100644 --- a/Documentation/rust/general-information.rst +++ b/Documentation/rust/general-information.rst @@ -64,6 +64,63 @@ but it is intended that coverage is expanded as time goes on. "Leaf" modules (e.g. drivers) should not use the C bindings directly. Instead, subsystems should provide as-safe-as-possible abstractions as needed. +.. code-block:: + + rust/bindings/ + (rust/helpers.c) + + include/ -----+ <-+ + | | + drivers/ rust/kernel/ +----------+ <-+ | + fs/ | bindgen | | + .../ +-------------------+ +----------+ --+ | + | Abstractions | | | + +---------+ | +------+ +------+ | +----------+ | | + | my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ | + | driver | Safe | | sub- | | sub- | | Unsafe | | | + +---------+ | |system| |system| | | bindings | <-----+ + | | +------+ +------+ | | crate | | + | | kernel crate | +----------+ | + | +-------------------+ | + | | + +------------------# FORBIDDEN #--------------------------------+ + +The main idea is to encapsulate all direct interaction with the kernel's C APIs +into carefully reviewed and documented abstractions. Then users of these +abstractions cannot introduce undefined behavior (UB) as long as: + +#. The abstractions are correct ("sound"). +#. Any ``unsafe`` blocks respect the safety contract necessary to call the + operations inside the block. Similarly, any ``unsafe impl``\ s respect the + safety contract necessary to implement the trait. + +Bindings +~~~~~~~~ + +By including a C header from ``include/`` into +``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the +bindings for the included subsystem. After building, see the ``*_generated.rs`` +output files in the ``rust/bindings/`` directory. + +For parts of the C header that ``bindgen`` does not auto generate, e.g. C +``inline`` functions or non-trivial macros, it is acceptable to add a small +wrapper function to ``rust/helpers.c`` to make it available for the Rust side as +well. + +Abstractions +~~~~~~~~~~~~ + +Abstractions are the layer between the bindings and the in-kernel users. They +are located in ``rust/kernel/`` and their role is to encapsulate the unsafe +access to the bindings into an as-safe-as-possible API that they expose to their +users. Users of the abstractions include things like drivers or file systems +written in Rust. + +Besides the safety aspect, the abstractions are supposed to be "ergonomic", in +the sense that they turn the C interfaces into "idiomatic" Rust code. Basic +examples are to turn the C resource acquisition and release into Rust +constructors and destructors or C integer error codes into Rust's ``Result``\ s. + Conditional compilation ----------------------- diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst index 6658998d1b6c..acfd0c2be48d 100644 --- a/Documentation/rust/testing.rst +++ b/Documentation/rust/testing.rst @@ -6,10 +6,11 @@ Testing This document contains useful information how to test the Rust code in the kernel. -There are two sorts of tests: +There are three sorts of tests: - The KUnit tests. - The ``#[test]`` tests. +- The Kselftests. The KUnit tests --------------- @@ -133,3 +134,25 @@ Additionally, there are the ``#[test]`` tests. These can be run using the This requires the kernel ``.config`` and downloads external repositories. It runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in what these tests can test. + +The Kselftests +-------------- + +Kselftests are also available in the ``tools/testing/selftests/rust`` folder. + +The kernel config options required for the tests are listed in the +``tools/testing/selftests/rust/config`` file and can be included with the aid +of the ``merge_config.sh`` script:: + + ./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config + +The kselftests are built within the kernel source tree and are intended to +be executed on a system that is running the same kernel. + +Once a kernel matching the source tree has been installed and booted, the +tests can be compiled and executed using the following command:: + + make TARGETS="rust" kselftest + +Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest +documentation. diff --git a/Documentation/security/SCTP.rst b/Documentation/security/SCTP.rst index b73eb764a001..6d80d464ab6e 100644 --- a/Documentation/security/SCTP.rst +++ b/Documentation/security/SCTP.rst @@ -81,7 +81,7 @@ A summary of the ``@optname`` entries is as follows:: destination addresses. SCTP_SENDMSG_CONNECT - Initiate a connection that is generated by a - sendmsg(2) or sctp_sendmsg(3) on a new asociation. + sendmsg(2) or sctp_sendmsg(3) on a new association. SCTP_PRIMARY_ADDR - Set local primary address. diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index e989b9802f92..f4d7e162d5e4 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -42,6 +42,14 @@ safe. randomly generated and fused into each SoC at manufacturing time. Otherwise, a common fixed test key is used instead. + (4) DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) + + Rooted to a one-time programmable key (OTP) that is generally burnt + in the on-chip fuses and is accessible to the DCP encryption engine only. + DCP provides two keys that can be used as root of trust: the OTP key + and the UNIQUE key. Default is to use the UNIQUE key, but selecting + the OTP key can be done via a module parameter (dcp_use_otp_key). + * Execution isolation (1) TPM @@ -57,6 +65,12 @@ safe. Fixed set of operations running in isolated execution environment. + (4) DCP + + Fixed set of cryptographic operations running in isolated execution + environment. Only basic blob key encryption is executed there. + The actual key sealing/unsealing is done on main processor/kernel space. + * Optional binding to platform integrity state (1) TPM @@ -79,6 +93,11 @@ safe. Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs for platform integrity. + (4) DCP + + Relies on Secure/Trusted boot process (called HAB by vendor) for + platform integrity. + * Interfaces and APIs (1) TPM @@ -94,6 +113,11 @@ safe. Interface is specific to silicon vendor. + (4) DCP + + Vendor-specific API that is implemented as part of the DCP crypto driver in + ``drivers/crypto/mxs-dcp.c``. + * Threat model The strength and appropriateness of a particular trust source for a given @@ -129,6 +153,13 @@ selected trust source: CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device is probed. + * DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs) + + The DCP hardware device itself does not provide a dedicated RNG interface, + so the kernel default RNG is used. SoCs with DCP like the i.MX6ULL do have + a dedicated hardware RNG that is independent from DCP which can be enabled + to back the kernel RNG. + Users may override this by specifying ``trusted.rng=kernel`` on the kernel command-line to override the used RNG with the kernel's random number pool. @@ -231,6 +262,19 @@ Usage:: CAAM-specific format. The key length for new keys is always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). +Trusted Keys usage: DCP +----------------------- + +Usage:: + + keyctl add trusted name "new keylen" ring + keyctl add trusted name "load hex_blob" ring + keyctl print keyid + +"keyctl print" returns an ASCII hex copy of the sealed key, which is in format +specific to this DCP key-blob implementation. The key length for new keys is +always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits). + Encrypted Keys usage -------------------- @@ -426,3 +470,12 @@ string length. privkey is the binary representation of TPM2B_PUBLIC excluding the initial TPM2B header which can be reconstructed from the ASN.1 octed string length. + +DCP Blob Format +--------------- + +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c + :doc: dcp blob format + +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c + :identifiers: struct dcp_blob_fmt diff --git a/Documentation/security/snp-tdx-threat-model.rst b/Documentation/security/snp-tdx-threat-model.rst index ec66f2ed80c9..3a2d41d2e645 100644 --- a/Documentation/security/snp-tdx-threat-model.rst +++ b/Documentation/security/snp-tdx-threat-model.rst @@ -4,7 +4,7 @@ Confidential Computing in Linux for x86 virtualization .. contents:: :local: -By: Elena Reshetova <elena.reshetova@intel.com> and Carlos Bilbao <carlos.bilbao@amd.com> +By: Elena Reshetova <elena.reshetova@intel.com> and Carlos Bilbao <carlos.bilbao.osdev@gmail.com> Motivation ========== diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst index fc40e9f23c85..fa593d960040 100644 --- a/Documentation/security/tpm/index.rst +++ b/Documentation/security/tpm/index.rst @@ -5,6 +5,8 @@ Trusted Platform Module documentation .. toctree:: tpm_event_log + tpm-security + tpm_tis tpm_vtpm_proxy xen-tpmfront tpm_ftpm_tee diff --git a/Documentation/security/tpm/tpm-security.rst b/Documentation/security/tpm/tpm-security.rst new file mode 100644 index 000000000000..4f633f251033 --- /dev/null +++ b/Documentation/security/tpm/tpm-security.rst @@ -0,0 +1,216 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +TPM Security +============ + +The object of this document is to describe how we make the kernel's +use of the TPM reasonably robust in the face of external snooping and +packet alteration attacks (called passive and active interposer attack +in the literature). The current security document is for TPM 2.0. + +Introduction +------------ + +The TPM is usually a discrete chip attached to a PC via some type of +low bandwidth bus. There are exceptions to this such as the Intel +PTT, which is a software TPM running inside a software environment +close to the CPU, which are subject to different attacks, but right at +the moment, most hardened security environments require a discrete +hardware TPM, which is the use case discussed here. + +Snooping and Alteration Attacks against the bus +----------------------------------------------- + +The current state of the art for snooping the `TPM Genie`_ hardware +interposer which is a simple external device that can be installed in +a couple of seconds on any system or laptop. Recently attacks were +successfully demonstrated against the `Windows Bitlocker TPM`_ system. +Most recently the same `attack against TPM based Linux disk +encryption`_ schemes. The next phase of research seems to be hacking +existing devices on the bus to act as interposers, so the fact that +the attacker requires physical access for a few seconds might +evaporate. However, the goal of this document is to protect TPM +secrets and integrity as far as we are able in this environment and to +try to insure that if we can't prevent the attack then at least we can +detect it. + +Unfortunately, most of the TPM functionality, including the hardware +reset capability can be controlled by an attacker who has access to +the bus, so we'll discuss some of the disruption possibilities below. + +Measurement (PCR) Integrity +--------------------------- + +Since the attacker can send their own commands to the TPM, they can +send arbitrary PCR extends and thus disrupt the measurement system, +which would be an annoying denial of service attack. However, there +are two, more serious, classes of attack aimed at entities sealed to +trust measurements. + +1. The attacker could intercept all PCR extends coming from the system + and completely substitute their own values, producing a replay of + an untampered state that would cause PCR measurements to attest to + a trusted state and release secrets + +2. At some point in time the attacker could reset the TPM, clearing + the PCRs and then send down their own measurements which would + effectively overwrite the boot time measurements the TPM has + already done. + +The first can be thwarted by always doing HMAC protection of the PCR +extend and read command meaning measurement values cannot be +substituted without producing a detectable HMAC failure in the +response. However, the second can only really be detected by relying +on some sort of mechanism for protection which would change over TPM +reset. + +Secrets Guarding +---------------- + +Certain information passing in and out of the TPM, such as key sealing +and private key import and random number generation, is vulnerable to +interception which HMAC protection alone cannot protect against, so +for these types of command we must also employ request and response +encryption to prevent the loss of secret information. + +Establishing Initial Trust with the TPM +--------------------------------------- + +In order to provide security from the beginning, an initial shared or +asymmetric secret must be established which must also be unknown to +the attacker. The most obvious avenues for this are the endorsement +and storage seeds, which can be used to derive asymmetric keys. +However, using these keys is difficult because the only way to pass +them into the kernel would be on the command line, which requires +extensive support in the boot system, and there's no guarantee that +either hierarchy would not have some type of authorization. + +The mechanism chosen for the Linux Kernel is to derive the primary +elliptic curve key from the null seed using the standard storage seed +parameters. The null seed has two advantages: firstly the hierarchy +physically cannot have an authorization, so we are always able to use +it and secondly, the null seed changes across TPM resets, meaning if +we establish trust on the null seed at start of day, all sessions +salted with the derived key will fail if the TPM is reset and the seed +changes. + +Obviously using the null seed without any other prior shared secrets, +we have to create and read the initial public key which could, of +course, be intercepted and substituted by the bus interposer. +However, the TPM has a key certification mechanism (using the EK +endorsement certificate, creating an attestation identity key and +certifying the null seed primary with that key) which is too complex +to run within the kernel, so we keep a copy of the null primary key +name, which is what is exported via sysfs so user-space can run the +full certification when it boots. The definitive guarantee here is +that if the null primary key certifies correctly, you know all your +TPM transactions since start of day were secure and if it doesn't, you +know there's an interposer on your system (and that any secret used +during boot may have been leaked). + +Stacking Trust +-------------- + +In the current null primary scenario, the TPM must be completely +cleared before handing it on to the next consumer. However the kernel +hands to user-space the name of the derived null seed key which can +then be verified by certification in user-space. Therefore, this chain +of name handoff can be used between the various boot components as +well (via an unspecified mechanism). For instance, grub could use the +null seed scheme for security and hand the name off to the kernel in +the boot area. The kernel could make its own derivation of the key +and the name and know definitively that if they differ from the handed +off version that tampering has occurred. Thus it becomes possible to +chain arbitrary boot components together (UEFI to grub to kernel) via +the name handoff provided each successive component knows how to +collect the name and verifies it against its derived key. + +Session Properties +------------------ + +All TPM commands the kernel uses allow sessions. HMAC sessions may be +used to check the integrity of requests and responses and decrypt and +encrypt flags may be used to shield parameters and responses. The +HMAC and encryption keys are usually derived from the shared +authorization secret, but for a lot of kernel operations that is well +known (and usually empty). Thus, every HMAC session used by the +kernel must be created using the null primary key as the salt key +which thus provides a cryptographic input into the session key +derivation. Thus, the kernel creates the null primary key once (as a +volatile TPM handle) and keeps it around in a saved context stored in +tpm_chip for every in-kernel use of the TPM. Currently, because of a +lack of de-gapping in the in-kernel resource manager, the session must +be created and destroyed for each operation, but, in future, a single +session may also be reused for the in-kernel HMAC, encryption and +decryption sessions. + +Protection Types +---------------- + +For every in-kernel operation we use null primary salted HMAC to +protect the integrity. Additionally, we use parameter encryption to +protect key sealing and parameter decryption to protect key unsealing +and random number generation. + +Null Primary Key Certification in Userspace +=========================================== + +Every TPM comes shipped with a couple of X.509 certificates for the +primary endorsement key. This document assumes that the Elliptic +Curve version of the certificate exists at 01C00002, but will work +equally well with the RSA certificate (at 01C00001). + +The first step in the certification is primary creation using the +template from the `TCG EK Credential Profile`_ which allows comparison +of the generated primary key against the one in the certificate (the +public key must match). Note that generation of the EK primary +requires the EK hierarchy password, but a pre-generated version of the +EC primary should exist at 81010002 and a TPM2_ReadPublic() may be +performed on this without needing the key authority. Next, the +certificate itself must be verified to chain back to the manufacturer +root (which should be published on the manufacturer website). Once +this is done, an attestation key (AK) is generated within the TPM and +it's name and the EK public key can be used to encrypt a secret using +TPM2_MakeCredential. The TPM then runs TPM2_ActivateCredential which +will only recover the secret if the binding between the TPM, the EK +and the AK is true. the generated AK may now be used to run a +certification of the null primary key whose name the kernel has +exported. Since TPM2_MakeCredential/ActivateCredential are somewhat +complicated, a more simplified process involving an externally +generated private key is described below. + +This process is a simplified abbreviation of the usual privacy CA +based attestation process. The assumption here is that the +attestation is done by the TPM owner who thus has access to only the +owner hierarchy. The owner creates an external public/private key +pair (assume elliptic curve in this case) and wraps the private key +for import using an inner wrapping process and parented to the EC +derived storage primary. The TPM2_Import() is done using a parameter +decryption HMAC session salted to the EK primary (which also does not +require the EK key authority) meaning that the inner wrapping key is +the encrypted parameter and thus the TPM will not be able to perform +the import unless is possesses the certified EK so if the command +succeeds and the HMAC verifies on return we know we have a loadable +copy of the private key only for the certified TPM. This key is now +loaded into the TPM and the Storage primary flushed (to free up space +for the null key generation). + +The null EC primary is now generated using the Storage profile +outlined in the `TCG TPM v2.0 Provisioning Guidance`_; the name of +this key (the hash of the public area) is computed and compared to the +null seed name presented by the kernel in +/sys/class/tpm/tpm0/null_name. If the names do not match, the TPM is +compromised. If the names match, the user performs a TPM2_Certify() +using the null primary as the object handle and the loaded private key +as the sign handle and providing randomized qualifying data. The +signature of the returned certifyInfo is verified against the public +part of the loaded private key and the qualifying data checked to +prevent replay. If all of these tests pass, the user is now assured +that TPM integrity and privacy was preserved across the entire boot +sequence of this kernel. + +.. _TPM Genie: https://www.nccgroup.trust/globalassets/about-us/us/documents/tpm-genie.pdf +.. _Windows Bitlocker TPM: https://dolosgroup.io/blog/2021/7/9/from-stolen-laptop-to-inside-the-company-network +.. _attack against TPM based Linux disk encryption: https://www.secura.com/blog/tpm-sniffing-attacks-against-non-bitlocker-targets +.. _TCG EK Credential Profile: https://trustedcomputinggroup.org/resource/tcg-ek-credential-profile-for-tpm-family-2-0/ +.. _TCG TPM v2.0 Provisioning Guidance: https://trustedcomputinggroup.org/resource/tcg-tpm-v2-0-provisioning-guidance/ diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst new file mode 100644 index 000000000000..b9637f295638 --- /dev/null +++ b/Documentation/security/tpm/tpm_tis.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +TPM FIFO interface driver +========================= + +TCG PTP Specification defines two interface types: FIFO and CRB. The former is +based on sequenced read and write operations, and the latter is based on a +buffer containing the full command or response. + +FIFO (First-In-First-Out) interface is used by the tpm_tis_core dependent +drivers. Originally Linux had only a driver called tpm_tis, which covered +memory mapped (aka MMIO) interface but it was later on extended to cover other +physical interfaces supported by the TCG standard. + +For historical reasons above the original MMIO driver is called tpm_tis and the +framework for FIFO drivers is named as tpm_tis_core. The postfix "tis" in +tpm_tis comes from the TPM Interface Specification, which is the hardware +interface specification for TPM 1.x chips. + +Communication is based on a 20 KiB buffer shared by the TPM chip through a +hardware bus or memory map, depending on the physical wiring. The buffer is +further split into five equal-size 4 KiB buffers, which provide equivalent +sets of registers for communication between the CPU and TPM. These +communication endpoints are called localities in the TCG terminology. + +When the kernel wants to send commands to the TPM chip, it first reserves +locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is +cleared by the chip when the access is granted. Once it completes its +communication, the kernel writes the TPM_ACCESS.activeLocality bit. This +informs the chip that the locality has been relinquished. + +Pending localities are served in order by the chip in descending order, one at +a time: + +- Locality 0 has the lowest priority. +- Locality 5 has the highest priority. + +Further information on the purpose and meaning of the localities can be found +in section 3.2 of the TCG PC Client Platform TPM Profile Specification. + +References +========== + +TCG PC Client Platform TPM Profile (PTP) Specification +https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/ diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index abe768088377..638762442336 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -97,7 +97,6 @@ class KernelInclude(Include): # HINT: this is the only line I had to change / commented out: #path = utils.relative_path(None, path) - path = nodes.reprunicode(path) encoding = self.options.get( 'encoding', self.state.document.settings.input_encoding) e_handler=self.state.document.settings.input_encoding_error_handler diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty index 3092df051c95..d479cfa73658 100644 --- a/Documentation/sphinx/kerneldoc-preamble.sty +++ b/Documentation/sphinx/kerneldoc-preamble.sty @@ -215,11 +215,12 @@ due to the lack of suitable font families and/or the texlive-xecjk package. - If you want them, please install ``Noto Sans CJK'' font families - along with the texlive-xecjk package by following instructions from + If you want them, please install non-variable ``Noto Sans CJK'' + font families along with the texlive-xecjk package by following + instructions from \sphinxcode{./scripts/sphinx-pre-install}. - Having optional ``Noto Serif CJK'' font families will improve - the looks of those translations. + Having optional non-variable ``Noto Serif CJK'' font families will + improve the looks of those translations. \end{sphinxadmonition}} \newcommand{\kerneldocEndSC}{} \newcommand{\kerneldocBeginTC}[1]{} diff --git a/Documentation/tee/index.rst b/Documentation/tee/index.rst index a23bd08847e5..4be6e69d7837 100644 --- a/Documentation/tee/index.rst +++ b/Documentation/tee/index.rst @@ -10,6 +10,7 @@ TEE Subsystem tee op-tee amd-tee + ts-tee .. only:: subproject and html diff --git a/Documentation/tee/ts-tee.rst b/Documentation/tee/ts-tee.rst new file mode 100644 index 000000000000..843e34422648 --- /dev/null +++ b/Documentation/tee/ts-tee.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +TS-TEE (Trusted Services project) +================================= + +This driver provides access to secure services implemented by Trusted Services. + +Trusted Services [1] is a TrustedFirmware.org project that provides a framework +for developing and deploying device Root of Trust services in FF-A [2] S-EL0 +Secure Partitions. The project hosts the reference implementation of the Arm +Platform Security Architecture [3] for Arm A-profile devices. + +The FF-A Secure Partitions (SP) are accessible through the FF-A driver [4] which +provides the low level communication for this driver. On top of that the Trusted +Services RPC protocol is used [5]. To use the driver from user space a reference +implementation is provided at [6], which is part of the Trusted Services client +library called libts [7]. + +All Trusted Services (TS) SPs have the same FF-A UUID; it identifies the TS RPC +protocol. A TS SP can host one or more services (e.g. PSA Crypto, PSA ITS, etc). +A service is identified by its service UUID; the same type of service cannot be +present twice in the same SP. During SP boot each service in the SP is assigned +an "interface ID". This is just a short ID to simplify message addressing. + +The generic TEE design is to share memory at once with the Trusted OS, which can +then be reused to communicate with multiple applications running on the Trusted +OS. However, in case of FF-A, memory sharing works on an endpoint level, i.e. +memory is shared with a specific SP. User space has to be able to separately +share memory with each SP based on its endpoint ID; therefore a separate TEE +device is registered for each discovered TS SP. Opening the SP corresponds to +opening the TEE device and creating a TEE context. A TS SP hosts one or more +services. Opening a service corresponds to opening a session in the given +tee_context. + +Overview of a system with Trusted Services components:: + + User space Kernel space Secure world + ~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~~~~~ + +--------+ +-------------+ + | Client | | Trusted | + +--------+ | Services SP | + /\ +-------------+ + || /\ + || || + || || + \/ \/ + +-------+ +----------+--------+ +-------------+ + | libts | | TEE | TS-TEE | | FF-A SPMC | + | | | subsys | driver | | + SPMD | + +-------+----------------+----+-----+--------+-----------+-------------+ + | Generic TEE API | | FF-A | TS RPC protocol | + | IOCTL (TEE_IOC_*) | | driver | over FF-A | + +-----------------------------+ +--------+-------------------------+ + +References +========== + +[1] https://www.trustedfirmware.org/projects/trusted-services/ + +[2] https://developer.arm.com/documentation/den0077/ + +[3] https://www.arm.com/architecture/security-features/platform-security + +[4] drivers/firmware/arm_ffa/ + +[5] https://trusted-services.readthedocs.io/en/v1.0.0/developer/service-access-protocols.html#abi + +[6] https://git.trustedfirmware.org/TS/trusted-services.git/tree/components/rpc/ts_rpc/caller/linux/ts_rpc_caller_linux.c?h=v1.0.0 + +[7] https://git.trustedfirmware.org/TS/trusted-services.git/tree/deployments/libts/arm-linux/CMakeLists.txt?h=v1.0.0 diff --git a/Documentation/timers/no_hz.rst b/Documentation/timers/no_hz.rst index f8786be15183..7fe8ef9718d8 100644 --- a/Documentation/timers/no_hz.rst +++ b/Documentation/timers/no_hz.rst @@ -129,11 +129,8 @@ adaptive-tick CPUs: At least one non-adaptive-tick CPU must remain online to handle timekeeping tasks in order to ensure that system calls like gettimeofday() returns accurate values on adaptive-tick CPUs. (This is not an issue for CONFIG_NO_HZ_IDLE=y because there are no running -user processes to observe slight drifts in clock rate.) Therefore, the -boot CPU is prohibited from entering adaptive-ticks mode. Specifying a -"nohz_full=" mask that includes the boot CPU will result in a boot-time -error message, and the boot CPU will be removed from the mask. Note that -this means that your system must have at least two CPUs in order for +user processes to observe slight drifts in clock rate.) Note that this +means that your system must have at least two CPUs in order for CONFIG_NO_HZ_FULL=y to do anything for you. Finally, adaptive-ticks CPUs must have their RCU callbacks offloaded. diff --git a/Documentation/trace/fprobetrace.rst b/Documentation/trace/fprobetrace.rst index 0f187e3796e4..b4c2ca3d02c1 100644 --- a/Documentation/trace/fprobetrace.rst +++ b/Documentation/trace/fprobetrace.rst @@ -74,7 +74,7 @@ Function arguments at exit -------------------------- Function arguments can be accessed at exit probe using $arg<N> fetcharg. This is useful to record the function parameter and return value at once, and -trace the difference of structure fields (for debuging a function whether it +trace the difference of structure fields (for debugging a function whether it correctly updates the given data structure or not) See the :ref:`sample<fprobetrace_exit_args_sample>` below for how it works. @@ -248,4 +248,4 @@ mode. You can trace that changes with return probe. cat-143 [007] ...1. 1945.720616: vfs_open__entry: (vfs_open+0x4/0x40) mode=0x1 inode=0x0 cat-143 [007] ...1. 1945.728263: vfs_open__exit: (do_open+0x274/0x3d0 <- vfs_open) mode=0xa800d inode=0xffff888004ada8d8 -You can see the `file::f_mode` and `file::f_inode` are upated in `vfs_open()`. +You can see the `file::f_mode` and `file::f_inode` are updated in `vfs_open()`. diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 7e7b8ec17934..5aba74872ba7 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -1968,7 +1968,7 @@ wakeup One common case that people are interested in tracing is the time it takes for a task that is woken to actually wake up. Now for non Real-Time tasks, this can be arbitrary. But tracing -it none the less can be interesting. +it nonetheless can be interesting. Without function tracing:: diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst index e1636e579c9c..5e606730cec6 100644 --- a/Documentation/trace/kprobes.rst +++ b/Documentation/trace/kprobes.rst @@ -322,6 +322,7 @@ architectures: - s390 - parisc - loongarch +- riscv Configuring Kprobes =================== diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index a49662ccd53c..69cb7776ae99 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -74,7 +74,7 @@ Function arguments at kretprobe ------------------------------- Function arguments can be accessed at kretprobe using $arg<N> fetcharg. This is useful to record the function parameter and return value at once, and -trace the difference of structure fields (for debuging a function whether it +trace the difference of structure fields (for debugging a function whether it correctly updates the given data structure or not). See the :ref:`sample<fprobetrace_exit_args_sample>` in fprobe event for how it works. diff --git a/Documentation/trace/tracepoints.rst b/Documentation/trace/tracepoints.rst index 0cb8d9ca3d60..decabcc77b56 100644 --- a/Documentation/trace/tracepoints.rst +++ b/Documentation/trace/tracepoints.rst @@ -27,7 +27,7 @@ the tracepoint site). You can put tracepoints at important locations in the code. They are lightweight hooks that can pass an arbitrary number of parameters, -which prototypes are described in a tracepoint declaration placed in a +whose prototypes are described in a tracepoint declaration placed in a header file. They can be used for tracing and performance accounting. diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 5cece223b46b..74057d203539 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -180,9 +180,9 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome se provate a formattare bene il vostro testo come nel seguente esempio:: * Return: - * 0 - OK - * -EINVAL - invalid argument - * -ENOMEM - out of memory + * %0 - OK + * %-EINVAL - invalid argument + * %-ENOMEM - out of memory le righe verranno unite e il risultato sarà:: @@ -192,8 +192,8 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome utilizzare una lista ReST, ad esempio:: * Return: - * * 0 - OK to runtime suspend the device - * * -EBUSY - Device should not be runtime suspended + * * %0 - OK to runtime suspend the device + * * %-EBUSY - Device should not be runtime suspended #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai due punti, allora ognuna di queste frasi verrà considerata come il nome diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index 70ccd23b2cde..9220f65e30d1 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -132,4 +132,4 @@ Documentazione varia Ci sono documenti che sono difficili da inserire nell'attuale organizzazione della documentazione; altri hanno bisogno di essere migliorati e/o convertiti -nel formato *ReStructured Text*; altri sono semplicamente troppo vecchi. +nel formato *reStructuredText*; altri sono semplicamente troppo vecchi. diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst index 25cd00351c03..0a62c0f33faf 100644 --- a/Documentation/translations/it_IT/process/2.Process.rst +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -462,9 +462,12 @@ linux-kernel: di far domande. Molti sviluppatori possono divenire impazienti con le persone che chiaramente non hanno svolto i propri compiti a casa. -- Evitate il *top-posting* (cioè la pratica di mettere la vostra risposta sopra - alla frase alla quale state rispondendo). Ciò renderebbe la vostra risposta - difficile da leggere e genera scarsa impressione. +- Rispondete sotto alla porzione di righe citate, così da dare un contesto alle + vostre risposte, e quindi renderle più leggibili (in altre parole, evitate di + rispondere in cima, ovvero prima del testo citato). Per maggiori dettagli + leggete :ref:`Documentation/translations/it_IT/process/submitting-patches.rst + <it_interleaved_replies>`. + - Chiedete nella lista di discussione corretta. Linux-kernel può essere un punto di incontro generale, ma non è il miglior posto dove trovare diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst index 54fd255b77d0..ec874a8dfb9d 100644 --- a/Documentation/translations/it_IT/process/4.Coding.rst +++ b/Documentation/translations/it_IT/process/4.Coding.rst @@ -72,6 +72,10 @@ compiti del genere. Consultate il file :ref:`Documentation/translations/it_IT/process/clang-format.rst <clangformat>` per maggiori dettagli +Se utilizzate un programma compatibile con EditorConfig, allora alcune +configurazioni basilari come l'indentazione e la fine delle righe verranno +applicate automaticamente. Per maggiori informazioni consultate la pagina: +https://editorconfig.org/ Livelli di astrazione ********************* diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst index dffd813a0910..a83fcfe18024 100644 --- a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -160,6 +160,8 @@ preparerà una richiesta nel modo in cui gli altri sviluppatori se l'aspettano, e verificherà che vi siate ricordati di pubblicare quelle patch su un server pubblico. +.. _development_advancedtopics_reviews_it: + Revisionare le patch -------------------- @@ -180,6 +182,13 @@ i commenti come domande e non come critiche. Chiedere "Come viene rilasciato il *lock* in questo percorso?" funziona sempre molto meglio che "qui la sincronizzazione è sbagliata". +In caso di disaccordi, può essere utile chiedere una terza opinione. Se dopo +pochi scambi la discussione raggiunge un punto morto, allora chiedete ai +manutentori o altri revisori di partecipare esprimendo la loro opinione. Spesso +vige un silenzio assenso per cui gli altri revisori non intervengono se non gli +viene richiesto esplicitamente. L'opinione di più persone avrà sicuramente un +peso maggiore. + Diversi sviluppatori revisioneranno il codice con diversi punti di vista. Alcuni potrebbero concentrarsi principalmente sullo stile del codice e se alcune linee hanno degli spazio bianchi di troppo. Altri si chiederanno @@ -189,3 +198,13 @@ l'uso eccessivo di *stack*, problemi di sicurezza, duplicazione del codice in altri contesti, documentazione, effetti negativi sulle prestazioni, cambi all'ABI dello spazio utente, eccetera. Qualunque tipo di revisione è ben accetta e di valore, se porta ad avere un codice migliore nel kernel. + +Non esistono requisiti particolarmente stringenti per l'uso di etichette come +``Reviewd-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un +qualche tipo di messaggio che dica "ho verificato A, B e C nel codice che è +appena stato inviato e mi sembra tutto in ordine". Inoltre, questo permette ai +manutentori di prendere conoscenza circa una revisione avvenuta per davvero. + +Per finire, la revisione delle patch può diventare un processo negativo, troppo +focalizzato sulla ricerca dei problemi. Provate a fare qualche complimento di +tanto in tanto, specialmente con i nuovi arrivati. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index f37c53f8b524..ade695a7de19 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -34,13 +34,15 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version +Rust (opzionale) 1.74.1 rustc --version +bindgen (opzionale) 0.65.1 bindgen --version GNU make 3.81 make --version bash 4.2 bash --version binutils 2.25 ld -v flex 2.5.35 flex --version bison 2.0 bison --version pahole 1.16 pahole --version -util-linux 2.10o fdformat --version +util-linux 2.10o mount --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V jfsutils 1.1.3 fsck.jfs -V @@ -59,8 +61,10 @@ mcelog 0.6 mcelog --version 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 +Sphinx\ [#f1]_ 2.4.4 sphinx-build --version cpio any cpio --version +GNU tar 1.28 tar --version +gtags (opzionale) 6.6.5 gtags --version ====================== ================= ======================================== .. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel @@ -151,6 +155,18 @@ Se la firma dei moduli è abilitata, allora vi servirà openssl per compilare il kernel 3.7 e successivi. Vi serviranno anche i pacchetti di sviluppo di openssl per compilare il kernel 4.3 o successivi. +Tar +--- + +GNU Tar è necessario per accedere ai file d'intestazione del kernel usando sysfs +(CONFIG_IKHEADERS) + +gtags / GNU GLOBAL (opzionale) +------------------------------ + +Il programma GNU GLOBAL versione 6.6.5, o successiva, è necessario quando si +vuole eseguire ``make gtags`` e generare i relativi indici. Internamente si fa +uso del parametro gtags ``-C (--directory)`` che compare in questa versione. Strumenti di sistema ******************** @@ -434,7 +450,7 @@ E2fsprogs JFSutils -------- -- <http://jfs.sourceforge.net/> +- <https://jfs.sourceforge.net/> Reiserfsprogs ------------- @@ -455,7 +471,7 @@ Pcmciautils Quota-tools ----------- -- <http://sourceforge.net/projects/linuxquota/> +- <https://sourceforge.net/projects/linuxquota/> Microcodice Intel P6 @@ -476,7 +492,7 @@ FUSE mcelog ------ -- <http://www.mcelog.org/> +- <https://www.mcelog.org/> cpio ---- @@ -497,7 +513,8 @@ PPP NFS-utils --------- -- <http://sourceforge.net/project/showfiles.php?group_id=14> +- <https://sourceforge.net/project/showfiles.php?group_id=14> +- <https://nfs.sourceforge.net/> Iptables -------- @@ -512,12 +529,7 @@ Ip-route2 OProfile -------- -- <http://oprofile.sf.net/download/> - -NFS-Utils ---------- - -- <http://nfs.sourceforge.net/> +- <https://oprofile.sf.net/download/> Documentazione del kernel ************************* diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index 284a75ac19f8..a4b9f44081da 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -214,7 +214,7 @@ Non usate inutilmente le graffe dove una singola espressione è sufficiente. e -.. code-block:: none +.. code-block:: c if (condition) do_this(); @@ -652,7 +652,7 @@ Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più sensati. Per fare quest'ultima cosa, potete appiccicare il codice che segue nel vostro file .emacs: -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -728,6 +728,10 @@ il testo e altre cose simili. Per maggiori dettagli, consultate il file :ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`. +Se utilizzate un programma compatibile con EditorConfig, allora alcune +configurazioni basilari come l'indentazione e la fine delle righe verranno +applicate automaticamente. Per maggiori informazioni consultate la pagina: +https://editorconfig.org/ 10) File di configurazione Kconfig ---------------------------------- @@ -898,7 +902,9 @@ 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 alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(), -eccetera. +eccetera. Quando tutto funziona correttamente, non dovrebbero esserci stampe, +per cui preferite dev_dbg/pr_debug a meno che non sia qualcosa di sbagliato +da segnalare. Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando l'avete può essere d'enorme aiuto per risolvere problemi da remoto. diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index ba0ed7dc154c..d4ab76e9be49 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -86,7 +86,7 @@ da kcalloc(). Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate le funzioni del tipo *saturate-on-overflow*:: - bar = vmalloc(array_size(count, size)); + bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL); Un altro tipico caso da evitare è quello di calcolare la dimensione di una struttura seguita da un vettore di altre strutture, come nel seguente caso:: diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 052f1b3610cb..090941a0a898 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -85,8 +85,8 @@ relativi file di documentatione che spiegano come usarele. Quando un cambiamento del kernel genera anche un cambiamento nell'interfaccia con lo spazio utente, è raccomandabile che inviate una notifica o una correzione alle pagine *man* spiegando tale modifica agli amministratori di -queste pagine all'indirizzo mtk.manpages@gmail.com, aggiungendo -in CC la lista linux-api@vger.kernel.org. +queste pagine all'indirizzo alx@kernel.org, aggiungendo in CC la +lista linux-api@vger.kernel.org. Di seguito una lista di file che sono presenti nei sorgente del kernel e che è richiesto che voi leggiate: @@ -144,7 +144,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che dello sviluppo di Linux ed è molto importante per le persone che arrivano da esperienze con altri Sistemi Operativi. - :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>` + :ref:`Documentation/translations/it_IT/process/security-bugs.rst <it_securitybugs>` Se ritenete di aver trovato un problema di sicurezza nel kernel Linux, seguite i passaggi scritti in questo documento per notificarlo agli sviluppatori del kernel, ed aiutare la risoluzione del problema. diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index cd7977905fb8..73c643dcc541 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -21,19 +21,75 @@ l'accettazione delle vostre modifiche con il minimo sforzo. Di seguito le guide che ogni sviluppatore dovrebbe leggere. +Introduzione al funzionamento dello sviluppo del kernel +------------------------------------------------------- + +Innanzitutto, leggete questi documenti che vi aiuteranno ad entrare nella +comunità del kernel. + .. toctree:: :maxdepth: 1 howto - code-of-conduct development-process submitting-patches + submit-checklist + +Strumenti e guide tecniche per gli sviluppatori del kernel +---------------------------------------------------------- + +Quella che segue è una raccolta di documenti che uno sviluppatore del kernel +Linux dovrebbe conoscere. + +.. toctree:: + :maxdepth: 1 + + changes programming-language coding-style maintainer-pgp-guide email-clients + applying-patches + adding-syscalls + volatile-considered-harmful + botching-up-ioctls + +Politiche e dichiarazioni degli sviluppatori +-------------------------------------------- + +Quelle che seguono rappresentano le regole che cerchiamo di seguire all'interno +della comunità del kernel (e oltre). + +.. toctree:: + :maxdepth: 1 + + code-of-conduct kernel-enforcement-statement kernel-driver-statement + stable-api-nonsense + stable-kernel-rules + management-style + +Gestire i bachi +--------------- + +I bachi sono parte della nostra vita; dunque è importante che vengano trattati +con riguardo. I documenti che seguono descrivono le nostre politiche riguardo al +trattamento di alcune classi particolari di bachi: le regressioni e i problemi +di sicurezza. + +Informazioni per i manutentori +------------------------------ + +Come trovare le persone che accetteranno le vostre modifiche. + +.. toctree:: + :maxdepth: 1 + + maintainers + +Altri documenti +--------------- Poi ci sono altre guide sulla comunità che sono di interesse per molti degli sviluppatori: @@ -41,13 +97,7 @@ degli sviluppatori: .. toctree:: :maxdepth: 1 - changes - 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. @@ -55,11 +105,7 @@ perché non si è trovato un posto migliore. .. toctree:: :maxdepth: 1 - applying-patches - adding-syscalls magic-number - volatile-considered-harmful - botching-up-ioctls clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/admin-guide/security-bugs.rst b/Documentation/translations/it_IT/process/security-bugs.rst index 20994f4bfa31..20994f4bfa31 100644 --- a/Documentation/translations/it_IT/admin-guide/security-bugs.rst +++ b/Documentation/translations/it_IT/process/security-bugs.rst diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 248bf1e4b171..a2577a806a18 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -44,7 +44,7 @@ Procedura per sottomettere patch per i sorgenti -stable .. 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>`. + :ref:`Documentation/translations/it_IT/process/security-bugs.rst <it_securitybugs>`. Per tutte le altre sottomissioni, scegliere una delle seguenti procedure ------------------------------------------------------------------------ diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index f91c8092844f..4c6a276bdc08 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -349,6 +349,33 @@ 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_interleaved_replies: + +Rispondere alle email in riga e riducendo la citazioni +------------------------------------------------------ + +Nelle discussioni riguardo allo sviluppo del kernel viene fortemente scoraggiato +l'uso di risposte in cima ai messaggi di posta elettronica. Rispondere in riga +rende le conversazioni molto più scorrevoli. Maggiori dettagli possono essere +trovati qui: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style + +Come spesso citato nelle liste di discussione:: + + R: http://en.wikipedia.org/wiki/Top_post + D: Dove posso trovare informazioni riguardo alle "risposte in cima"? + R: Perché incasina il normale ordine con cui si legge un testo. + D: Perché è così terribile rispondere in cima? + R: Risposte in cima. + Q: Qual è la cosa più fastidiosa nei messaggi di posta elettronica? + +Allo stesso modo, per favore eliminate tutte le citazioni non necessarie per la +vostra risposta. Questo permette di trovare più facilmente le risposte, e +permette di risparmiare tempo e spazio. Per maggiori dettagli: +http://daringfireball.net/2007/07/on_top :: + + R: No. + D: Dovrei includere un blocco di citazione dopo la mia risposta? + .. _it_resend_reminders: Non scoraggiatevi - o impazientitevi diff --git a/Documentation/translations/ja_JP/process/howto.rst b/Documentation/translations/ja_JP/process/howto.rst index 8d856ebe873c..872876c67896 100644 --- a/Documentation/translations/ja_JP/process/howto.rst +++ b/Documentation/translations/ja_JP/process/howto.rst @@ -110,7 +110,7 @@ Linux カーネルソースツリーは幅広い範囲のドキュメントを 新しいドキュメントファイルも追加することを勧めます。 カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの 変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 -をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を +をマニュアルページのメンテナ alx@kernel.org に送り、CC を linux-api@vger.kernel.org に送ることを勧めます。 以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で diff --git a/Documentation/translations/sp_SP/index.rst b/Documentation/translations/sp_SP/index.rst index c543b495c042..274ef4ad96b9 100644 --- a/Documentation/translations/sp_SP/index.rst +++ b/Documentation/translations/sp_SP/index.rst @@ -7,7 +7,7 @@ Traducción al español \kerneldocCJKoff -:maintainer: Carlos Bilbao <carlos.bilbao@amd.com> +:maintainer: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_disclaimer: diff --git a/Documentation/translations/sp_SP/memory-barriers.txt b/Documentation/translations/sp_SP/memory-barriers.txt index 27097a808c88..153e57130775 100644 --- a/Documentation/translations/sp_SP/memory-barriers.txt +++ b/Documentation/translations/sp_SP/memory-barriers.txt @@ -1,6 +1,6 @@ NOTE: This is a version of Documentation/memory-barriers.txt translated into -Spanish by Carlos Bilbao <carlos.bilbao@amd.com>. If you find any +Spanish by Carlos Bilbao <carlos.bilbao.osdev@gmail.com>. If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. Please also note that the purpose of this file is to be easier to read for non English @@ -18,7 +18,7 @@ Documento original: David Howells <dhowells@redhat.com> Will Deacon <will.deacon@arm.com> Peter Zijlstra <peterz@infradead.org> -Traducido por: Carlos Bilbao <carlos.bilbao@amd.com> +Traducido por: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> Nota: Si tiene alguna duda sobre la exactitud del contenido de esta traducción, la única referencia válida es la documentación oficial en inglés. diff --git a/Documentation/translations/sp_SP/process/1.Intro.rst b/Documentation/translations/sp_SP/process/1.Intro.rst new file mode 100644 index 000000000000..9b92b6c85221 --- /dev/null +++ b/Documentation/translations/sp_SP/process/1.Intro.rst @@ -0,0 +1,302 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/1.Intro.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +.. _sp_development_process_intro: + +Introducción +============ + +Resumen ejecutivo +----------------- + +El resto de esta sección cubre el alcance del proceso de desarrollo del +kernel y los tipos de frustraciones que los desarrolladores y sus +empleadores pueden encontrar allí. Hay muchas razones por las que el +código del kernel debe fusionarse con el kernel oficial (“mainline”), +incluyendo la disponibilidad automática para los usuarios, el apoyo de la +comunidad en muchas formas, y la capacidad de influir en la dirección del +desarrollo del kernel. El código contribuido al kernel de Linux debe +estar disponible bajo una licencia compatible con GPL. + +:ref:`sp_development_process` introduce el proceso de desarrollo, el ciclo +de lanzamiento del kernel y la mecánica de la "ventana de combinación" +(merge window). Se cubren las distintas fases en el desarrollo del parche, +la revisión y, el ciclo de fusión. Hay algunas discusiones sobre +herramientas y listas de correo. Se anima a los desarrolladores que deseen +comenzar con el desarrollo del kernel a encontrar y corregir errores como +ejercicio inicial. + +:ref:`sp_development_early_stage` cubre la planificación de proyectos en +etapas tempranas, con énfasis en involucrar a la comunidad de desarrollo +lo antes posible. + +:ref:`sp_development_coding` trata sobre el proceso de codificación. Se +discuten varios escollos encontrados por otros desarrolladores. Se cubren +algunos requisitos para los parches, y hay una introducción a algunas de +las herramientas que pueden ayudar a garantizar que los parches del kernel +sean correctos. + +:ref:`sp_development_posting` trata sobre el proceso de enviar parches para +su revisión. Para ser tomados en serio por la comunidad de desarrollo, +los parches deben estar correctamente formateados y descritos, y deben +enviarse al lugar correcto. Seguir los consejos de esta sección debería +ayudar a garantizar la mejor recepción posible para su trabajo. + +:ref:`sp_development_followthrough` cubre lo que sucede después de publicar +parches; el trabajo está lejos de terminar en ese momento. Trabajar con +revisores es una parte crucial del proceso de desarrollo; esta sección +ofrece varios consejos sobre cómo evitar problemas en esta importante +etapa. Se advierte a los desarrolladores que no asuman que el trabajo está +terminado cuando un parche se fusiona en mainline. + +:ref:`sp_development_advancedtopics` introduce un par de temas “avanzados”: +la administración de parches con git y la revisión de parches publicados +por otros. + +:ref:`sp_development_conclusion` concluye el documento con punteros a las +fuentes para obtener más información sobre el desarrollo del kernel. + +De qué trata este documento +--------------------------- + +El kernel de Linux, con más de 8 millones de líneas de código y más de +1000 colaboradores en cada versión, en uno de los proyectos de software +libre más grandes y activos que existen. Desde sus humildes comienzos en +1991, este kernel ha evolucionado hasta convertirse en el mejor componente +del sistema operativo que se ejecuta en reproductores de música digital +de bolsillo, PC de escritorio, las supercomputadoras más grandes que +existen y todo tipo de sistemas intermedios. Es una solución robusta, +eficiente, y escalable para casi cualquier situación. + +Con el crecimiento de Linux, ha llegado un aumento en el número de +desarrolladores (y empresas) que desean participar en su desarrollo. Los +vendedores de hardware quieren asegurarse de que Linux sea compatible con +sus productos, lo que hace que esos productos sean atractivos para los +usuarios de Linux. Los vendedores de sistemas embebidos, que utilizan +Linux como componente de un producto integrado, quieren que Linux sea lo +más capaz y adecuado posible para tarea en cuestión. Los distribuidores +y otros vendedores de software que basan sus productos en Linux tienen un +claro interés en las capacidades, el rendimiento, y la fiabilidad del +kernel de Linux. Y los usuarios finales, también, a menudo desearán +cambiar Linux para que se adapte mejor a sus necesidades. + +Una de las características más convincentes de Linux es que es accesible +a estos desarrolladores; cualquier persona con las habilidades necesarias +puede mejorar Linux e influir en la dirección de su desarrollo. Los +productos propietarios no pueden ofrecer este tipo de apertura, que es una +característica del proceso de software libre. Pero, en todo caso, el +kernel es aún más libre que la mayoría de los otros proyectos de software +libre. Un ciclo típico de desarrollo de kernel de tres meses puede +involucrar a más de 1000 desarrolladores que trabajan para más de 100 +empresas diferentes (o sin pertenecer a ninguna empresa). + +Trabajar con la comunidad de desarrollo del kernel no es especialmente +difícil. Pero, a pesar de eso, muchos colaboradores potenciales han +experimentado dificultades al tratar de hacer el trabajo del kernel. La +comunidad del kernel ha desarrollado sus propias formas distintivas de +operar, lo que le permite funcionar de manera fluida (y producir un +producto de alta calidad) en un entorno donde miles de líneas de código +se cambian todos los días. Por lo tanto, no es sorprendente que el +proceso de desarrollo del kernel de Linux difiera mucho de los métodos de +desarrollo propietarios. + +El proceso de desarrollo del kernel puede parecer extraño e intimidante +para los nuevos desarrolladores, pero hay buenas razones y una sólida +experiencia detrás de él. Un desarrollador que no entienda las formas de +la comunidad del kernel (o, peor aún, que intente burlarse o eludirlas) +tendrá una experiencia frustrante por delante. La comunidad de +desarrollo, si bien es servicial para aquellos que están tratando de +aprender, tiene poco tiempo para aquellos que no escuchan o que no se +preocupan por el proceso de desarrollo. + +Se espera que quienes lean este documento puedan evitar esa experiencia +frustrante. Hay mucho material aquí, pero el esfuerzo que implica leerlo +será recompensado en poco tiempo. La comunidad de desarrollo siempre +necesita desarrolladores que ayudan a mejorar el kernel; el siguiente +texto debería ayudarle – o a quienes trabajan para usted, a unirse a +nuestra comunidad. + +Créditos +-------- + +Este documento fue escrito por Jonathan Corbet, corbet@lwn.net. Ha sido +mejorado por los comentarios de Johannes Berg, James Berry, Alex Chiang, +Roland Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur +Marsh, Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata y +Jochen Voß. +Este trabajo fue respaldado por la Fundación Linux; gracias especialmente +a Amanda McPherson, quien reconoció el valor de este esfuerzo e hizo que +todo sucediera. + +Importancia de integrar el código en el mainline +------------------------------------------------ + +Algunas empresas y desarrolladores ocasionalmente se preguntan por qué +deberían molestarse en aprender cómo trabajar con la comunidad del +kernel y obtener su código en el kernel mainline (el “mainline” es el +kernel mantenido por Linus Torvalds y utilizado como base por los +distribuidores de Linux. A corto plazo, contribuir con código puede +parecer un gasto evitable; parece más fácil mantener el código separado +y dar soporte a los usuarios directamente. La verdad del asunto es que +mantener el código separado (“fuera del árbol”) es pan para hoy y hambre +para mañana. + +Para ilustrar los costos del código fuera-del-árbol, aquí hay algunos +aspectos relevantes del proceso de desarrollo del kernel. La mayoría de +estos se discutirán con mayor detalle más adelante en este documento. +Considerar: + +- El código que se ha fusionado con el kernel mainline está disponible + para todos los usuarios de Linux. Estará presente automáticamente en + todas las distribuciones que lo habiliten. No hay necesidad de discos + de controladores, descargas, o las molestias de admitir múltiples + versiones de múltiples distribuciones; todo simplemente funciona, para + el desarrollador y para el usuario. La incorporación al mainline + resuelve un gran número de problemas de distribución y soporte. + +- Mientras los desarrolladores del kernel se esfuerzan por mantener una + interfaz estable para el espacio de usuario, la API interna de kernel + está en constante cambio. La falta de una interfaz interna estable es + una decisión deliberada de diseño; permite realizar mejoras + fundamentales en cualquier momento y da como resultado un código de + mayor calidad. Pero uno resultado de esa política es que cualquier + código fuera-del-árbol requiere un mantenimiento constante si va a + funcionar con los nuevos kernels. Mantener el código fuera-del-árbol + requiere una cantidad significativa de trabajo sólo para que ese código + siga funcionando. + + En su lugar, el código en el mainline no requiere este trabajo como + resultado de una regla simple que requiere que cualquier desarrollador + que realice un cambio en la API también corrija cualquier código que + se rompa como resultado de ese cambio. Así que, el código fusionado en + el mainline tiene costos de mantenimiento significativamente más bajos. + +- Más allá de eso, el código que está en el kernel a menudo será + mejorado por otros desarrolladores. Resultados sorprendentes pueden + provenir de capacitar a su comunidad de usuarios y clientes para mejorar + su producto. + +- El código del kernel se somete a revisión, tanto antes como después + de fusionarse con el mainline. No importa cuán fuertes sean las + habilidades del desarrollador original, este proceso de revisión + invariablemente encuentra formas en las que se puede mejorar el código. + A menudo la revisión encuentra errores graves y problemas de seguridad. + Esto es especialmente cierto para el código que se ha desarrollado en + un entorno cerrado; dicho código se beneficia fuertemente de la + revisión por desarrolladores externos. El código fuera-del-árbol es + de menor calidad. + +- La participación en el proceso de desarrollo es su manera de influir en + la dirección del desarrollo del kernel. Los usuarios que se quejan + desde el sofa son escuchados, pero los desarrolladores activos tienen + una voz más fuerte – y la capacidad de implementar cambios que hacen + que el kernel funcione mejor para sus necesidades. + +- Cuando el código se mantiene por separado, siempre existe la posibilidad + de que un tercero contribuya a una implementación diferente de una + característica similar. Si eso sucede, conseguir que su código + fusionado será mucho más difícil – hasta el punto de la imposibilidad. + Entonces se enfrentará a las desagradables alternativas de (1) mantener + una característica no estándar fuera del árbol indefinidamente, o + (2) abandonar su código y migrar sus usuarios a la versión en el árbol. + +- La contribución del código es la acción fundamental que hace que todo + el proceso funcione. Al contribuir con su código, puede agregar nuevas + funcionalidades al kernel y proporcionar capacidades y ejemplos que son + útiles para otros desarrolladores del kernel. Si ha desarrollado código + para Linux (o está pensando en hacerlo), claramente tiene un interés + en el éxito continuo de esta plataforma; contribuir con código es una + de las mejores maneras de ayudar a garantizar ese éxito. + +Todo el razonamiento anterior se aplica a cualquier código de kernel +fuera-del-árbol, incluido el código que se distribuye en forma propietaria +y únicamente en binario. Sin embargo, hay factores adicionales que deben +tenerse en cuenta antes de considerar cualquier tipo de distribución de +código de kernel únicamente en binario. Estos incluyen: + +- Las cuestiones legales en torno a la distribución de módulos + propietarios del kernel son, en el mejor de los casos, confusas; + bastantes titulares de derechos de autor del kernel creen que la + mayoría de los módulos binarios son productos derivados del kernel y + que, como resultado, su distribución es una violación de la licencia + Pública General de GNU (sobre la que se dirá más adelante). El autor + de este texto no es abogado, y nada en este documento puede considerarse + asesoramiento legal. Solo los tribunales pueden determinar el verdadero + estatus legal de los módulos de código cerrado. Pero la incertidumbre + que acecha a esos módulos está ahí a pesar de todo. + +- Los módulos binarios aumentan enormemente la dificultad de depurar + problemas del kernel, hasta el punto de que la mayoría de los + desarrolladores del kernel ni siquiera lo intentarán. Por lo tanto, + la distribución de módulos únicamente en binario hará que sea más + difícil para sus usuarios obtener soporte de la comunidad. + +- El soporte también es más difícil para los distribuidores de módulos + únicamente en binario, que deben proporcionar una versión del módulo + para cada distribución y cada versión del kernel que deseen apoyar. + Podría requerir docenas de compilaciones de un solo módulo para + proporcionar una cobertura razonablemente completa, y sus usuarios + tendrán que actualizar su módulo por separado cada vez que + actualicen su kernel. + +- Todo lo que se dijo anteriormente sobre la revisión de código se aplica + doblemente al código cerrado. Dado que este código no está disponible + en absoluto, no puede haber sido revisado por la comunidad y, sin duda, + tendrá serios problemas. + +Los fabricantes de sistemas embebidos, en particular, pueden verse +tentados a ignorar gran parte de lo que se ha dicho en esta sección +creyendo que están enviando un producto autónomo que utiliza una +versión de kernel congelada y no requiere más desarrollo después de su +lanzamiento. Este argumento desaprovecha el valor de la revisión +generalizad del código y el valor de permitir que sus usuarios agreguen +capacidades a su producto. Pero estos productos también tienen una vida +comercial limitada, después de la cual se debe lanzar una nueva versión. +En ese punto, los vendedores cuyo código esté en el mainline y bien +mantenido estarán en una posición mucho mejor para preparar el nuevo +producto rápidamente para el mercado. + +Licencias +--------- + +El código se contribuye al kernel de Linux bajo varias licencias, pero +todo el código debe ser compatible con la versión 2 de la Licencia +Pública General de GNU (GPLv2), que cubre la distribución del kernel. En +la práctica, esto significa que todas las contribuciones de código están +cubiertas ya sea por la GPLv2 (con, opcionalmente, un lenguaje que permite +la distribución en versiones posteriores de la GPL) o por la licencia BSD +de tres cláusulas. Cualquier contribución que no esté cubierta por una +licencia compatible no será aceptada en el kernel. + +No se requieren (ni se solicitan) cesiones de derechos de autor para el +código aportado al kernel. Todo el código fusionado en el kernel +mainline conserva su propiedad original; como resultado, el kernel ahora +tiene miles de propietarios. + +Una implicación de esta estructura de propiedad es que cualquier intento +de cambiar la licencia del kernel está condenado a un fracaso casi seguro. +Hay pocos escenarios prácticos en los que se pueda obtener el acuerdo de +todos los titulares de derechos de autor (o eliminar su código del +kernel). Así que, en particular, no hay perspectivas de una migración a +la versión 3 de la GPL en un futuro previsible. + +Es imperativo que todo el código aportado al kernel sea legítimamente +software libre. Por esa razón, no se aceptará código de colaboradores +anónimos (o seudónimos). Todos los colaboradores están obligados a +“firmar” su código, indicando que el código puede ser distribuido con +el kernel bajo la GPL. El código que no ha sido licenciado como software +libre por su propietario, o que corre el riesgo de crear problemas +relacionadas con los derechos de autor para el kernel (como el código que +se deriva de esfuerzos de ingeniería inversa que carecen de las garantías +adecuadas) no puede ser contribuido. + +Las preguntas sobre cuestiones relacionadas con los derechos de autor son +comunes en las listas de correo de desarrollo de Linux. Normalmente, estas +preguntas no recibirán escasez de respuestas, pero se debe tener en cuenta +que las personas que responden a esas preguntas no son abogados y no +pueden proporcionar consejo legal. Si tiene preguntas legales relacionadas +con el código fuente de Linux, no hay sustituto para hablar con un abogado +que entienda este campo. Confiar en las respuestas obtenidas en listas +técnicas de correo es un asunto arriesgado. diff --git a/Documentation/translations/sp_SP/process/2.Process.rst b/Documentation/translations/sp_SP/process/2.Process.rst new file mode 100644 index 000000000000..5993eed71563 --- /dev/null +++ b/Documentation/translations/sp_SP/process/2.Process.rst @@ -0,0 +1,542 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/2.Process.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +.. _sp_development_process: + +Cómo funciona el proceso de desarrollo +====================================== + +El desarrollo del kernel de Linux a principios de la década de 1990 fue +un asunto relajado, con un número relativamente pequeño de usuarios y +desarrolladores involucrados. Con una base de usuarios en los millones y +alrededor de 2,000 desarrolladores involucrados durante un año, el kernel +ha tenido que adaptar varios procesos para mantener el desarrollo sin +problemas. Se requiere una comprensión solida de cómo funciona el proceso +para ser una parte efectiva del mismo. + +El panorama general +------------------- + +Los desarrolladores del kernel utilizan un proceso de lanzamiento basado +en el tiempo de manera flexible, con uno nuevo lanzamiento principal del +kernel ocurriendo cada dos o tres meses. El historial reciente de +lanzamientos se ve así: + + ====== ================== + 5.0 Marzo 3, 2019 + 5.1 Mayo 5, 2019 + 5.2 Julio 7, 2019 + 5.3 Septiembre 15, 2019 + 5.4 Noviembre 24, 2019 + 5.5 Enero 6, 2020 + ====== ================== + +Cada lanzamiento 5.x es un lanzamiento principal del kernel con nuevas +características, cambios internos en la API y más. Un lanzamiento típico +puede contener alrededor de 13,000 conjuntos de cambios incluyendo en +varias centenas de miles de líneas de código. 5.x es la vanguardia del +desarrollo del kernel de Linux; el kernel utiliza un modelo de desarrollo +continuo que está integrando continuamente cambios importantes. + +Se sigue una disciplina relativamente sencilla con respecto a la fusión +de parches para cada lanzamiento. Al comienzo de cada ciclo de desarrollo, +se dice que la "merge window" (ventana de fusión) está abierta. En ese +momento, el código que se considera lo suficientemente estable (y que es +aceptado por la comunidad de desarrollo) se fusiona en el kernel mainline. +La mayor parte de los cambios para un nuevo ciclo de desarrollo (y todos +los cambios principales) se fusionarán durante este tiempo, a un ritmo +cercano a los 1,000 cambios (“parches” o “conjuntos de cambios”) por +día. + +(Aparte, vale la pena señalar que los cambios integrados durante la +ventana de fusión no surgen de la nada; han sido recolectados, probados +y montados con anticipación. Como funciona ese proceso se describirá en +detalle más adelante). + +La ventana de fusión dura aproximadamente dos semanas. Al final de este +tiempo, Linux Torvalds declarará que la ventana está cerrada y publicará +el primero de los kernels “rc”. Para el kernel destinado a ser 5.6, por +ejemplo, el lanzamiento al final de la ventana de fusión se llamará +5.6-rc1. El lanzamiento -rc1 señala que el tiempo para fusionar nuevas +características ha pasado y que el tiempo para estabilizar el siguiente +kernel ha comenzado. + +Durante las próximas seis a diez semanas, solo los parches que solucionen +problemas deben enviarse al mainline. En ocasiones, se permitirá un cambio +más significativo, pero tales ocasiones son raras; los desarrolladores que +intentan fusionar nuevas características fuera de la ventana de fusión +suelen recibir una recepción poco amistosa. Como regla general, si se +pierde la ventana de fusión de una característica determinada, lo mejor +que puede hacer es esperar al siguiente ciclo de desarrollo. (Se hace una +excepción ocasional para los drivers de hardware que no se admitía +anteriormente; si no afectan a ningún código en árbol, no pueden causar +regresiones y debería ser seguro agregarlos en cualquier momento). + +A medida que las correcciones se abren paso en el mainline, la tasa de +parches se ralentizará con el tiempo. Linus lanza nuevos kernels -rc +aproximadamente una vez a la semana; una serie normal llegará a algún +punto entre -rc6 y -rc9 antes de que se considere que el kernel es +suficientemente estable y realice el lanzamiento final. En ese momento, +todo el proceso vuelve a empezar. + +Como ejemplo, así fue el ciclo de desarrollo de 5.4 (todas las fechas son +de 2019): + + ============== ======================================= + Septiembre 15 5.3 lanzamiento estable + Septiembre 30 5.4-rc1, la ventana de fusion se cierra + Octubre 6 5.4-rc2 + Octubre 13 5.4-rc3 + Octubre 20 5.4-rc4 + Octubre 27 5.4-rc5 + Noviembre 3 5.4-rc6 + Noviembre 10 5.4-rc7 + Noviembre 17 5.4-rc8 + Noviembre 24 5.4 lanzamiento estable + ============== ======================================= + +¿Cómo deciden los desarrolladores cuándo cerrar el ciclo de desarrollo +y crear el lanzamiento estable? La métrica más significativa utilizada +es la lista de regresiones de lanzamientos anteriores. Ningunos errores +son bienvenidos, pero aquellos que rompen sistemas que funcionaron en el +pasado se consideran especialmente graves. Por esta razón, los parches +que causan regresiones se ven con malos ojos y es bastante probable que +se reviertan durante el periodo de estabilización. + +El objetivo de los desarrolladores es corregir todas las regresiones +conocidas antes de que se realice el lanzamiento estable. En el mundo +real, este tipo de perfección es difícil de lograr; hay demasiados +variables en un proyecto de este tamaño. Llega un punto en el que +retrasar el lanzamiento final solo empeora el problema; la pila de cambios +que esperan la siguiente ventana de fusión crecerá, creando aún más +regresiones la próxima vez. Por lo tanto, la mayoría de los kernels 5.x +se lanzan con un punado de regresiones conocidas, aunque, con suerte, +ninguna de ellas es seria. + +Una vez que se realiza un lanzamiento estable, su mantenimiento continuo +se transfiere al “equipo estable”, actualmente encabezado por Greg +Kroah-Hartman. El equipo estable lanzará actualizaciones ocasionales al +lanzamiento estable utilizando el esquema de numeración 5.x.y. Para ser +considerado para un lanzamiento de actualización, un parche debe +(1) corregir un error significativo y (2) ya estar fusionado en el +mainline para el siguiente kernel de desarrollo. Por lo general, los +kernels recibirán actualizaciones estables durante un poco más de un +ciclo de desarrollo después de su lanzamiento inicial. Así, por ejemplo, +la historia del kernel 5.2 se veía así (todas las fechas en 2019): + + ============== =============================== + Julio 7 5.2 lanzamiento estable + Julio 14 5.2.1 + Julio 21 5.2.2 + Julio 26 5.2.3 + Julio 28 5.2.4 + Julio 31 5.2.5 + ... ... + Octubre 11 5.2.21 + ============== =============================== + +5.2.21 fue la última actualización estable del lanzamiento 5.2. + +Algunos kernels se designan como kernels “a largo plazo”; recibirán +soporte durante un periodo más largo. Consulte el siguiente enlace para +obtener la lista de versiones activas del kernel a largo plazos y sus +maintainers: + + https://www.kernel.org/category/releases.html + +La selección de un kernel para soporte a largo plazo es puramente una +cuestión de que un maintainer tenga la necesidad y el tiempo para +mantener ese lanzamiento. No hay planes conocidos para ofrecer soporte a +largo plazo para ningún lanzamiento especifico próximo. + +Ciclo de vida de un parche +-------------------------- + +Los parches no van directamente desde el teclado del desarrollador al +kernel mainline. Hay, en cambio, un proceso algo complicado (aunque algo +informal) diseñado para garantizar que cada parche sea revisado en cuanto +a calidad y que cada parche implemente un cambio que es deseable tener en +el mainline. Este proceso puede ocurrir rápidamente para correcciones +menores, o, en el caso de cambios grandes y controvertidos, continuar +durante años. Gran parte de la frustración de los desarrolladores proviene +de la falta de compresión de este proceso o de sus intentos de eludirlo. + +Con la esperanza de reducir esa frustración, este documento describirá +cómo un parche entra en el kernel. Lo que sigue a continuación es una +introducción que describe el proceso de una manera tanto idealizada. Un +tratamiento mucho más detallado vendrá en secciones posteriores. + +Las etapas por las que pasa un parche son, generalmente: + + - Diseño. Aquí es donde se establecen los requisitos reales para el + parche – y la forma en que se cumplirán esos requisitos. El trabajo + de diseño a menudo se realiza sin involucrar a la comunidad, pero es + mejor hacer este trabajo de manera abierta si es posible; puede ahorrar + mucho tiempo rediseñando las cosas más tarde. + + - Revisión inicial. Los parches se publican en la lista de correo + relevante y los desarrolladores en esa lista responden con cualquier + comentario que puedan tener. Este proceso debería revelar cualquier + problema importante con un parche si todo va bien. + + - Revisión más amplia. Cuando el parche se acerca a estar listo para su + inclusión en el mainline, debe ser aceptado por un maintainer del + subsistema relevante – aunque esta aceptación no es una garantía de + que el parche llegara hasta el mainline. El parche aparecerá en el + árbol de subsistemas del maintainer y en los árboles -next (descritos + a continuación). Cuando el proceso funciona, este paso conduce a una + revisión exhaustiva del parche y al descubrimiento de cualquier + problema resultante de la integración de este parche con el trabajo + realizado por otros. + + - Tenga en cuenta que la mayoría de los maintainers también tienen + trabajos diurnos, por lo que fusionar su parche no puede ser su máxima + prioridad. Si su parche está recibiendo comentarios sobre los cambios + que se necesitan, debería realizar esos cambios o justificar por qué + no deberían realizarse. Si su parche no tiene quejas de revisión, pero + no está siendo fusionado por el maintainer apropiado del subsistema o + del driver, debe ser persistente en la actualización del parche + al kernel actual para que se aplique limpiamente y seguir enviándolo + para su revisión y fusión. + + - Fusión en el mainline. Eventualmente, un parche exitoso se fusionará + en el repositorio mainline administrado por Linux Torvalds. Mas + comentarios y/o problemas pueden surgir en este momento; es importante + que el desarrollador responda a estos y solucione cualquier problema + que surja. + + - Lanzamiento estable. El número de usuarios potencialmente afectados por + el parche es ahora grande, por lo que, una vez más, pueden surgir + nuevos problemas. + + - Mantenimiento a largo plazo. Si bien un desarrollador puede olvidarse + del código después de fusionarlo, ese comportamiento tiende a dejar + una impresión negativa en la comunidad de desarrollo. Fusionar el + código elimina parte de la carga de mantenimiento; otros solucionarán + los problemas causados por los cambios en la API. Sin embargo, el + desarrollador original debe seguir asumiendo la responsabilidad del + código si quiere seguir siendo útil a largo plazo. + +Uno de los peores errores cometidos por los desarrolladores del kernel +(o sus empleadores) es tratar de reducir el proceso a un solo paso de +“fusión en el mainline”. Este enfoque conduce invariablemente a la +frustración de todos los involucrados. + +Cómo se integran los parches en el kernel +----------------------------------------- + +Hay exactamente una persona que puede fusionar parches en el repositorio +mainline del kernel: Linus Torvalds. Pero, por ejemplo, de los más de +9,500 parches que se incluyeron en el kernel 2.6.38, solo 112 (alrededor +del 1.3%) fueron elegidos directamente por Linus mismo. El proyecto del +kernel ha crecido mucho desde hace tiempo a un tamaño en el que ningún +desarrollador individual podría inspeccionar y seleccionar todos los +parches sin ayuda. La forma que los desarrolladores del kernel han +abordado este crecimiento es a través del uso de un sistema jerárquico +alrededor de una cadena de confianza. + +La base de código del kernel se descompone lógicamente en un conjunto de +subsistemas: redes, soporte de arquitectura especifica, gestión de +memoria, dispositivos de video, etc. La mayoría de los subsistemas tienen +un maintainer designado, un desarrollador que tiene la responsabilidad +general del código dentro de ese subsistema. Estos maintainers de +subsistemas son los guardianes (en cierto modo) de la parte del kernel que +gestionan; son los que (usualmente) aceptarán un parche para incluirlo en +el kernel mainline. + +Cada uno de los maintainers del subsistema administra su propia versión +del árbol de fuentes del kernel, generalmente (pero, ciertamente no +siempre) usando la herramienta de administración de código fuente de git. +Herramientas como git (y herramientas relacionadas como quilt o mercurial) +permiten a los maintainers realizar un seguimiento de una lista de +parches, incluida la información de autoría y otros metadatos. En +cualquier momento, el maintainer puede identificar qué parches de su +repositorio no se encuentran en el mainline. + +Cuando se abre la ventana de fusión, los maintainers de nivel superior +le pedirán a Linus que “extraiga” los parches que han seleccionado para +fusionar de sus repositorios. Si Linus está de acuerdo, el flujo de +parches fluirá hacia su repositorio, convirtiéndose en parte del kernel +mainline. La cantidad de atención que Linus presta a los parches +específicos recibidos en una operación de extracción varia. Está claro +que, a veces, examina bastante de cerca. Pero, como regla general, Linus +confía en que los maintainers del subsistema no envíen parches +defectuosos al upstream. + +Los maintainers de subsistemas, a su vez, pueden extraer parches de otros +maintainers. Por ejemplo, el árbol de red se construye a partir de +parches que se acumulan primero en arboles dedicados a drivers de +dispositivos de red, redes inalámbricas, etc. Esta cadena de repositorios +puede ser arbitrariamente larga, aunque rara vez supera los dos o tres +enlaces. Dado que cada maintainer de la cadena confía en los que +administran árboles de nivel inferior, este proceso se conoce como la +“cadena de confianza”. + +Claramente, en un sistema como este, lograr que los parches se integren +en el kernel depende de encontrar el maintainer adecuado. Enviar parches +directamente a Linus no es normalmente la forma correcta de hacerlo. + +Árboles siguientes (next) +------------------------- + +La cadena de árboles de subsistemas guía el flujo de parches en el +kernel, pero también plantea una pregunta interesante: ¿Qué pasa si +alguien quiere ver todos los parches que se están preparando para la +próxima ventana de fusión? Los desarrolladores estarán interesados en +saber que otros cambios están pendientes para ver si hay algún conflicto +del que preocuparse; un parche que cambia un prototipo de función del +núcleo del kernel, por ejemplo, entrará en conflicto con cualquier otro +parche que utilice la forma anterior de esa función. Los revisores y +probadores quieren tener acceso a los cambios en su forma integrada antes +de que todos esos cambios se integren en el kernel mainline. Uno podría +extraer cambios de todos los árboles de subsistemas interesantes, pero +eso sería un trabajo tedioso y propenso a errores. + +La respuesta viene en forma de árboles -next, donde los árboles de +subsistemas se recopilan para pruebas y revisiones. El más antiguo de +estos árboles, mantenido por Andrew Morton, se llama “-mm” (por gestión +de la memoria, que es como comenzó). El árbol “-mm” integra parches +de una larga lista de árboles de subsistemas; también tiene algunos +parches destinados a ayudar con la depuración. + +Más allá de eso, -mm contiene una colección significativa de parches +que han sido seleccionados directamente por Andrew. Estos parches pueden +haber sido publicados en una lista de correo o aplicarse a una parte del +kernel para la que no hay un árbol de subsistemas designado. Como +resultado, -mm funciona como una especie de árbol de subsistemas de +último recurso; si no hay otro camino obvio para un parche en el mainline, +es probable que termine en -mm. Los parches misceláneos que se acumulan +en -mm eventualmente se enviarán a un árbol de subsistema apropiado o se +enviarán directamente a Linus. En un ciclo de desarrollo típico, +aproximadamente el 5-10% de los parches que van al mainline llegan allí +a través de -mm. + +El parche -mm actual está disponible en el directorio “mmotm” (-mm +del momento) en: + + https://www.ozlabs.org/~akpm/mmotm/ + +Sin embargo, es probable que el uso del árbol MMOTM sea una experiencia +frustrante; existe una posibilidad definitiva de que ni siquiera se +compile. + +El árbol principal para la fusión de parches del siguiente ciclo es +linux-next, mantenido por Stephen Rothwell. El árbol linux-next es, por +diseño, una instantánea de cómo se espera que se vea el mainline después +de que se cierre la siguiente ventana de fusión. Los árboles linux-next +se anuncian en las listas de correo linux-kernel y linux-next cuando se +ensamblan; Se pueden descargar desde: + + https://www.kernel.org/pub/linux/kernel/next/ + +Linux-next se ha convertido en una parte integral del proceso de +desarrollo del kernel; todos los parches fusionados durante una ventana +de fusión determinada deberían haber encontrado su camino en linux-next +en algún momento antes de que se abra la ventana de fusión. + +Árboles de staging +------------------ + +El árbol de fuentes del kernel contiene el directorio drivers/staging/, +donde residen muchos subdirectorios para drivers o sistemas de archivos +que están en proceso de ser agregados al árbol del kernel. Permanecen +en drivers/staging mientras aún necesitan más trabajo; una vez +completados, se pueden mover al kernel propiamente dicho. Esta es una +forma de realizar un seguimiento de los drivers drivers que no están a la +altura de la codificación o los estándares de calidad del kernel de +Linux, pero que las personas pueden querer usarlos y realizar un +seguimiento del desarrollo. + +Greg Kroah-Hartman mantiene actualmente el árbol de staging. Los drivers +que aun necesitan trabajo se le envían, y cada driver tiene su propio +subdirectorio en drivers/staging/. Junto con los archivos de origen del +driver, también debe haber un archivo TODO en el directorio. El archivo +TODO enumera el trabajo pendiente que el driver necesita para ser aceptado +en el kernel propiamente dicho, así como una lista de personas a las que +Cc’d para cualquier parche para el driver. Las reglas actuales exigen +que los drivers que contribuyen a staging deben, como mínimo, compilarse +correctamente. + +El staging puede ser una forma relativamente fácil de conseguir nuevos +drivers en el mainline donde, con suerte, llamarán la atención de otros +desarrolladores y mejorarán rápidamente. Sin embargo, la entrada en el +staging no es el final de la historia; el código que no está viendo +progreso regular eventualmente será eliminado. Los distribuidores también +tienden a ser relativamente reacios a habilitar los drivers de staging. +Por lo tanto, el staging es, en el mejor de los casos, una parada en el +camino para hacia convertirse en un apropiado driver del mainline. + +Herramientas +------------ + +Como se puede ver en el texto anterior, el proceso de desarrollo del +kernel depende en gran medida de la capacidad de dirigir colecciones de +parches en varias direcciones. Todo ello no funcionaría tan bien como lo +hace sin herramientas apropiadamente potentes. Los tutoriales sobre cómo +usar estas herramientas están mucho más allá del alcance de este +documento, pero hay espacio para algunos consejos. + +Con mucho, el sistema de gestión de código fuente dominante utilizado +por la comunidad del kernel es git. Git es uno de los varios sistemas de +control de versiones distribuidos que se están desarrollando en la +comunidad de software libre. Está bien ajustado para el desarrollo de +kernel, ya que funciona bastante bien cuando se trata de grandes +repositorios y grandes cantidades de parches. También tiene la reputación +de ser difícil de aprender y usar, aunque ha mejorado con el tiempo. +Algún tipo de familiaridad con git es casi un requisito para los +desarrolladores del kernel; incluso si no lo usan para su propio +trabajo, necesitarán git para mantenerse al día con lo que otros +desarrolladores (y el mainline) están haciendo. + +Git ahora está empaquetado por casi todas las distribuciones de Linux. +Hay una página de inicio en: + + https://git-scm.com/ + +Esa página tiene punteros a documentación y tutoriales. + +Entre los desarrolladores de kernel que no usan git, la opción más +popular es casi con certeza Mercurial: + + https://www.selenic.com/mercurial/ + +Mercurial comparte muchas características con git, pero proporciona una +interfaz que muchos encuentran más fácil de usar. + +Otra herramienta que vale la pena conocer es Quilt: + + https://savannah.nongnu.org/projects/quilt/ + +Quilt es un sistema de gestión de parches, en lugar de un sistema de +gestión de código fuente. No rastrea el historial a lo largo del tiempo; +en cambio, está orientado al seguimiento de un conjunto especifico de +cambios en relación con una base de código en evolución. Algunos de los +principales maintainers de subsistemas utilizan Quilt para gestionar los +parches destinados a ir upstream. Para la gestión de ciertos tipos de +árboles (por ejemplo, -mm) Quilt es la mejor herramienta para el trabajo. + +Listas de correo +---------------- + +Una gran parte del trabajo de desarrollo del kernel de Linux se realiza a +través de listas de correo. Es difícil ser un miembro plenamente funcional +de la comunidad sin unirse al menos a una lista en algún parte. Pero las +listas de correo de Linux también representan un peligro potencial para +los desarrolladores, que corren el riesgo de quedar enterrados bajo una +carga de correo electrónico, incumplir las convenciones utilizadas en las +listas de Linux, o ambas cosas. + +La mayoría de las listas de correo del kernel se ejecutan en +vger.kernel.org; la lista principal se puede encontrar en: + + http://vger.kernel.org/vger-lists.html + +Sim embargo, hay listas alojadas en otros lugares; varios de ellos se +encuentran en redhat.com/mailman/listinfo. + +La lista de correo principal para el desarrollo del kernel es, por +supuesto, linux-kernel. Esta lista es un lugar intimidante; el volumen +puede alcanzar 500 mensajes por día, la cantidad de ruido es alta, la +conversación puede ser muy técnica y los participantes no siempre se +preocupan por mostrar un alto grado de cortesía. Pero no hay otro lugar +donde la comunidad de desarrollo del kernel se reúna como un todo; los +desarrolladores que eviten esta lista se perderán información importante. + +Hay algunos consejos que pueden ayudar a sobrevivir en el kernel de Linux: + +- Haga que la lista se entregue en una carpeta separada, en lugar de su + buzón principal. Uno debe ser capaz de ignorar el flujo durante + periodos prolongados. + +- No trate de seguir cada conversación, nadie lo hace. Es importante + filtrar tanto por el tema de interés (aunque tenga en cuenta que las + conversaciones prolongadas pueden alejarse del asunto original sin + cambiar la línea de asunto del correo electrónico) por las personas + que participan. + +- No alimente a los trolls. Si alguien está tratando de provocar una + respuesta de enojo, ignórelos. + +- Al responder al correo electrónico del kernel de Linux (o al de otras + listas) conserve el encabezado Cc: para todos los involucrados. En + ausencia de una razón solida (como una solicitud explícita), nunca debe + eliminar destinarios. Asegúrese siempre de que la persona a la que está + respondiendo esté en la lista Cc:. Esta convención también hace que no + sea necesario solicitar explícitamente que se le copie en las respuestas + a sus publicaciones. + +- Busque en los archivos de la lista (y en la red en su conjunto) antes + de hacer preguntas. Algunos desarrolladores pueden impacientarse con + las personas que claramente no han hecho sus deberes. + +- Utilice respuestas intercaladas (“en línea”), lo que hace que su + respuesta sea más fácil de leer. (Es decir, evite top-posting – la + práctica de poner su respuesta encima del texto citado al que está + respondiendo.) Para obtener más información, consulte + :ref:`Documentation/translations/sp_SP/process/submitting-patches.rst <sp_interleaved_replies>`. + +- Pregunte en la lista de correo correcta. linux-kernel puede ser el + punto de encuentro general, pero no es el mejor lugar para encontrar + desarrolladores de todos los subsistemas. + +El último punto, encontrar la lista de correo correcta, es una fuente +común de errores para desarrolladores principiantes. Alguien que haga +una pregunta relacionada con las redes en linux-kernel seguramente +recibirá una surgencia educada para preguntar en la lista de netdev en su +lugar, ya que esa es la lista frecuentada por la mayoría de los +desarrolladores de redes. Existen otras listas para los subsistemas SCSI, +video4linux, IDE, sistema de archivos, etc. El mejor lugar para buscar +listas de correo es en el archivo MAINTAINERS incluido con el código +fuente del kernel. + +Comenzar con el desarrollo del kernel +------------------------------------- + +Las preguntas sobre como comenzar con el proceso de desarrollo del kernel +son comunes, tanto de individuos como de empresas. Igualmente comunes son +los pasos en falso que hacen que el comienzo de la relación sea más +difícil de lo que tiene que ser. + +Las empresas a menudo buscan contratar desarrolladores conocidos para +iniciar un grupo de desarrollo. De hecho, esta puede ser una técnica +efectiva. Pero también tiende a ser caro y no hace mucho para crecer el +grupo de desarrolladores de kernel experimentados. Es posible poner al +día a los desarrolladores internos en el desarrollo de kernel de Linux, +dada la inversión de algún tiempo. Tomarse este tiempo puede dotar a un +empleador de un grupo de desarrolladores que comprendan tanto el kernel +como la empresa, y que también puedan ayudar a educar a otros. A medio +plazo, este es a menudo el enfoque más rentable. + +Los desarrolladores individuales, a menudo, comprensiblemente, no tienen +un lugar para empezar. Comenzar con un proyecto grande puede ser +intimidante; a menudo uno quiere probar las aguas con algo más pequeño +primero. Este es el punto en el que algunos desarrolladores se lanzan a +la creación de parches para corregir errores ortográficos o problemas +menores de estilo de codificación. Desafortunadamente, dicho parches +crean un nivel de ruido que distrae a la comunidad de desarrollo en su +conjunto, por lo que, cada vez más, se los mira con desprecio. Los nuevos +desarrolladores que deseen presentarse a la comunidad no recibirán la +recepción que desean por estos medios. + +Andrew Morton da este consejo (traducido) para los aspirantes a +desarrolladores de kernel. + +:: + + El proyecto #1 para los principiantes en el kernel seguramente debería + ser “asegúrese de que el kernel funcione perfectamente en todo momento + en todas las máquinas que pueda conseguir”. Por lo general, la forma + de hacer esto es trabajar con otros para arreglar las cosas (¡esto + puede requerir persistencia!), pero eso está bien, es parte del + desarrollo del kernel. + +(https://lwn.net/Articles/283982/) + +En ausencia de problemas obvios que solucionar, se aconseja a los +desarrolladores que consulten las listas actuales de regresiones y errores +abiertos en general. Nunca faltan problemas que necesitan solución; al +abordar estos problemas, los desarrolladores ganarán experiencia con el +proceso mientras, al mismo tiempo, se ganarán el respeto del resto de la +comunidad de desarrollo. diff --git a/Documentation/translations/sp_SP/process/3.Early-stage.rst b/Documentation/translations/sp_SP/process/3.Early-stage.rst new file mode 100644 index 000000000000..71cfb3fb0fda --- /dev/null +++ b/Documentation/translations/sp_SP/process/3.Early-stage.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/3.Early-stage.rst + +.. _sp_development_early_stage: + +Planificación en etapa inicial +============================== + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/4.Coding.rst b/Documentation/translations/sp_SP/process/4.Coding.rst new file mode 100644 index 000000000000..d9436e039b4b --- /dev/null +++ b/Documentation/translations/sp_SP/process/4.Coding.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/4.Coding.rst + +.. _sp_development_coding: + +Conseguir el código correcto +============================ + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/5.Posting.rst b/Documentation/translations/sp_SP/process/5.Posting.rst new file mode 100644 index 000000000000..50a3bc5998a8 --- /dev/null +++ b/Documentation/translations/sp_SP/process/5.Posting.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/5.Posting.rst + +.. _sp_development_posting: + +Publicar parches +================ + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/6.Followthrough.rst b/Documentation/translations/sp_SP/process/6.Followthrough.rst new file mode 100644 index 000000000000..f0acf9082bb3 --- /dev/null +++ b/Documentation/translations/sp_SP/process/6.Followthrough.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/6.Followthrough.rst + +.. _sp_development_followthrough: + +Seguimiento +=========== + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/7.AdvancedTopics.rst b/Documentation/translations/sp_SP/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..553759857339 --- /dev/null +++ b/Documentation/translations/sp_SP/process/7.AdvancedTopics.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/7.AdvancedTopics.rst + +.. _sp_development_advancedtopics: + +Temas avanzados +=============== + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/8.Conclusion.rst b/Documentation/translations/sp_SP/process/8.Conclusion.rst new file mode 100644 index 000000000000..dd181cb8ec9a --- /dev/null +++ b/Documentation/translations/sp_SP/process/8.Conclusion.rst @@ -0,0 +1,11 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/8.Conclusion.rst + +.. _sp_development_conclusion: + +Para más información +==================== + +.. warning:: + TODO aún no traducido diff --git a/Documentation/translations/sp_SP/process/code-of-conduct.rst b/Documentation/translations/sp_SP/process/code-of-conduct.rst index adc6c770cc37..a6c08613aefc 100644 --- a/Documentation/translations/sp_SP/process/code-of-conduct.rst +++ b/Documentation/translations/sp_SP/process/code-of-conduct.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` -:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_code_of_conduct: diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index a37274764371..b5a84df44cea 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/coding-style.rst <submittingpatches>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_codingstyle: diff --git a/Documentation/translations/sp_SP/process/development-process.rst b/Documentation/translations/sp_SP/process/development-process.rst new file mode 100644 index 000000000000..40d74086f22e --- /dev/null +++ b/Documentation/translations/sp_SP/process/development-process.rst @@ -0,0 +1,27 @@ +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/development-process.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +.. _sp_development_process_main: + +Guía del proceso de desarrollo del kernel +========================================= + +El propósito de este documento es ayudar a los desarrolladores (y sus +gerentes) a trabajar con la comunidad de desarrollo con un mínimo de +frustración. Es un intento de documentar cómo funciona esta comunidad +de una manera accesible para aquellos que no están familiarizados +íntimamente con el desarrollo del kernel de Linux (o, de hecho, el +desarrollo de software libre en general). Si bien hay algo de material +técnico aquí, este es en gran medida una discusión orientada al proceso +que no requiere un conocimiento profundo de la programación del kernel +para entenderla. + +.. toctree:: + :caption: Contenido + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process diff --git a/Documentation/translations/sp_SP/process/email-clients.rst b/Documentation/translations/sp_SP/process/email-clients.rst index fdf1e51b84e4..55d5803daf41 100644 --- a/Documentation/translations/sp_SP/process/email-clients.rst +++ b/Documentation/translations/sp_SP/process/email-clients.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/email-clients.rst <email_clients>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_email_clients: diff --git a/Documentation/translations/sp_SP/process/howto.rst b/Documentation/translations/sp_SP/process/howto.rst index dd793c0f8574..72ea855ac9dc 100644 --- a/Documentation/translations/sp_SP/process/howto.rst +++ b/Documentation/translations/sp_SP/process/howto.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/howto.rst <process_howto>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_process_howto: diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 2239373b3999..4892159310ff 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -28,3 +28,4 @@ management-style submit-checklist howto + development-process diff --git a/Documentation/translations/sp_SP/process/kernel-docs.rst b/Documentation/translations/sp_SP/process/kernel-docs.rst index 2f9b3df8f8fa..a62c6854f59b 100644 --- a/Documentation/translations/sp_SP/process/kernel-docs.rst +++ b/Documentation/translations/sp_SP/process/kernel-docs.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_kernel_docs: diff --git a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst index d66902694089..d47a1c154610 100644 --- a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst +++ b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_process_statement_kernel: diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst index 7c7dfb4ba80b..32a99aac2f6c 100644 --- a/Documentation/translations/sp_SP/process/magic-number.rst +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_magicnumbers: diff --git a/Documentation/translations/sp_SP/process/programming-language.rst b/Documentation/translations/sp_SP/process/programming-language.rst index 301f525372d8..ba2164057f45 100644 --- a/Documentation/translations/sp_SP/process/programming-language.rst +++ b/Documentation/translations/sp_SP/process/programming-language.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/programming-language.rst <programming_language>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_programming_language: diff --git a/Documentation/translations/sp_SP/process/submitting-patches.rst b/Documentation/translations/sp_SP/process/submitting-patches.rst index c2757d9ab216..328ec80bd61d 100644 --- a/Documentation/translations/sp_SP/process/submitting-patches.rst +++ b/Documentation/translations/sp_SP/process/submitting-patches.rst @@ -1,7 +1,7 @@ .. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` -:Translator: Carlos Bilbao <carlos.bilbao@amd.com> +:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> .. _sp_submittingpatches: @@ -356,6 +356,34 @@ Consulte Documentation/process/email-clients.rst para obtener recomendaciones sobre clientes de correo electrónico y normas de etiqueta en la lista de correo. +.. _sp_interleaved_replies: + +Uso de respuestas intercaladas recortadas en las discusiones por correo electrónico +----------------------------------------------------------------------------------- + +Se desaconseja encarecidamente la publicación en la parte superior de las +discusiones sobre el desarrollo del kernel de Linux. Las respuestas +intercaladas (o "en línea") hacen que las conversaciones sean mucho más +fáciles de seguir. Para obtener más detalles, consulte: +https://en.wikipedia.org/wiki/Posting_style#Interleaved_style + +Como se cita frecuentemente en la lista de correo:: + + A: http://en.wikipedia.org/wiki/Top_post + Q: ¿Dónde puedo encontrar información sobre esto que se llama top-posting? + A: Porque desordena el orden en el que la gente normalmente lee el texto. + Q: ¿Por qué es tan malo el top-posting? + A: Top-posting. + Q: ¿Qué es lo más molesto del correo electrónico? + +Del mismo modo, por favor, recorte todas las citas innecesarias que no +sean relevantes para su respuesta. Esto hace que las respuestas sean más +fáciles de encontrar y ahorra tiempo y espacio. Para obtener más +información, consulte: http://daringfireball.net/2007/07/on_top :: + + A: No. + Q: ¿Debo incluir citas después de mi respuesta? + .. _sp_resend_reminders: No se desanime o impaciente diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index 7fac6f75d078..fe0ff5a127f3 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -7,12 +7,13 @@ 司延腾 Yanteng Si <siyanteng@loongson.cn> 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + 陈兴友 Xingyou Chen <rockrush@rockwork.org> .. _cn_workqueue.rst: -========================= -并发管理的工作队列 (cmwq) -========================= +======== +工作队列 +======== :日期: September, 2010 :作者: Tejun Heo <tj@kernel.org> @@ -22,7 +23,7 @@ 简介 ==== -在很多情况下,需要一个异步进程的执行环境,工作队列(wq)API是这种情况下 +在很多情况下,需要一个异步的程序执行环境,工作队列(wq)API是这种情况下 最常用的机制。 当需要这样一个异步执行上下文时,一个描述将要执行的函数的工作项(work, @@ -34,8 +35,8 @@ 队列时,工作者又开始执行。 -为什么要cmwq? -============= +为什么要有并发管理工作队列? +=========================== 在最初的wq实现中,多线程(MT)wq在每个CPU上有一个工作者线程,而单线程 (ST)wq在全系统有一个工作者线程。一个MT wq需要保持与CPU数量相同的工 @@ -73,9 +74,11 @@ 向该函数的工作项,并在工作队列中排队等待该工作项。(就是挂到workqueue 队列里面去) -特定目的线程,称为工作线程(工作者),一个接一个地执行队列中的功能。 -如果没有工作项排队,工作者线程就会闲置。这些工作者线程被管理在所谓 -的工作者池中。 +工作项可以在线程或BH(软中断)上下文中执行。 + +对于由线程执行的工作队列,被称为(内核)工作者([k]worker)的特殊 +线程会依次执行其中的函数。如果没有工作项排队,工作者线程就会闲置。 +这些工作者线程被管理在所谓的工作者池中。 cmwq设计区分了面向用户的工作队列,子系统和驱动程序在上面排队工作, 以及管理工作者池和处理排队工作项的后端机制。 @@ -84,6 +87,10 @@ cmwq设计区分了面向用户的工作队列,子系统和驱动程序在上 优先级的工作项,还有一些额外的工作者池,用于服务未绑定工作队列的工 作项目——这些后备池的数量是动态的。 +BH工作队列使用相同的结构。然而,由于同一时间只可能有一个执行上下文, +不需要担心并发问题。每个CPU上的BH工作者池只包含一个用于表示BH执行 +上下文的虚拟工作者。BH工作队列可以被看作软中断的便捷接口。 + 当他们认为合适的时候,子系统和驱动程序可以通过特殊的 ``workqueue API`` 函数创建和排队工作项。他们可以通过在工作队列上 设置标志来影响工作项执行方式的某些方面,他们把工作项放在那里。这些 @@ -95,9 +102,9 @@ cmwq设计区分了面向用户的工作队列,子系统和驱动程序在上 否则一个绑定的工作队列的工作项将被排在与发起线程运行的CPU相关的普 通或高级工作工作者池的工作项列表中。 -对于任何工作者池的实施,管理并发水平(有多少执行上下文处于活动状 -态)是一个重要问题。最低水平是为了节省资源,而饱和水平是指系统被 -充分使用。 +对于任何线程池的实施,管理并发水平(有多少执行上下文处于活动状 +态)是一个重要问题。cmwq试图将并发保持在一个尽可能低且充足的 +水平。最低水平是为了节省资源,而充足是为了使系统能被充分使用。 每个与实际CPU绑定的worker-pool通过钩住调度器来实现并发管理。每当 一个活动的工作者被唤醒或睡眠时,工作者池就会得到通知,并跟踪当前可 @@ -140,6 +147,17 @@ workqueue将自动创建与属性相匹配的后备工作者池。调节并发 ``flags`` --------- +``WQ_BH`` + BH工作队列可以被看作软中断的便捷接口。它总是每个CPU一份, + 其中的各个工作项也会按在队列中的顺序,被所属CPU在软中断 + 上下文中执行。 + + BH工作队列的 ``max_active`` 值必须为0,且只能单独或和 + ``WQ_HIGHPRI`` 标志组合使用。 + + BH工作项不可以睡眠。像延迟排队、冲洗、取消等所有其他特性 + 都是支持的。 + ``WQ_UNBOUND`` 排队到非绑定wq的工作项由特殊的工作者池提供服务,这些工作者不 绑定在任何特定的CPU上。这使得wq表现得像一个简单的执行环境提 @@ -184,25 +202,21 @@ workqueue将自动创建与属性相匹配的后备工作者池。调节并发 -------------- ``@max_active`` 决定了每个CPU可以分配给wq的工作项的最大执行上 -下文数量。例如,如果 ``@max_active为16`` ,每个CPU最多可以同 -时执行16个wq的工作项。 +下文数量。例如,如果 ``@max_active`` 为16 ,每个CPU最多可以同 +时执行16个wq的工作项。它总是每CPU属性,即便对于未绑定 wq。 -目前,对于一个绑定的wq, ``@max_active`` 的最大限制是512,当指 -定为0时使用的默认值是256。对于非绑定的wq,其限制是512和 -4 * ``num_possible_cpus()`` 中的较高值。这些值被选得足够高,所 -以它们不是限制性因素,同时会在失控情况下提供保护。 +``@max_active`` 的最大限制是512,当指定为0时使用的默认值是256。 +这些值被选得足够高,所以它们不是限制性因素,同时会在失控情况下提供 +保护。 一个wq的活动工作项的数量通常由wq的用户来调节,更具体地说,是由用 户在同一时间可以排列多少个工作项来调节。除非有特定的需求来控制活动 工作项的数量,否则建议指定 为"0"。 -一些用户依赖于ST wq的严格执行顺序。 ``@max_active`` 为1和 ``WQ_UNBOUND`` -的组合用来实现这种行为。这种wq上的工作项目总是被排到未绑定的工作池 -中,并且在任何时候都只有一个工作项目处于活动状态,从而实现与ST wq相 -同的排序属性。 - -在目前的实现中,上述配置只保证了特定NUMA节点内的ST行为。相反, -``alloc_ordered_workqueue()`` 应该被用来实现全系统的ST行为。 +一些用户依赖于任意时刻最多只有一个工作项被执行,且各工作项被按队列中 +顺序处理带来的严格执行顺序。``@max_active`` 为1和 ``WQ_UNBOUND`` +的组合曾被用来实现这种行为,现在不用了。请使用 +``alloc_ordered_workqueue()`` 。 执行场景示例 @@ -285,7 +299,7 @@ And with cmwq with ``@max_active`` >= 3, :: * 除非有特殊需要,建议使用0作为@max_active。在大多数使用情 况下,并发水平通常保持在默认限制之下。 -* 一个wq作为前进进度保证(WQ_MEM_RECLAIM,冲洗(flush)和工 +* 一个wq作为前进进度保证,``WQ_MEM_RECLAIM`` ,冲洗(flush)和工 作项属性的域。不涉及内存回收的工作项,不需要作为工作项组的一 部分被刷新,也不需要任何特殊属性,可以使用系统中的一个wq。使 用专用wq和系统wq在执行特性上没有区别。 @@ -294,6 +308,337 @@ And with cmwq with ``@max_active`` >= 3, :: 益的,因为wq操作和工作项执行中的定位水平提高了。 +亲和性作用域 +============ + +一个非绑定工作队列根据其亲和性作用域来对CPU进行分组以提高缓存 +局部性。比如如果一个工作队列使用默认的“cache”亲和性作用域, +它将根据最后一级缓存的边界来分组处理器。这个工作队列上的工作项 +将被分配给一个与发起CPU共用最后级缓存的处理器上的工作者。根据 +``affinity_strict`` 的设置,工作者在启动后可能被允许移出 +所在作用域,也可能不被允许。 + +工作队列目前支持以下亲和性作用域。 + +``default`` + 使用模块参数 ``workqueue.default_affinity_scope`` 指定 + 的作用域,该参数总是会被设为以下作用域中的一个。 + +``cpu`` + CPU不被分组。一个CPU上发起的工作项会被同一CPU上的工作者执行。 + 这使非绑定工作队列表现得像是不含并发管理的每CPU工作队列。 + +``smt`` + CPU被按SMT边界分组。这通常意味着每个物理CPU核上的各逻辑CPU会 + 被分进同一组。 + +``cache`` + CPU被按缓存边界分组。采用哪个缓存边界由架构代码决定。很多情况 + 下会使用L3。这是默认的亲和性作用域。 + +``numa`` + CPU被按NUMA边界分组。 + +``system`` + 所有CPU被放在同一组。工作队列不尝试在临近发起CPU的CPU上运行 + 工作项。 + +默认的亲和性作用域可以被模块参数 ``workqueue.default_affinity_scope`` +修改,特定工作队列的亲和性作用域可以通过 ``apply_workqueue_attrs()`` +被更改。 + +如果设置了 ``WQ_SYSFS`` ,工作队列会在它的 ``/sys/devices/virtual/workqueue/WQ_NAME/`` +目录中有以下亲和性作用域相关的接口文件。 + +``affinity_scope`` + 读操作以查看当前的亲和性作用域。写操作用于更改设置。 + + 当前作用域是默认值时,当前生效的作用域也可以被从这个文件中 + 读到(小括号内),例如 ``default (cache)`` 。 + +``affinity_strict`` + 默认值0表明亲和性作用域不是严格的。当一个工作项开始执行时, + 工作队列尽量尝试使工作者处于亲和性作用域内,称为遣返。启动后, + 调度器可以自由地将工作者调度到系统中任意它认为合适的地方去。 + 这使得在保留使用其他CPU(如果必需且有可用)能力的同时, + 还能从作用域局部性上获益。 + + 如果设置为1,作用域内的所有工作者将被保证总是处于作用域内。 + 这在跨亲和性作用域会导致如功耗、负载隔离等方面的潜在影响时 + 会有用。严格的NUMA作用域也可用于和旧版内核中工作队列的行为 + 保持一致。 + + +亲和性作用域与性能 +================== + +如果非绑定工作队列的行为对绝大多数使用场景来说都是最优的, +不需要更多调节,就完美了。很不幸,在当前内核中,重度使用 +工作队列时,需要在局部性和利用率间显式地作一个明显的权衡。 + +更高的局部性带来更高效率,也就是相同数量的CPU周期内可以做 +更多工作。然而,如果发起者没能将工作项充分地分散在亲和性 +作用域间,更高的局部性也可能带来更低的整体系统利用率。以下 +dm-crypt 的性能测试清楚地阐明了这一取舍。 + +测试运行在一个12核24线程、4个L3缓存的处理器(AMD Ryzen +9 3900x)上。为保持一致性,关闭CPU超频。 ``/dev/dm-0`` +是NVME SSD(三星 990 PRO)上创建,用 ``cryptsetup`` +以默认配置打开的一个 dm-crypt 设备。 + + +场景 1: 机器上遍布着有充足的发起者和工作量 +------------------------------------------ + +使用命令::: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k --ioengine=libaio \ + --iodepth=64 --runtime=60 --numjobs=24 --time_based --group_reporting \ + --name=iops-test-job --verify=sha512 + +这里有24个发起者,每个同时发起64个IO。 ``--verify=sha512`` +使得 ``fio`` 每次生成和读回内容受发起者和 ``kcryptd`` +间的执行局部性影响。下面是基于不同 ``kcryptd`` 的亲和性 +作用域设置,各经过五次测试得到的读取带宽和CPU利用率数据。 + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - 亲和性 + - 带宽 (MiBps) + - CPU利用率(%) + + * - system + - 1159.40 ±1.34 + - 99.31 ±0.02 + + * - cache + - 1166.40 ±0.89 + - 99.34 ±0.01 + + * - cache (strict) + - 1166.00 ±0.71 + - 99.35 ±0.01 + +在系统中分布着足够多发起者的情况下,不论严格与否,“cache” +没有表现得更差。三种配置均使整个机器达到饱和,但由于提高了 +局部性,缓存相关的两种有0.6%的(带宽)提升。 + + +场景 2: 更少发起者,足以达到饱和的工作量 +---------------------------------------- + +使用命令::: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k \ + --ioengine=libaio --iodepth=64 --runtime=60 --numjobs=8 \ + --time_based --group_reporting --name=iops-test-job --verify=sha512 + +与上一个场景唯一的区别是 ``--numjobs=8``。 发起者数量 +减少为三分之一,但仍然有足以使系统达到饱和的工作总量。 + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - 亲和性 + - 带宽 (MiBps) + - CPU利用率(%) + + * - system + - 1155.40 ±0.89 + - 97.41 ±0.05 + + * - cache + - 1154.40 ±1.14 + - 96.15 ±0.09 + + * - cache (strict) + - 1112.00 ±4.64 + - 93.26 ±0.35 + +这里有超过使系统达到饱和所需的工作量。“system”和“cache” +都接近但并未使机器完全饱和。“cache”消耗更少的CPU但更高的 +效率使其得到和“system”相同的带宽。 + +八个发起者盘桓在四个L3缓存作用域间仍然允许“cache (strict)” +几乎使机器饱和,但缺少对工作的保持(不移到空闲处理器上) +开始带来3.7%的带宽损失。 + + +场景 3: 更少发起者,不充足的工作量 +---------------------------------- + +使用命令::: + + $ fio --filename=/dev/dm-0 --direct=1 --rw=randrw --bs=32k \ + --ioengine=libaio --iodepth=64 --runtime=60 --numjobs=4 \ + --time_based --group_reporting --name=iops-test-job --verify=sha512 + +再次,唯一的区别是 ``--numjobs=4``。由于发起者减少到四个, +现在没有足以使系统饱和的工作量,带宽变得依赖于完成时延。 + +.. list-table:: + :widths: 16 20 20 + :header-rows: 1 + + * - 亲和性 + - 带宽 (MiBps) + - CPU利用率(%) + + * - system + - 993.60 ±1.82 + - 75.49 ±0.06 + + * - cache + - 973.40 ±1.52 + - 74.90 ±0.07 + + * - cache (strict) + - 828.20 ±4.49 + - 66.84 ±0.29 + +现在,局部性和利用率间的权衡更清晰了。“cache”展示出相比 +“system”2%的带宽损失,而“cache (strict)”跌到20%。 + + +结论和建议 +---------- + +在以上试验中,虽然一致并且也明显,但“cache”亲和性作用域 +相比“system”的性能优势并不大。然而,这影响是依赖于作用域 +间距离的,在更复杂的处理器拓扑下可能有更明显的影响。 + +虽然这些情形下缺少工作保持是有坏处的,但比“cache (strict)” +好多了,而且最大化工作队列利用率的需求也并不常见。因此, +“cache”是非绑定池的默认亲和性作用域。 + +* 由于不存在一个适用于大多数场景的选择,对于可能需要消耗 + 大量CPU的工作队列,建议通过 ``apply_workqueue_attrs()`` + 进行(专门)配置,并考虑是否启用 ``WQ_SYSFS``。 + +* 设置了严格“cpu”亲和性作用域的非绑定工作队列,它的行为与 + ``WQ_CPU_INTENSIVE`` 每CPU工作队列一样。后者没有真正 + 优势,而前者提供了大幅度的灵活性。 + +* 亲和性作用域是从Linux v6.5起引入的。为了模拟旧版行为, + 可以使用严格的“numa”亲和性作用域。 + +* 不严格的亲和性作用域中,缺少工作保持大概缘于调度器。内核 + 为什么没能维护好大多数场景下的工作保持,把事情作对,还没有 + 理论上的解释。因此,未来调度器的改进可能会使我们不再需要 + 这些调节项。 + + +检查配置 +======== + +使用 tools/workqueue/wq_dump.py(drgn脚本) 来检查未 +绑定CPU的亲和性配置,工作者池,以及工作队列如何映射到池上: :: + + $ tools/workqueue/wq_dump.py + Affinity Scopes + =============== + wq_unbound_cpumask=0000000f + + CPU + nr_pods 4 + pod_cpus [0]=00000001 [1]=00000002 [2]=00000004 [3]=00000008 + pod_node [0]=0 [1]=0 [2]=1 [3]=1 + cpu_pod [0]=0 [1]=1 [2]=2 [3]=3 + + SMT + nr_pods 4 + pod_cpus [0]=00000001 [1]=00000002 [2]=00000004 [3]=00000008 + pod_node [0]=0 [1]=0 [2]=1 [3]=1 + cpu_pod [0]=0 [1]=1 [2]=2 [3]=3 + + CACHE (default) + nr_pods 2 + pod_cpus [0]=00000003 [1]=0000000c + pod_node [0]=0 [1]=1 + cpu_pod [0]=0 [1]=0 [2]=1 [3]=1 + + NUMA + nr_pods 2 + pod_cpus [0]=00000003 [1]=0000000c + pod_node [0]=0 [1]=1 + cpu_pod [0]=0 [1]=0 [2]=1 [3]=1 + + SYSTEM + nr_pods 1 + pod_cpus [0]=0000000f + pod_node [0]=-1 + cpu_pod [0]=0 [1]=0 [2]=0 [3]=0 + + Worker Pools + ============ + pool[00] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 0 + pool[01] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 0 + pool[02] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 1 + pool[03] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 1 + pool[04] ref= 1 nice= 0 idle/workers= 4/ 4 cpu= 2 + pool[05] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 2 + pool[06] ref= 1 nice= 0 idle/workers= 3/ 3 cpu= 3 + pool[07] ref= 1 nice=-20 idle/workers= 2/ 2 cpu= 3 + pool[08] ref=42 nice= 0 idle/workers= 6/ 6 cpus=0000000f + pool[09] ref=28 nice= 0 idle/workers= 3/ 3 cpus=00000003 + pool[10] ref=28 nice= 0 idle/workers= 17/ 17 cpus=0000000c + pool[11] ref= 1 nice=-20 idle/workers= 1/ 1 cpus=0000000f + pool[12] ref= 2 nice=-20 idle/workers= 1/ 1 cpus=00000003 + pool[13] ref= 2 nice=-20 idle/workers= 1/ 1 cpus=0000000c + + Workqueue CPU -> pool + ===================== + [ workqueue \ CPU 0 1 2 3 dfl] + events percpu 0 2 4 6 + events_highpri percpu 1 3 5 7 + events_long percpu 0 2 4 6 + events_unbound unbound 9 9 10 10 8 + events_freezable percpu 0 2 4 6 + events_power_efficient percpu 0 2 4 6 + events_freezable_power_ percpu 0 2 4 6 + rcu_gp percpu 0 2 4 6 + rcu_par_gp percpu 0 2 4 6 + slub_flushwq percpu 0 2 4 6 + netns ordered 8 8 8 8 8 + ... + +参见命令的帮助消息以获取更多信息。 + + +监视 +==== + +使用 tools/workqueue/wq_monitor.py 来监视工作队列的运行: :: + + $ tools/workqueue/wq_monitor.py events + total infl CPUtime CPUhog CMW/RPR mayday rescued + events 18545 0 6.1 0 5 - - + events_highpri 8 0 0.0 0 0 - - + events_long 3 0 0.0 0 0 - - + events_unbound 38306 0 0.1 - 7 - - + events_freezable 0 0 0.0 0 0 - - + events_power_efficient 29598 0 0.2 0 0 - - + events_freezable_power_ 10 0 0.0 0 0 - - + sock_diag_events 0 0 0.0 0 0 - - + + total infl CPUtime CPUhog CMW/RPR mayday rescued + events 18548 0 6.1 0 5 - - + events_highpri 8 0 0.0 0 0 - - + events_long 3 0 0.0 0 0 - - + events_unbound 38322 0 0.1 - 7 - - + events_freezable 0 0 0.0 0 0 - - + events_power_efficient 29603 0 0.2 0 0 - - + events_freezable_power_ 10 0 0.0 0 0 - - + sock_diag_events 0 0 0.0 0 0 - - + + ... + +参见命令的帮助消息以获取更多信息。 + + 调试 ==== @@ -330,7 +675,6 @@ And with cmwq with ``@max_active`` >= 3, :: 工作队列保证,如果在工作项排队后满足以下条件,则工作项不能重入: - 1. 工作函数没有被改变。 2. 没有人将该工作项排到另一个工作队列中。 3. 该工作项尚未被重新启动。 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index c2db3e566b1b..fa900f5beb68 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -22,14 +22,14 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst sparse gcov kasan + kcov + ubsan + kmemleak gdb-kernel-debugging Todolist: - coccinelle - - kcov - - ubsan - - kmemleak - kcsan - kfence - kgdb diff --git a/Documentation/translations/zh_CN/dev-tools/kcov.rst b/Documentation/translations/zh_CN/dev-tools/kcov.rst new file mode 100644 index 000000000000..629154df7121 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/kcov.rst @@ -0,0 +1,359 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/kcov.rst +:Translator: 刘浩阳 Haoyang Liu <tttturtleruss@hust.edu.cn> + +KCOV: 用于模糊测试的代码覆盖率 +============================== + +KCOV 以一种适用于覆盖率引导的模糊测试的形式收集和暴露内核代码覆盖率信息。 +一个正在运行的内核的覆盖率数据可以通过 ``kcov`` 调试文件导出。覆盖率的收集是基 +于任务启用的,因此 KCOV 可以精确捕获单个系统调用的覆盖率。 + +要注意的是 KCOV 不是为了收集尽可能多的覆盖率数据。而是为了收集相对稳定的覆盖率 +,这是系统调用输入的函数。为了完成这个目标,它不收集软硬中断的覆盖率(除非移除 +覆盖率收集被启用,见下文)以及内核中固有的不确定部分的覆盖率(如调度器,锁定) + +除了收集代码覆盖率,KCOV 还收集操作数比较的覆盖率。见 "操作数比较收集" 一节 +查看详细信息。 + +除了从系统调用处理器收集覆盖率数据,KCOV 还从后台内核或软中断任务中执行的内核 +被标注的部分收集覆盖率。见 "远程覆盖率收集" 一节查看详细信息。 + +先决条件 +-------- + +KCOV 依赖编译器插桩,要求 GCC 6.1.0 及更高版本或者内核支持的任意版本的 Clang。 + +收集操作数比较的覆盖率需要 GCC 8+ 或者 Clang。 + +为了启用 KCOV,需要使用如下参数配置内核:: + + CONFIG_KCOV=y + +为了启用操作数比较覆盖率的收集,使用如下参数:: + + CONFIG_KCOV_ENABLE_COMPARISONS=y + +覆盖率数据只会在调试文件系统被挂载后才可以获取:: + + mount -t debugfs none /sys/kernel/debug + +覆盖率收集 +---------- + +下面的程序演示了如何使用 KCOV 在一个测试程序中收集单个系统调用的覆盖率: + +.. code-block:: c + + #include <stdio.h> + #include <stddef.h> + #include <stdint.h> + #include <stdlib.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <sys/ioctl.h> + #include <sys/mman.h> + #include <unistd.h> + #include <fcntl.h> + #include <linux/types.h> + + #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) + #define KCOV_ENABLE _IO('c', 100) + #define KCOV_DISABLE _IO('c', 101) + #define COVER_SIZE (64<<10) + + #define KCOV_TRACE_PC 0 + #define KCOV_TRACE_CMP 1 + + int main(int argc, char **argv) + { + int fd; + unsigned long *cover, n, i; + + /* 单个文件描述符允许 + * 在单线程上收集覆盖率。 + */ + fd = open("/sys/kernel/debug/kcov", O_RDWR); + if (fd == -1) + perror("open"), exit(1); + /* 设置跟踪模式和跟踪大小。 */ + if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE)) + perror("ioctl"), exit(1); + /* 映射内核空间和用户空间共享的缓冲区。 */ + cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + if ((void*)cover == MAP_FAILED) + perror("mmap"), exit(1); + /* 在当前线程中启用覆盖率收集。 */ + if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC)) + perror("ioctl"), exit(1); + /* 在调用 ioctl() 之后重置覆盖率。 */ + __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED); + /* 调用目标系统调用。 */ + read(-1, NULL, 0); + /* 读取收集到的 PC 的数目。 */ + n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); + for (i = 0; i < n; i++) + printf("0x%lx\n", cover[i + 1]); + /* 在当前线程上禁用覆盖率收集。在这之后 + * 可以在其他线程上收集覆盖率 + */ + if (ioctl(fd, KCOV_DISABLE, 0)) + perror("ioctl"), exit(1); + /* 释放资源 */ + if (munmap(cover, COVER_SIZE * sizeof(unsigned long))) + perror("munmap"), exit(1); + if (close(fd)) + perror("close"), exit(1); + return 0; + } + +在使用 ``addr2line`` 传输后,程序输出应该如下所示:: + + SyS_read + fs/read_write.c:562 + __fdget_pos + fs/file.c:774 + __fget_light + fs/file.c:746 + __fget_light + fs/file.c:750 + __fget_light + fs/file.c:760 + __fdget_pos + fs/file.c:784 + SyS_read + fs/read_write.c:562 + +如果一个程序需要从多个线程收集覆盖率(独立地)。那么每个线程都需要单独打开 +``/sys/kernel/debug/kcov``。 + +接口的细粒度允许高效的创建测试进程。即,一个父进程打开了 +``/sys/kernel/debug/kcov``,启用了追踪模式,映射了覆盖率缓冲区,然后在一个循 +环中创建了子进程。这个子进程只需要启用覆盖率收集即可(当一个线程退出时将自动禁 +用覆盖率收集)。 + +操作数比较收集 +-------------- + +操作数比较收集和覆盖率收集类似: + +.. code-block:: c + + /* 包含和上文一样的头文件和宏定义。 */ + + /* 每次记录的 64 位字的数量。 */ + #define KCOV_WORDS_PER_CMP 4 + + /* + * 收集的比较种类的格式。 + * + * 0 比特表示是否是一个编译时常量。 + * 1 & 2 比特包含参数大小的 log2 值,最大 8 字节。 + */ + + #define KCOV_CMP_CONST (1 << 0) + #define KCOV_CMP_SIZE(n) ((n) << 1) + #define KCOV_CMP_MASK KCOV_CMP_SIZE(3) + + int main(int argc, char **argv) + { + int fd; + uint64_t *cover, type, arg1, arg2, is_const, size; + unsigned long n, i; + + fd = open("/sys/kernel/debug/kcov", O_RDWR); + if (fd == -1) + perror("open"), exit(1); + if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE)) + perror("ioctl"), exit(1); + /* + * 注意缓冲区指针的类型是 uint64_t*,因为所有的 + * 比较操作数都被提升为 uint64_t 类型。 + */ + cover = (uint64_t *)mmap(NULL, COVER_SIZE * sizeof(unsigned long), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + if ((void*)cover == MAP_FAILED) + perror("mmap"), exit(1); + /* 注意这里是 KCOV_TRACE_CMP 而不是 KCOV_TRACE_PC。 */ + if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_CMP)) + perror("ioctl"), exit(1); + __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED); + read(-1, NULL, 0); + /* 读取收集到的比较操作数的数量。 */ + n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); + for (i = 0; i < n; i++) { + uint64_t ip; + + type = cover[i * KCOV_WORDS_PER_CMP + 1]; + /* arg1 和 arg2 - 比较的两个操作数。 */ + arg1 = cover[i * KCOV_WORDS_PER_CMP + 2]; + arg2 = cover[i * KCOV_WORDS_PER_CMP + 3]; + /* ip - 调用者的地址。 */ + ip = cover[i * KCOV_WORDS_PER_CMP + 4]; + /* 操作数的大小。 */ + size = 1 << ((type & KCOV_CMP_MASK) >> 1); + /* is_const - 当操作数是一个编译时常量时为真。*/ + is_const = type & KCOV_CMP_CONST; + printf("ip: 0x%lx type: 0x%lx, arg1: 0x%lx, arg2: 0x%lx, " + "size: %lu, %s\n", + ip, type, arg1, arg2, size, + is_const ? "const" : "non-const"); + } + if (ioctl(fd, KCOV_DISABLE, 0)) + perror("ioctl"), exit(1); + /* 释放资源。 */ + if (munmap(cover, COVER_SIZE * sizeof(unsigned long))) + perror("munmap"), exit(1); + if (close(fd)) + perror("close"), exit(1); + return 0; + } + +注意 KCOV 的模式(代码覆盖率收集或操作数比较收集)是互斥的。 + +远程覆盖率收集 +-------------- + +除了从用户空间进程发布的系统调用句柄收集覆盖率数据以外,KCOV 也可以从部分在其 +他上下文中执行的内核中收集覆盖率 - 称为“远程”覆盖率。 + +使用 KCOV 收集远程覆盖率要求: + +1. 修改内核源码并使用 ``kcov_remote_start`` 和 ``kcov_remote_stop`` 来标注要收集 + 覆盖率的代码片段。 + +2. 在用户空间的收集覆盖率的进程应使用 ``KCOV_REMOTE_ENABLE`` 而不是 ``KCOV_ENABLE``。 + +``kcov_remote_start`` 和 ``kcov_remote_stop`` 的标注以及 ``KCOV_REMOTE_ENABLE`` +ioctl 都接受可以识别特定覆盖率收集片段的句柄。句柄的使用方式取决于匹配代码片段执 +行的上下文。 + +KCOV 支持在如下上下文中收集远程覆盖率: + +1. 全局内核后台任务。这些任务是内核启动时创建的数量有限的实例(如,每一个 + USB HCD 产生一个 USB ``hub_event`` 工作器)。 + +2. 局部内核后台任务。这些任务通常是由于用户空间进程与某些内核接口进行交互时产 + 生的,并且通常在进程退出时会被停止(如,vhost 工作器)。 + +3. 软中断。 + +对于 #1 和 #3,必须选择一个独特的全局句柄并将其传递给对应的 +``kcov_remote_start`` 调用。一个用户空间进程必须将该句柄存储在 +``kcov_remote_arg`` 结构体的 ``handle`` 数组字段中并将其传递给 +``KCOV_REMOTE_ENABLE``。这会将使用的 KCOV 设备附加到由此句柄引用的代码片段。多个全局 +句柄标识的不同代码片段可以一次性传递。 + +对于 #2,用户空间进程必须通过 ``kcov_remote_arg`` 结构体的 ``common_handle`` 字段 +传递一个非零句柄。这个通用句柄将会被保存在当前 ``task_struct`` 结构体的 +``kcov_handle`` 字段中并且需要通过自定义内核代码的修改来传递给新创建的本地任务 +。这些任务需要在 ``kcov_remote_start`` 和 ``kcov_remote_stop`` 标注中依次使用传递过来的 +句柄。 + +KCOV 对全局句柄和通用句柄均遵循一个预定义的格式。每一个句柄都是一个 ``u64`` 整形 +。当前,只有最高位和低四位字节被使用。第 4-7 字节是保留位并且值必须为 0。 + +对于全局句柄,最高位的字节表示该句柄属于的子系统的标识。比如,KCOV 使用 ``1`` +表示 USB 子系统类型。全局句柄的低 4 字节表示子系统中任务实例的标识。比如,每一 +个 ``hub_event`` 工作器使用 USB 总线号作为任务实例的标识。 + +对于通用句柄,使用一个保留值 ``0`` 作为子系统标识,因为这些句柄不属于一个特定 +的子系统。通用句柄的低 4 字节用于识别有用户进程生成的所有本地句柄的集合实例, +该进程将通用句柄传递给 ``KCOV_REMOTE_ENABLE``。 + +实际上,如果只从系统中的单个用户空间进程收集覆盖率,那么可以使用任意值作为通用 +句柄的实例标识。然而,如果通用句柄被多个用户空间进程使用,每个进程必须使用唯一 +的实例标识。一个选择是使用进程标识作为通用句柄实例的标识。 + +下面的程序演示了如何使用 KCOV 从一个由进程产生的本地任务和处理 USB 总线的全局 +任务 #1 收集覆盖率: + +.. code-block:: c + + /* 包含和上文一样的头文件和宏定义。 */ + + struct kcov_remote_arg { + __u32 trace_mode; + __u32 area_size; + __u32 num_handles; + __aligned_u64 common_handle; + __aligned_u64 handles[0]; + }; + + #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) + #define KCOV_DISABLE _IO('c', 101) + #define KCOV_REMOTE_ENABLE _IOW('c', 102, struct kcov_remote_arg) + + #define COVER_SIZE (64 << 10) + + #define KCOV_TRACE_PC 0 + + #define KCOV_SUBSYSTEM_COMMON (0x00ull << 56) + #define KCOV_SUBSYSTEM_USB (0x01ull << 56) + + #define KCOV_SUBSYSTEM_MASK (0xffull << 56) + #define KCOV_INSTANCE_MASK (0xffffffffull) + + static inline __u64 kcov_remote_handle(__u64 subsys, __u64 inst) + { + if (subsys & ~KCOV_SUBSYSTEM_MASK || inst & ~KCOV_INSTANCE_MASK) + return 0; + return subsys | inst; + } + + #define KCOV_COMMON_ID 0x42 + #define KCOV_USB_BUS_NUM 1 + + int main(int argc, char **argv) + { + int fd; + unsigned long *cover, n, i; + struct kcov_remote_arg *arg; + + fd = open("/sys/kernel/debug/kcov", O_RDWR); + if (fd == -1) + perror("open"), exit(1); + if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE)) + perror("ioctl"), exit(1); + cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + if ((void*)cover == MAP_FAILED) + perror("mmap"), exit(1); + + /* 通过通用句柄和 USB 总线 #1 启用代码覆盖率收集。 */ + arg = calloc(1, sizeof(*arg) + sizeof(uint64_t)); + if (!arg) + perror("calloc"), exit(1); + arg->trace_mode = KCOV_TRACE_PC; + arg->area_size = COVER_SIZE; + arg->num_handles = 1; + arg->common_handle = kcov_remote_handle(KCOV_SUBSYSTEM_COMMON, + KCOV_COMMON_ID); + arg->handles[0] = kcov_remote_handle(KCOV_SUBSYSTEM_USB, + KCOV_USB_BUS_NUM); + if (ioctl(fd, KCOV_REMOTE_ENABLE, arg)) + perror("ioctl"), free(arg), exit(1); + free(arg); + + /* + * 在这里用户需要触发执行一个内核代码段 + * 该代码段要么使用通用句柄标识 + * 要么触发了一些 USB 总线 #1 上的一些活动。 + */ + sleep(2); + + n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); + for (i = 0; i < n; i++) + printf("0x%lx\n", cover[i + 1]); + if (ioctl(fd, KCOV_DISABLE, 0)) + perror("ioctl"), exit(1); + if (munmap(cover, COVER_SIZE * sizeof(unsigned long))) + perror("munmap"), exit(1); + if (close(fd)) + perror("close"), exit(1); + return 0; + } diff --git a/Documentation/translations/zh_CN/dev-tools/kmemleak.rst b/Documentation/translations/zh_CN/dev-tools/kmemleak.rst new file mode 100644 index 000000000000..d248c8428095 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/kmemleak.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/kmemleak.rst +:Translator: 刘浩阳 Haoyang Liu <tttturtleruss@hust.edu.cn> + +内核内存泄露检测器 +================== + +Kmemleak 提供了一个类似 `可追踪的垃圾收集器 <https://en.wikipedia.org/wiki/Tra +cing_garbage_collection>`_ 的方法来检测可能的内核内存泄漏,不同的是孤立对象不会 +被释放,而是仅通过 /sys/kernel/debug/kmemleak 报告。Valgrind 工具 +(``memcheck --leak-check``)使用了一种相似的方法来检测用户空间应用中的内存泄 +露。 + +用法 +---- + +"Kernel hacking" 中的 CONFIG_DEBUG_KMEMLEAK 必须被启用。一个内核线程每10分钟 +(默认情况下)扫描一次内存,并且打印出新发现的未被引用的对象个数。 +如果 ``debugfs`` 没有挂载,则执行:: + + # mount -t debugfs nodev /sys/kernel/debug/ + +显示所有扫描出的可能的内存泄漏的细节信息:: + + # cat /sys/kernel/debug/kmemleak + +启动一次中等程度的内存扫描:: + + # echo scan > /sys/kernel/debug/kmemleak + +清空当前所有可能的内存泄露列表:: + + # echo clear > /sys/kernel/debug/kmemleak + +当再次读取 ``/sys/kernel/debug/kmemleak`` 文件时,将会输出自上次扫描以来检测到的 +新的内存泄露。 + +注意,孤立目标是通过被分配时间来排序的,列表开始的对象可能会导致后续的对象都被 +识别为孤立对象。 + +可以通过写入 ``/sys/kernel/debug/kmemleak`` 文件在运行时修改内存扫描参数。下面是 +支持的参数: + + +* off + 禁用 kmemleak(不可逆) +* stack=on + 开启任务栈扫描(默认) +* stack=off + 禁用任务栈扫描 +* scan=on + 开启自动内存扫描线程(默认) +* scan=off + 关闭自动内存扫描线程 +* scan=<secs>; + 设定自动内存扫描间隔,以秒为单位(默认值为 600,设置为 0 表示停 + 止自动扫描) +* scan + 触发一次内存扫描 +* clear + 通过标记所有当前已报告的未被引用对象为灰,从而清空当前可能的内存泄露列 + 表;如果 kmemleak 被禁用,则释放所有 kmemleak 对象,。 +* dump=<addr> + 输出存储在 <addr> 中的对象信息 + +可以通过在内核命令行中传递 ``kmemleak=off`` 参数从而在启动时禁用 Kmemleak。 + +在 kmemleak 初始化之前就可能会有内存分配或释放,这些操作被存储在一个早期日志缓 +冲区中。缓冲区的大小通过 CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE 选项配置。 + +如果 CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF 被启用,则 kmemleak 默认被禁用。在内核命 +令行中传递 ``kmemleak=on`` 参数来开启这个功能。 + +如果出现 "Error while writing to stdout" 或 "write_loop: Invalid argument" 这样 +的错误,请确认 kmemleak 被正确启用。 + +基础算法 +-------- + +通过 :c:func:`kmalloc`, :c:func:`vmalloc`, :c:func:`kmem_cache_alloc` 以及同类 +函数均被跟踪,指针,包括一些额外的信息如大小和栈追踪等,都被存储在红黑树中。 +对应的释放函数调用也被追踪,并从 kmemleak 数据结构中移除相应指针。 + +对于一个已分配的内存块,如果通过扫描内存(包括保存寄存器)没有发现任何指针指向 +它的起始地址或者其中的任何位置,则认为这块内存是孤立的。这意味着内核无法将该内 +存块的地址传递给一个释放内存函数,这块内存便被认为泄露了。 + +扫描算法步骤: + + 1. 标记所有对象为白色(最后剩下的白色对象被认为是孤立的) + 2. 从数据节和栈开始扫描内存,检测每个值是否是红黑树中存储的地址。如果一个指向 + 白色对象的指针被检测到,则将该对象标记为灰色。 + 3. 扫描灰色对象引用的其他对象(有些白色对象可能会变为灰色并被添加到灰名单末尾 + )直到灰名单为空。 + 4. 剩余的白色对象就被认为是孤立的并通过 /sys/kernel/debug/kmemleak 报告。 + +有些指向已分配的内存块的指针存储在内核内部的数据结构中,它们不能被检测为孤立。 +为了避免这种情况,kmemleak 也存储了指向需要被查找的内存块范围内的任意地址的地址 +数量,如此一来这些内存便不会被认为泄露。一个例子是 __vmalloc()。 + +用 kmemleak 测试特定部分 +------------------------ + +在初始化启动阶段 /sys/kernel/debug/kmemleak 的输出可能会很多,这也可能是你在开发 +时编写的漏洞百出的代码导致的。为了解决这种情况你可以使用 'clear' 命令来清除 +/sys/kernel/debug/kmemleak 输出的所有的未引用对象。在执行 'clear' 后执行 'scan' +可以发现新的未引用对象,这将会有利你测试代码的特定部分。 + +为了用一个空的 kmemleak 测试一个特定部分,执行:: + + # echo clear > /sys/kernel/debug/kmemleak + ... 测试你的内核或者模块 ... + # echo scan > /sys/kernel/debug/kmemleak + +然后像平常一样获得报告:: + + # cat /sys/kernel/debug/kmemleak + +释放 kmemleak 内核对象 +---------------------- + +为了允许访问先前发现的内存泄露,当用户禁用或发生致命错误导致 kmemleak +被禁用时,内核中的 kmemleak 对象不会被释放。这些对象可能会占用很大 +一部分物理内存。 + +在这种情况下,你可以用如下命令回收这些内存:: + + # echo clear > /sys/kernel/debug/kmemleak + +Kmemleak API +------------ + +在 include/linux/kmemleak.h 头文件中查看函数原型: + +- ``kmemleak_init`` - 初始化 kmemleak +- ``kmemleak_alloc`` - 通知一个内存块的分配 +- ``kmemleak_alloc_percpu`` - 通知一个 percpu 类型的内存分配 +- ``kmemleak_vmalloc`` - 通知一个使用 vmalloc() 的内存分配 +- ``kmemleak_free`` - 通知一个内存块的释放 +- ``kmemleak_free_part`` - 通知一个部分的内存释放 +- ``kmemleak_free_percpu`` - 通知一个 percpu 类型的内存释放 +- ``kmemleak_update_trace`` - 更新分配对象过程的栈追踪 +- ``kmemleak_not_leak`` - 标记一个对象内存为未泄露的 +- ``kmemleak_ignore`` - 不要扫描或报告某个对象未泄露的 +- ``kmemleak_scan_area`` - 在内存块中添加扫描区域 +- ``kmemleak_no_scan`` - 不扫描某个内存块 +- ``kmemleak_erase`` - 在指针变量中移除某个旧的值 +- ``kmemleak_alloc_recursive`` - 和 kmemleak_alloc 效果相同但会检查是否有递归的 + 内存分配 +- ``kmemleak_free_recursive`` - 和 kmemleak_free 效果相同但会检查是否有递归的 + 内存释放 + +下列函数使用一个物理地址作为对象指针并且只在地址有一个 lowmem 映射时做出相应的 +行为: + +- ``kmemleak_alloc_phys`` +- ``kmemleak_free_part_phys`` +- ``kmemleak_ignore_phys`` + +解决假阳性/假阴性 +----------------- + +假阴性是指由于在内存扫描中有值指向该对象导致 kmemleak 没有报告的实际存在的内存 +泄露(孤立对象)。为了减少假阴性的出现次数,kmemleak 提供了 kmemleak_ignore, +kmemleak_scan_area,kmemleak_no_scan 和 kmemleak_erase 函数(见上)。 +任务栈也会增加假阴性的数量并且默认不开启对它们的扫描。 + +假阳性是对象被误报为内存泄露(孤立对象)。对于已知未泄露的对象,kmemleak +提供了 kmemleak_not_leak 函数。同时 kmemleak_ignore 可以用于标记已知不包含任何 +其他指针的内存块,标记后该内存块不会再被扫描。 + +一些被报告的泄露仅仅是暂时的,尤其是在 SMP(对称多处理)系统中,因为其指针 +暂存在 CPU 寄存器或栈中。Kmemleak 定义了 MSECS_MIN_AGE(默认值为 1000) +来表示一个被报告为内存泄露的对象的最小存活时间。 + +限制和缺点 +---------- + +主要的缺点是内存分配和释放的性能下降。为了避免其他的损失,只有当 +/sys/kernel/debug/kmemleak 文件被读取时才会进行内存扫描。无论如何,这个工具是出于 +调试的目标,性能表现可能不是最重要的。 + +为了保持算法简单,kmemleak 寻找指向某个内存块范围中的任何值。这可能会引发假阴性 +现象的出现。但是,最后一个真正的内存泄露也会变得明显。 + +非指针值的数据是假阴性的另一个来源。在将来的版本中,kmemleak 仅仅会扫 +描已分配结构体中的指针成员。这个特性会解决上述很多的假阴性情况。 + +Kmemleak 会报告假阳性。这可能发生在某些被分配的内存块不需要被释放的情况下 +(某些 init_call 函数中),指针的计算是通过其他方法而不是常规的 container_of 宏 +或是指针被存储在 kmemleak 没有扫描的地方。 + +页分配和 ioremap 不会被追踪。 + +使用 kmemleak-test 测试 +----------------------- + +为了检测是否成功启用了 kmemleak,你可以使用一个故意制造内存泄露的模块 +kmemleak-test。设置 CONFIG_SAMPLE_KMEMLEAK 为模块(不能作为内建模块使用) +并且启动启用了 kmemleak 的内核。加载模块并执行一次扫描:: + + # modprobe kmemleak-test + # echo scan > /sys/kernel/debug/kmemleak + +注意你可能无法立刻或在第一次扫描后得到结果。当 kmemleak 得到结果,将会输出日 +志 ``kmemleak: <count of leaks> new suspected memory leaks`` 。然后通过读取文件 +获取信息:: + + # cat /sys/kernel/debug/kmemleak + unreferenced object 0xffff89862ca702e8 (size 32): + comm "modprobe", pid 2088, jiffies 4294680594 (age 375.486s) + hex dump (first 32 bytes): + 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. + backtrace: + [<00000000e0a73ec7>] 0xffffffffc01d2036 + [<000000000c5d2a46>] do_one_initcall+0x41/0x1df + [<0000000046db7e0a>] do_init_module+0x55/0x200 + [<00000000542b9814>] load_module+0x203c/0x2480 + [<00000000c2850256>] __do_sys_finit_module+0xba/0xe0 + [<000000006564e7ef>] do_syscall_64+0x43/0x110 + [<000000007c873fa6>] entry_SYSCALL_64_after_hwframe+0x44/0xa9 + ... + +用 ``rmmod kmemleak_test`` 移除模块时也会触发 +kmemleak 的结果输出。 diff --git a/Documentation/translations/zh_CN/dev-tools/ubsan.rst b/Documentation/translations/zh_CN/dev-tools/ubsan.rst new file mode 100644 index 000000000000..2487696b3772 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/ubsan.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/ubsan.rst +:Translator: Dongliang Mu <dzm91@hust.edu.cn> + +未定义行为消毒剂 - UBSAN +==================================== + +UBSAN是一种动态未定义行为检查工具。 + +UBSAN使用编译时插桩捕捉未定义行为。编译器在可能导致未定义行为的操作前插入特定 +检测代码。如果检查失败,即检测到未定义行为,__ubsan_handle_* 函数将被调用打印 +错误信息。 + +GCC自4.9.x [1_] (详见 ``-fsanitize=undefined`` 选项及其子选项)版本后引入这 +一特性。GCC 5.x 版本实现了更多检查器 [2_]。 + +报告样例 +-------------- + +:: + + ================================================================================ + UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 + shift exponent 32 is to large for 32-bit type 'unsigned int' + CPU: 0 PID: 0 Comm: swapper Not tainted 4.4.0-rc1+ #26 + 0000000000000000 ffffffff82403cc8 ffffffff815e6cd6 0000000000000001 + ffffffff82403cf8 ffffffff82403ce0 ffffffff8163a5ed 0000000000000020 + ffffffff82403d78 ffffffff8163ac2b ffffffff815f0001 0000000000000002 + Call Trace: + [<ffffffff815e6cd6>] dump_stack+0x45/0x5f + [<ffffffff8163a5ed>] ubsan_epilogue+0xd/0x40 + [<ffffffff8163ac2b>] __ubsan_handle_shift_out_of_bounds+0xeb/0x130 + [<ffffffff815f0001>] ? radix_tree_gang_lookup_slot+0x51/0x150 + [<ffffffff8173c586>] _mix_pool_bytes+0x1e6/0x480 + [<ffffffff83105653>] ? dmi_walk_early+0x48/0x5c + [<ffffffff8173c881>] add_device_randomness+0x61/0x130 + [<ffffffff83105b35>] ? dmi_save_one_device+0xaa/0xaa + [<ffffffff83105653>] dmi_walk_early+0x48/0x5c + [<ffffffff831066ae>] dmi_scan_machine+0x278/0x4b4 + [<ffffffff8111d58a>] ? vprintk_default+0x1a/0x20 + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830b2240>] setup_arch+0x405/0xc2c + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830ae053>] start_kernel+0x83/0x49a + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830ad386>] x86_64_start_reservations+0x2a/0x2c + [<ffffffff830ad4f3>] x86_64_start_kernel+0x16b/0x17a + ================================================================================ + +用法 +----- + +使用如下内核配置启用UBSAN:: + + CONFIG_UBSAN=y + +使用如下内核配置检查整个内核:: + + CONFIG_UBSAN_SANITIZE_ALL=y + +为了在特定文件或目录启动代码插桩,需要在相应的内核Makefile中添加一行类似内容: + +- 单文件(如main.o):: + + UBSAN_SANITIZE_main.o := y + +- 一个目录中的所有文件:: + + UBSAN_SANITIZE := y + +即使设置了``CONFIG_UBSAN_SANITIZE_ALL=y``,为了避免文件被插桩,可使用:: + + UBSAN_SANITIZE_main.o := n + +与:: + + UBSAN_SANITIZE := n + +未对齐的内存访问检测可通过开启独立选项 - CONFIG_UBSAN_ALIGNMENT 检测。 +该选项在支持未对齐访问的架构上(CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS=y) +默认为关闭。该选项仍可通过内核配置启用,但它将产生大量的UBSAN报告。 + +参考文献 +---------- + +.. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html +.. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html +.. _3: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 6ccec9657cc6..20b9d4270d1f 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -24,8 +24,8 @@ 上的linux-doc邮件列表。 顺便说下,中文文档也需要遵守内核编码风格,风格中中文和英文的主要不同就是中文 -的字符标点占用两个英文字符宽度, 所以,当英文要求不要超过每行100个字符时, -中文就不要超过50个字符。另外,也要注意'-','=' 等符号与相关标题的对齐。在将 +的字符标点占用两个英文字符宽度,所以,当英文要求不要超过每行100个字符时, +中文就不要超过50个字符。另外,也要注意'-','='等符号与相关标题的对齐。在将 补丁提交到社区之前,一定要进行必要的 ``checkpatch.pl`` 检查和编译测试。 与Linux 内核社区一起工作 diff --git a/Documentation/translations/zh_CN/process/cve.rst b/Documentation/translations/zh_CN/process/cve.rst new file mode 100644 index 000000000000..e39b796efcec --- /dev/null +++ b/Documentation/translations/zh_CN/process/cve.rst @@ -0,0 +1,89 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/process/cve.rst +:Translator: Dongliang Mu <dzm91@hust.edu.cn> + +==== +CVEs +==== + +Common Vulnerabilities and Exposure (CVE®) 编号是一种明确的方式来 +识别、定义和登记公开披露的安全漏洞。随着时间的推移,它们在内核项目中的实用性 +已经下降,CVE编号经常以不适当的方式和不适当的原因被分配。因此,内核开发社区 +倾向于避免使用它们。然而,分配CVE与其他形式的安全标识符的持续压力,以及内核 +社区之外的个人和公司的持续滥用,已经清楚地表明内核社区应该控制这些CVE分配。 + +Linux内核开发团队确实有能力为潜在的Linux内核安全问题分配CVE。CVE的分配 +独立于 :doc:`安全漏洞报送流程</process/security-bugs>`。 + +所有分配给Linux内核的CVE列表都可以在linux-cve邮件列表的存档中找到,如 +https://lore.kernel.org/linux-cve-announce/ 所示。如果想获得已分配 +CVE的通知,请“订阅”该邮件列表。要获得分配的CVE通知,请订阅该邮件列表: +`订阅 <https://subspace.kernel.org/subscribing.html>`_。 + +过程 +======= + +作为正常稳定发布过程的一部分,可能存在安全问题的内核更改由负责CVE编号分配 +的开发人员识别,并自动为其分配CVE编号。这些CVE分配会作为经常性的通告经常 +发布在linux-cve-announce邮件列表上。 + +注意,由于Linux内核在系统中的特殊地位,几乎任何漏洞都可能被利用来危害内核 +的安全性,但是当漏洞被修复后,利用的可能性通常不明显。因此,CVE分配团队过于 +谨慎,并将CVE编号分配给他们识别的任何漏洞修复。这就解释了为什么Linux内核 +团队会发布大量的CVE。 + +如果CVE分配团队错过了任何用户认为应该分配CVE的特定修复,请发送电子邮件到 +<cve@kernel.org>,那里的团队将与您一起工作。请注意,任何潜在的安全问题 +不应被发送到此邮箱,它仅用于为已发布的内核树中的漏洞修复分配CVE。如果你觉得 +自己发现了一个未修复的安全问题,请按照 :doc:`安全漏洞报送流程 +</process/security-bugs>` 发送到Linux内核社区。 + +Linux内核不会给未修复的安全问题自动分配CVE;只有在安全修复可用且应用于 +稳定内核树后,CVE分配才会自动发生,并且它将通过安全修复的Git提交编号进行 +跟踪。如果有人希望在提交安全修复之前分配CVE,请联系内核CVE分配团队,从 +他们的一批保留编号中获得相应的CVE编号。 + +对于目前没有得到稳定与长期维护内核团队积极支持的内核版本中发现的任何问题, +都不会分配CVEs。当前支持的内核分支列表可以在 https://kernel.org/releases.html +上找到。 + +被分配CVE的争论 +========================= + +对于为特定内核修改分配的CVE,其争论或修改的权限仅属于受影响子系统的维护者。 +这一原则确保了漏洞报告的高度准确性和可问责性。只有那些具有深厚专业知识和 +对子系统深入了解的维护人员,才能有效评估内核漏洞的有效性和范围,并确定其适当的 +CVE指定策略。在此指定权限之外,任何争论或修改CVE的尝试都可能导致混乱、 +不准确的报告,并最终危及系统。 + +无效的CVE +============ + +如果发现的安全问题存在于仅由某Linux发行版支持的Linux内核中,即安全问题是 +由于Linux发行版所做的更改导致,或者Linux的发行版内核版本不再是Linux内核 +社区支持的内核版本,那么Linux内核CVE团队将不能分配CVE,必须从Linux +发行版本身请求。 + +内核CVE分配团队以外的任何团队对Linux内核支持版本分配的CVE都不应被 +视为有效CVE。请通知内核CVE分配团队,以便他们可以通过CNA修复措施使 +这些条目失效。 + +特定CVE的适用性 +============================== + +由于Linux内核可以以许多不同方式使用,外部用户可以通过许多不同方式访问它,或者 +根本没有访问,因此任何特定CVE的适用性取决于Linux用户,而不是内核CVE分配团队。 +请不要与我们联系来尝试确定任何特定CVE的适用性。 + +此外,由于源代码树非常大,而任何一个系统都只使用源代码树的一小部分,因此任何 +Linux用户都应该意识到,大量分配的CVEs与他们的系统无关。 + +简而言之,我们不知道您的用例,也不知道您使用的是内核的哪个部分,因此我们无法 +确定特定的CVE是否与您的系统相关。 + +与往常一样,最好采用所有发布的内核更改,因为它们是由许多社区成员在一个统一的 +整体中一起进行测试的,而不是作为个别的精选更改。还要注意,对于许多安全问题来 +说,整体问题的解决方案并不是在单个更改中找到的,而是在彼此之上的许多修复的总 +和。理想情况下,CVE将被分配给所有问题的所有修复,但有时我们将无法注意到一些 +修复,因此某些修复可能在没有CVE的情况下被采取。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 3ca02d281be0..5c6c8ccdd50d 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -48,6 +48,7 @@ TODOLIST: :maxdepth: 1 embargoed-hardware-issues + cve TODOLIST: diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index f8978f02057c..7864107e60a8 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -333,10 +333,10 @@ Linus 和其他的内核开发者需要阅读和评论你提交的改动。对 未参与其开发。签署链应当反映补丁传播到维护者并最终传播到Linus所经过的 **真实** 路径,首个签署指明单个作者的主要作者身份。 -何时使用Acked-by:,CC:,和Co-Developed by: +何时使用Acked-by:,Cc:,和Co-developed-by: ------------------------------------------ -Singed-off-by: 标签表示签名者参与了补丁的开发,或者他/她在补丁的传递路径中。 +Signed-off-by: 标签表示签名者参与了补丁的开发,或者他/她在补丁的传递路径中。 如果一个人没有直接参与补丁的准备或处理,但希望表示并记录他们对补丁的批准/赞成, 那么他们可以要求在补丁的变更日志中添加一个Acked-by:。 @@ -358,8 +358,8 @@ Acked-by:不一定表示对整个补丁的确认。例如,如果一个补丁 Co-developed-by: 声明补丁是由多个开发人员共同创建的;当几个人在一个补丁上工 作时,它用于给出共同作者(除了From:所给出的作者之外)。因为Co-developed-by: 表示作者身份,所以每个Co-developed-by:必须紧跟在相关合作作者的签署之后。标准 -签署程序要求Singed-off-by:标签的顺序应尽可能反映补丁的时间历史,无论作者是通 -过From:还是Co-developed-by:表明。值得注意的是,最后一个Singed-off-by:必须是 +签署程序要求Signed-off-by:标签的顺序应尽可能反映补丁的时间历史,无论作者是通 +过From:还是Co-developed-by:表明。值得注意的是,最后一个Signed-off-by:必须是 提交补丁的开发人员。 注意,如果From:作者也是电子邮件标题的From:行中列出的人,则From:标签是可选的。 diff --git a/Documentation/translations/zh_CN/rust/arch-support.rst b/Documentation/translations/zh_CN/rust/arch-support.rst index afbd02afec45..abd708d48f82 100644 --- a/Documentation/translations/zh_CN/rust/arch-support.rst +++ b/Documentation/translations/zh_CN/rust/arch-support.rst @@ -16,8 +16,12 @@ 下面是目前可以工作的架构的一般总结。支持程度与 ``MAINTAINERS`` 文件中的``S`` 值相对应: -============ ================ ============================================== -架构 支持水平 限制因素 -============ ================ ============================================== -``x86`` Maintained 只有 ``x86_64`` -============ ================ ============================================== +============= ================ ============================================== +架构 支持水平 限制因素 +============= ================ ============================================== +``arm64`` Maintained 只有小端序 +``loongarch`` Maintained \- +``riscv`` Maintained 只有 ``riscv64`` +``um`` Maintained 只有 ``x86_64`` +``x86`` Maintained 只有 ``x86_64`` +============= ================ ============================================== diff --git a/Documentation/translations/zh_CN/rust/coding-guidelines.rst b/Documentation/translations/zh_CN/rust/coding-guidelines.rst index 6c0bdbbc5a2a..419143b938ed 100644 --- a/Documentation/translations/zh_CN/rust/coding-guidelines.rst +++ b/Documentation/translations/zh_CN/rust/coding-guidelines.rst @@ -157,6 +157,18 @@ https://commonmark.org/help/ https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html +此外,内核支持通过在链接目标前添加 ``srctree/`` 来创建相对于源代码树的链接。例如: + +.. code-block:: rust + + //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h) + +或者: + +.. code-block:: rust + + /// [`struct mutex`]: srctree/include/linux/mutex.h + 命名 ---- diff --git a/Documentation/translations/zh_CN/rust/general-information.rst b/Documentation/translations/zh_CN/rust/general-information.rst index 6b91dfe1834a..251f6ee2bb44 100644 --- a/Documentation/translations/zh_CN/rust/general-information.rst +++ b/Documentation/translations/zh_CN/rust/general-information.rst @@ -32,7 +32,7 @@ Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。 要在你的网络浏览器中本地阅读该文档,请运行如:: - xdg-open rust/doc/kernel/index.html + xdg-open Documentation/output/rust/rustdoc/kernel/index.html 要了解如何编写文档,请看 coding-guidelines.rst 。 diff --git a/Documentation/translations/zh_CN/rust/quick-start.rst b/Documentation/translations/zh_CN/rust/quick-start.rst index a4b8e8a50a89..8616556ae4d7 100644 --- a/Documentation/translations/zh_CN/rust/quick-start.rst +++ b/Documentation/translations/zh_CN/rust/quick-start.rst @@ -37,13 +37,18 @@ rustc 需要一个特定版本的Rust编译器。较新的版本可能会也可能不会工作,因为就目前而言,内核依赖 于一些不稳定的Rust特性。 -如果使用的是 ``rustup`` ,请进入检出的源代码目录并运行:: +如果使用的是 ``rustup`` ,请进入内核编译目录(或者用 ``--path=<build-dir>`` 参数 +来 ``设置`` sub-command)并运行:: rustup override set $(scripts/min-tool-version.sh rustc) -或者从以下网址获取一个独立的安装程序或安装 ``rustup`` : ++这将配置你的工作目录使用正确版本的 ``rustc``,而不影响你的默认工具链。 - https://www.rust-lang.org +请注意覆盖应用当前的工作目录(和它的子目录)。 + +如果你使用 ``rustup``, 可以从下面的链接拉取一个单独的安装程序: + + https://forge.rust-lang.org/infra/other-installation-methods.html#standalone Rust标准库源代码 @@ -57,21 +62,23 @@ Rust标准库的源代码是必需的,因为构建系统会交叉编译 ``core 这些组件是按工具链安装的,因此以后升级Rust编译器版本需要重新添加组件。 -否则,如果使用独立的安装程序,可以将Rust仓库克隆到工具链的安装文件夹中:: +否则,如果使用独立的安装程序,可以将Rust源码树下载到安装工具链的文件夹中:: - git clone --recurse-submodules \ - --branch $(scripts/min-tool-version.sh rustc) \ - https://github.com/rust-lang/rust \ - $(rustc --print sysroot)/lib/rustlib/src/rust + curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" | + tar -xzf - -C "$(rustc --print sysroot)/lib" \ + "rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \ + --strip-components=3 -在这种情况下,以后升级Rust编译器版本需要手动更新这个克隆的仓库。 +在这种情况下,以后升级Rust编译器版本需要手动更新这个源代码树(这可以通过移除 +``$(rustc --print sysroot)/lib/rustlib/src/rust`` ,然后重新执行上 +面的命令做到)。 libclang ******** ``bindgen`` 使用 ``libclang`` (LLVM的一部分)来理解内核中的C代码,这意味着需要安 -装LLVM;同在开启 ``CC=clang`` 或 ``LLVM=1`` 时编译内核一样。 +装LLVM;同在开启``LLVM=1`` 时编译内核一样。 Linux发行版中可能会有合适的包,所以最好先检查一下。 @@ -94,7 +101,20 @@ bindgen 通过以下方式安装它(注意,这将从源码下载并构建该工具):: - cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen + cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli + +``bindgen`` 需要找到合适的 ``libclang`` 才能工作。如果没有找到(或者找到的 +``libclang`` 与应该使用的 ``libclang`` 不同),则可以使用 ``clang-sys`` +理解的环境变量(Rust绑定创建的 ``bindgen`` 用来访问 ``libclang``): + + +* ``LLVM_CONFIG_PATH`` 可以指向一个 ``llvm-config`` 可执行文件。 + +* 或者 ``LIBCLANG_PATH`` 可以指向 ``libclang`` 共享库或包含它的目录。 + +* 或者 ``CLANG_PATH`` 可以指向 ``clang`` 可执行文件。 + +详情请参阅 ``clang-sys`` 的文档: 开发依赖 @@ -163,7 +183,9 @@ rust-analyzer 一起使用,以实现语法高亮、补全、转到定义和其他功能。 ``rust-analyzer`` 需要一个配置文件, ``rust-project.json``, 它可以由 ``rust-analyzer`` -Make 目标生成。 +Make 目标生成:: + + make LLVM=1 rust-analyzer 配置 @@ -189,10 +211,6 @@ Rust支持(CONFIG_RUST)需要在 ``General setup`` 菜单中启用。在其 make LLVM=1 -对于不支持完整LLVM工具链的架构,使用:: - - make CC=clang - 使用GCC对某些配置也是可行的,但目前它是非常试验性的。 diff --git a/Documentation/translations/zh_TW/process/submit-checklist.rst b/Documentation/translations/zh_TW/process/submit-checklist.rst index 43f2e3c5b514..0ecb187753e4 100644 --- a/Documentation/translations/zh_TW/process/submit-checklist.rst +++ b/Documentation/translations/zh_TW/process/submit-checklist.rst @@ -31,7 +31,7 @@ Linux內核補丁提交檢查單 c) 使用 ``O=builddir`` 時可以成功編譯 - d) 任何 Doucmentation/ 下的變更都能成功構建且不引入新警告/錯誤。 + d) 任何 Documentation/ 下的變更都能成功構建且不引入新警告/錯誤。 用 ``make htmldocs`` 或 ``make pdfdocs`` 檢驗構建情況並修復問題。 3) 通過使用本地交叉編譯工具或其他一些構建設施在多個CPU體系結構上構建。 diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index 99fa0f2fe6f4..f12f2f193f85 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -334,10 +334,10 @@ Linus 和其他的內核開發者需要閱讀和評論你提交的改動。對 未參與其開發。簽署鏈應當反映補丁傳播到維護者並最終傳播到Linus所經過的 **真實** 路徑,首個簽署指明單個作者的主要作者身份。 -何時使用Acked-by:,CC:,和Co-Developed by: +何時使用Acked-by:,Cc:,和Co-developed-by: ------------------------------------------ -Singed-off-by: 標籤表示簽名者參與了補丁的開發,或者他/她在補丁的傳遞路徑中。 +Signed-off-by: 標籤表示簽名者參與了補丁的開發,或者他/她在補丁的傳遞路徑中。 如果一個人沒有直接參與補丁的準備或處理,但希望表示並記錄他們對補丁的批准/贊成, 那麼他們可以要求在補丁的變更日誌中添加一個Acked-by:。 @@ -359,8 +359,8 @@ Acked-by:不一定表示對整個補丁的確認。例如,如果一個補丁 Co-developed-by: 聲明補丁是由多個開發人員共同創建的;當幾個人在一個補丁上工 作時,它用於給出共同作者(除了From:所給出的作者之外)。因爲Co-developed-by: 表示作者身份,所以每個Co-developed-by:必須緊跟在相關合作作者的簽署之後。標準 -簽署程序要求Singed-off-by:標籤的順序應儘可能反映補丁的時間歷史,無論作者是通 -過From:還是Co-developed-by:表明。值得注意的是,最後一個Singed-off-by:必須是 +簽署程序要求Signed-off-by:標籤的順序應儘可能反映補丁的時間歷史,無論作者是通 +過From:還是Co-developed-by:表明。值得注意的是,最後一個Signed-off-by:必須是 提交補丁的開發人員。 注意,如果From:作者也是電子郵件標題的From:行中列出的人,則From:標籤是可選的。 diff --git a/Documentation/virt/kvm/x86/amd-memory-encryption.rst b/Documentation/virt/kvm/x86/amd-memory-encryption.rst index 995780088eb2..84335d119ff1 100644 --- a/Documentation/virt/kvm/x86/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/x86/amd-memory-encryption.rst @@ -46,21 +46,16 @@ SEV hardware uses ASIDs to associate a memory encryption key with a VM. Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value defined in the CPUID 0x8000001f[ecx] field. -SEV Key Management -================== +The KVM_MEMORY_ENCRYPT_OP ioctl +=============================== -The SEV guest key management is handled by a separate processor called the AMD -Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure -key management interface to perform common hypervisor activities such as -encrypting bootstrap code, snapshot, migrating and debugging the guest. For more -information, see the SEV Key Management spec [api-spec]_ - -The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP. If the argument -to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled -and ``ENOTTY`` if it is disabled (on some older versions of Linux, -the ioctl runs normally even with a NULL argument, and therefore will -likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP -must be a struct kvm_sev_cmd:: +The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP, which operates on +the VM file descriptor. If the argument to KVM_MEMORY_ENCRYPT_OP is NULL, +the ioctl returns 0 if SEV is enabled and ``ENOTTY`` if it is disabled +(on some older versions of Linux, the ioctl tries to run normally even +with a NULL argument, and therefore will likely return ``EFAULT`` instead +of zero if SEV is enabled). If non-NULL, the argument to +KVM_MEMORY_ENCRYPT_OP must be a struct kvm_sev_cmd:: struct kvm_sev_cmd { __u32 id; @@ -87,10 +82,6 @@ guests, such as launching, running, snapshotting, migrating and decommissioning. The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform context. In a typical workflow, this command should be the first command issued. -The firmware can be initialized either by using its own non-volatile storage or -the OS can manage the NV storage for the firmware using the module parameter -``init_ex_path``. If the file specified by ``init_ex_path`` does not exist or -is invalid, the OS will create or override the file with output from PSP. Returns: 0 on success, -negative on error @@ -434,6 +425,21 @@ issued by the hypervisor to make the guest ready for execution. Returns: 0 on success, -negative on error +Firmware Management +=================== + +The SEV guest key management is handled by a separate processor called the AMD +Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure +key management interface to perform common hypervisor activities such as +encrypting bootstrap code, snapshot, migrating and debugging the guest. For more +information, see the SEV Key Management spec [api-spec]_ + +The AMD-SP firmware can be initialized either by using its own non-volatile +storage or the OS can manage the NV storage for the firmware using +parameter ``init_ex_path`` of the ``ccp`` module. If the file specified +by ``init_ex_path`` does not exist or is invalid, the OS will create or +override the file with PSP non-volatile storage. + References ========== diff --git a/Documentation/virt/kvm/x86/msr.rst b/Documentation/virt/kvm/x86/msr.rst index 9315fc385fb0..3aecf2a70e7b 100644 --- a/Documentation/virt/kvm/x86/msr.rst +++ b/Documentation/virt/kvm/x86/msr.rst @@ -193,8 +193,8 @@ data: Asynchronous page fault (APF) control MSR. Bits 63-6 hold 64-byte aligned physical address of a 64 byte memory area - which must be in guest RAM and must be zeroed. This memory is expected - to hold a copy of the following structure:: + which must be in guest RAM. This memory is expected to hold the + following structure:: struct kvm_vcpu_pv_apf_data { /* Used for 'page not present' events delivered via #PF */ @@ -204,7 +204,6 @@ data: __u32 token; __u8 pad[56]; - __u32 enabled; }; Bits 5-4 of the MSR are reserved and should be zero. Bit 0 is set to 1 @@ -232,14 +231,14 @@ data: as regular page fault, guest must reset 'flags' to '0' before it does something that can generate normal page fault. - Bytes 5-7 of 64 byte memory location ('token') will be written to by the + Bytes 4-7 of 64 byte memory location ('token') will be written to by the hypervisor at the time of APF 'page ready' event injection. The content - of these bytes is a token which was previously delivered as 'page not - present' event. The event indicates the page in now available. Guest is - supposed to write '0' to 'token' when it is done handling 'page ready' - event and to write 1' to MSR_KVM_ASYNC_PF_ACK after clearing the location; - writing to the MSR forces KVM to re-scan its queue and deliver the next - pending notification. + of these bytes is a token which was previously delivered in CR2 as + 'page not present' event. The event indicates the page is now available. + Guest is supposed to write '0' to 'token' when it is done handling + 'page ready' event and to write '1' to MSR_KVM_ASYNC_PF_ACK after + clearing the location; writing to the MSR forces KVM to re-scan its + queue and deliver the next pending notification. Note, MSR_KVM_ASYNC_PF_INT MSR specifying the interrupt vector for 'page ready' APF delivery needs to be written to before enabling APF mechanism |