summaryrefslogtreecommitdiff
AgeCommit message (Collapse)Author
2025-10-17KVM: SVM: Add AVIC support for 4k vCPUs in x2AVIC modeNaveen N Rao
With AVIC support for 4k vCPUs, the maximum supported physical ID in x2AVIC mode is 4095. Since this is no longer fixed, introduce a variable (x2avic_max_physical_id) to capture the maximum supported physical ID on the current platform and use that in place of the existing macro (X2AVIC_MAX_PHYSICAL_ID). With AVIC support for 4k vCPUs, the AVIC Physical ID table is no longer a single page and can occupy up to 8 contiguous 4k pages. Since AVIC hardware accesses of the physical ID table are limited by the physical max index programmed in the VMCB, it is sufficient to allocate only as many pages as are required to have a physical table entry for the max guest APIC ID. Since the guest APIC mode is not available at this point, provision for the maximum possible x2AVIC ID. For this purpose, add a variant of avic_get_max_physical_id() that works with a NULL vCPU pointer and returns the max x2AVIC ID. Wrap this in a new helper for obtaining the allocation order. To make it easy to identify support for 4k vCPUs in x2AVIC mode, update the message printed to the kernel log to print the maximum number of vCPUs supported. Do this on all platforms supporting x2AVIC since it is useful to know what is supported on a specific platform. Co-developed-by: Suravee Suthikulpanit <suravee.suthikulpanit@amd.com> Signed-off-by: Suravee Suthikulpanit <suravee.suthikulpanit@amd.com> Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/7fc5962f6da028f7dd3c79dbbd5c574fa02c99dd.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17x86/cpufeatures: Add X86_FEATURE_X2AVIC_EXTNaveen N Rao
Add CPUID feature bit for x2AVIC extension that enables AMD SVM to support up to 4096 vCPUs in x2AVIC mode. The primary change is in the size of the AVIC Physical ID table, which can now go up to 8 contiguous 4k pages. The number of pages allocated is controlled by the maximum APIC ID for a guest, and that controls the number of pages to allocate for the AVIC Physical ID table. AVIC hardware is enhanced to look up Physical ID table entries for vCPUs > 512 for locating the target APIC backing page and the host APIC ID of the physical core on which the guest vCPU is running. Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Acked-by: Borislav Petkov (AMD) <bp@alien8.de> Link: https://lore.kernel.org/r/e5c9c471ab99a130bf9b728b77050ab308cf8624.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: SVM: Move AVIC Physical ID table allocation to vcpu_precreate()Naveen N Rao
With support for 4k vCPUs in x2AVIC, the size of the AVIC Physical ID table is expanded from a single 4k page to a maximum of 8 contiguous 4k pages. The actual number of pages allocated depends on the maximum possible APIC ID in the guest, which is only known by the time the first vCPU is created. In preparation for supporting a dynamic AVIC Physical ID table size, move its allocation to vcpu_precreate(). Suggested-by: Sean Christopherson <seanjc@google.com> Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/7dc764e0af7f01440bbac3d9215ed174027c2384.1757009416.git.naveen@kernel.org [sean: drop enable_apicv check from svm_vcpu_precreate()] Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: SVM: Expand AVIC_PHYSICAL_MAX_INDEX_MASK to be a 12-bit fieldNaveen N Rao
In the latest APM describing AVIC support for 4k vCPUs, VMCB AVIC_PHYSICAL_MAX_INDEX (Offset 0xF8) and EXITINFO2.Index are both updated from 9-bit wide to 12-bit wide fields unconditionally (i.e., regardless of AVIC support for 4k vCPUs). Expand AVIC_PHYSICAL_MAX_INDEX_MASK accordingly. While AVIC_PHYSICAL_MAX_INDEX_MASK is updated to a 12-bit field, KVM will limit the max vCPU/APIC ID based on the maximum supported on a specific processor and enforce that limit during vCPU creation. I.e., KVM doesn't need to rely on the mask to ensure that the max APIC ID being programmed in the VMCB is in range. The additional bits (11:9) were previously marked reserved and were never set/read by older processors. Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/a24ae953cea716bf9c56c136f7ca4bf5e97b1080.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: SVM: Replace hard-coded value 0x1FF with the corresponding macroNaveen N Rao
The lower 9-bit field in EXITINFO2 represents an index into the AVIC Physical/Logical APIC ID table for a AVIC_INCOMPLETE_IPI #VMEXIT. Since the index into the Logical APIC ID table is just 8 bits, this field is actually bound by the bit-width of the index into the AVIC Physical ID table which is represented by AVIC_PHYSICAL_MAX_INDEX_MASK. So, use that macro to mask EXITINFO2.Index instead of hard coding 0x1FF in avic_incomplete_ipi_interception(). Co-developed-by: Suravee Suthikulpanit <suravee.suthikulpanit@amd.com> Signed-off-by: Suravee Suthikulpanit <suravee.suthikulpanit@amd.com> Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/95795f449c68bffcb3e1789ee2b0b7393711d37d.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: SVM: Add a helper to look up the max physical ID for AVICNaveen N Rao
To help with a future change, add a helper to look up the maximum physical ID depending on the vCPU AVIC mode. No functional change intended. Suggested-by: Sean Christopherson <seanjc@google.com> Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/0ab9bf5e20a3463a4aa3a5ea9bbbac66beedf1d1.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: SVM: Limit AVIC physical max index based on configured max_vcpu_idsNaveen N Rao
KVM allows VMMs to specify the maximum possible APIC ID for a virtual machine through KVM_CAP_MAX_VCPU_ID capability so as to limit data structures related to APIC/x2APIC. Utilize the same to set the AVIC physical max index in the VMCB, similar to VMX. This helps hardware limit the number of entries to be scanned in the physical APIC ID table speeding up IPI broadcasts for virtual machines with smaller number of vCPUs. Unlike VMX, SVM AVIC requires a single page to be allocated for the Physical APIC ID table and the Logical APIC ID table, so retain the existing approach of allocating those during VM init. Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org> Link: https://lore.kernel.org/r/adb07ccdb3394cd79cb372ba6bcc69a4e4d4ef54.1757009416.git.naveen@kernel.org Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Add an off-by-default module param to WARN on missed consistency ↵Sean Christopherson
checks Add an off-by-default param, "warn_on_missed_cc", to have KVM WARN on a missed VMX Consistency Check on nested VM-Enter, specifically so that KVM developers and maintainers can more easily detect missing checks. KVM's goal/intent is that KVM detect *all* VM-Fail conditions in software, as relying on hardware leads to false passes when KVM's nested support is a subset of hardware support, e.g. see commit 095686e6fcb4 ("KVM: nVMX: Check vmcs12->guest_ia32_debugctl on nested VM-Enter"). With one notable exception, KVM now detects all VM-Fail scenarios for which there is known test coverage, i.e. KVM developers can enable the param and expect a clean run, and thus can use the param to detect missed checks, e.g. when enabling new features, when writing new tests, etc. The one exception is an unfortunate consistency check on vTPR. Because the vTPR for L2 comes from the virtual APIC page provided by L1, L2's vTPR is fully writable at all times, i.e. is inherently subject to TOCTOU issues with respect to checks in software versus consumption in hardware. Further complicating matters is KVM's deferred handling of vmcs12 pages when loading nested state; KVM flat out cannot check vTPR during KVM_SET_NESTED_STATE without breaking setups that do on-demand paging, e.g. for live migration and/or live update. To fudge around the vTPR issue, add a "late" controls check for vTPR and also treat an invalid virtual APIC as VM-Fail, but gate the check on warn_on_missed_cc being enabled to avoid unwanted false positives, i.e. to avoid breaking KVM in production. Cc: Jim Mattson <jmattson@google.com> Link: https://lore.kernel.org/r/20250919005955.1366256-10-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Remove support for "early" consistency checks via hardwareSean Christopherson
Remove nested_early_check and all associated code, as it's quite obviously not being used or tested (it's been broken for 4+ years without a single bug report). More importantly, KVM's software-based consistency checks have matured since the option to do hardware-based checks was added; KVM appears to be missing only _one_ consistency check, on vTPR. And even *more* importantly, that consistency check can't be prevented by an early hardware check due to L1 being able to modify the virtual APIC at any time, i.e. there's an inherent TOCTOU flaw that could cause KVM to "miss" a consistency check VM-Fail, regardless of whether the check is performed by software or by hardware. In other words, KVM _must_ be able to unwind from a late VM-Fail (which was a big motivation for doing early checks). I.e. now that KVM provides (almost) all necessary consistency checks, what's really needed is a way to detect missing checks in KVM, not a way to avoid having to unwind from a late VM-Fail. And that can be done much more simply, e.g. by an simple module param to guard a WARN (which, sadly, must be off-by-default to avoid splats due to the aforementioned TOCTOU issue). For all intents and purposes, this reverts commit 52017608da33 ("KVM: nVMX: add option to perform early consistency checks via H/W"). Link: https://lore.kernel.org/r/20250919005955.1366256-9-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Stuff vmcs02.TSC_MULTIPLIER early on for nested early checksSean Christopherson
If KVM is doing "early" nested VM-Enter consistency checks and TSC scaling is supported, stuff vmcs02's TSC Multiplier early on to avoid getting a false positive VM-Fail due to trying to do VM-Enter with TSC_MULTIPLIER=0. To minimize complexity around L1 vs. L2 TSC, KVM sets the actual TSC Multiplier rather late during VM-Entry, i.e. may have '0' at the time of early consistency checks. If vmcs12 has TSC Scaling enabled, use the multiplier from vmcs12 so that nested early checks actually check vmcs12 state, otherwise throw in an arbitrary value of '1' (anything non-zero is legal). Fixes: d041b5ea9335 ("KVM: nVMX: Enable nested TSC scaling") Link: https://lore.kernel.org/r/20250919005955.1366256-8-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Add consistency check for TSC_MULTIPLIER=0Sean Christopherson
Add a missing consistency check on the TSC Multiplier being '0'. Per the SDM: If the "use TSC scaling" VM-execution control is 1, the TSC-multiplier must not be zero. Fixes: d041b5ea9335 ("KVM: nVMX: Enable nested TSC scaling") Link: https://lore.kernel.org/r/20250919005955.1366256-7-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Add consistency check for TPR_THRESHOLD[31:4]!=0 without VIDSean Christopherson
Add a missing consistency check on the TPR Threshold. Per the SDM If the "use TPR shadow" VM-execution control is 1 and the "virtual- interrupt delivery" VM-execution control is 0, bits 31:4 of the TPR threshold VM-execution control field must be 0. Note, nested_vmx_check_tpr_shadow_controls() bails early if "use TPR shadow" is 0. Link: https://lore.kernel.org/r/20250919005955.1366256-6-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: VMX: Use kvm_mmu_page role to construct EPTP, not current vCPU stateSean Christopherson
Use the role for the to-be-loaded/invalidated EPT root to compute the root's level and A/D enablement instead of pulling the information from the vCPU (e.g. by passing in the root level and querying vmcs12). Not making unnecessary assumptions about the root will allow invalidating arbitrary EPT roots (which sadly requires a full EPTP) at any given time. No functional change intended (the end result should be the same). Link: https://lore.kernel.org/r/20250919005955.1366256-5-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: x86/mmu: Move "dummy root" helpers to spte.hSean Christopherson
Move the helpers to get/query a dummy root from mmu_internal.h to spte.h so that VMX can detect and handle dummy roots when constructing EPTPs. This will allow using the root's role to build the EPTP instead of pulling equivalent information out of the vCPU structure. No functional change intended. Link: https://lore.kernel.org/r/20250919005955.1366256-4-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: nVMX: Hardcode dummy EPTP used for early nested consistency checksSean Christopherson
Hardcode the dummy EPTP used for "early" consistency checks as there's no need to use 5-level EPT based on the guest.MAXPHYADDR (the EPTP just needs to be valid, it's never truly consumed). This will allow breaking construct_eptp()'s dependency on having access to the vCPU, which in turn will (much further in the future) allow for eliding per-root TLB flushes when a vCPU is migrated between pCPUs (a flush is need if and only if that particular pCPU hasn't already flushed the vCPU's roots). Link: https://lore.kernel.org/r/20250919005955.1366256-3-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17KVM: VMX: Hoist construct_eptp() "up" in vmx.cSean Christopherson
Move construct_eptp() further up in vmx.c so that it's above vmx_flush_tlb_current(), its "first" user in vmx.c. This will allow a future patch to opportunistically make construct_eptp() local to vmx.c. No functional change intended. Link: https://lore.kernel.org/r/20250919005955.1366256-2-seanjc@google.com Signed-off-by: Sean Christopherson <seanjc@google.com>
2025-10-17arm64: dts: qcom: ipq5424: correct the TF-A reserved memory to 512KKathiravan Thirumoorthy
Correct the reserved memory size for TF-A to 512K, as it was mistakenly marked as 500K. Update the reserved memory node accordingly. Fixes: 8517204c982b ("arm64: dts: qcom: ipq5424: Add reserved memory for TF-A") Signed-off-by: Kathiravan Thirumoorthy <kathiravan.thirumoorthy@oss.qualcomm.com> Link: https://lore.kernel.org/r/20251014-tfa-reserved-mem-v1-1-48c82033c8a7@oss.qualcomm.com Signed-off-by: Bjorn Andersson <andersson@kernel.org>
2025-10-17soc: qcom: pd-mapper: Add Kaanapali compatiblePrasad Kumpatla
Add support for the Qualcomm Kaanapali SoC to the protection domain mapper. Kaanapali shares the same protection domain configuration as SM8550, except charger_pd as it move to SoCCP. Signed-off-by: Jingyi Wang <jingyi.wang@oss.qualcomm.com> Signed-off-by: Prasad Kumpatla <prasad.kumpatla@oss.qualcomm.com> Reviewed-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com> Link: https://lore.kernel.org/r/20251014-knp-pdmapper-v2-v2-1-ba44422ac503@oss.qualcomm.com Signed-off-by: Bjorn Andersson <andersson@kernel.org>
2025-10-17clk: qcom: gcc-x1e80100: Add missing USB4 clocks/resetsKonrad Dybcio
Currently, some of the USB4 clocks/resets are described, but not all of the back-end muxes are present. Configuring them properly is necessary for proper operation of the hardware. Add all the resets & muxes and wire up any unaccounted USB4 clock paths. Fixes: 161b7c401f4b ("clk: qcom: Add Global Clock controller (GCC) driver for X1E80100") Reviewed-by: Bryan O'Donoghue <bod@kernel.org> Signed-off-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com> Reviewed-by: Taniya Das <taniya.das@oss.qualcomm.com> Reviewed-by: Abel Vesa <abel.vesa@linaro.org> Reviewed-by: Dmitry Baryshkov <dmitry.baryshkov@oss.qualcomm.com> Link: https://lore.kernel.org/r/20251003-topic-hamoa_gcc_usb4-v2-2-61d27a14ee65@oss.qualcomm.com Signed-off-by: Bjorn Andersson <andersson@kernel.org>
2025-10-17Merge branch ↵Bjorn Andersson
'20251003-topic-hamoa_gcc_usb4-v2-1-61d27a14ee65@oss.qualcomm.com' into clk-for-6.19 Merge the addition of missing USB4 clocks and resets in the Hamoa global clock controller binding, to allow sharing them with the DeviceTree branch.
2025-10-17dt-bindings: clock: qcom,x1e80100-gcc: Add missing USB4 clocks/resetsKonrad Dybcio
Some of the USB4 muxes, RCGs and resets were not initially described. Add indices for them to allow extending the driver. Acked-by: Rob Herring (Arm) <robh@kernel.org> Reviewed-by: Bryan O'Donoghue <bod@kernel.org> Signed-off-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com> Link: https://lore.kernel.org/r/20251003-topic-hamoa_gcc_usb4-v2-1-61d27a14ee65@oss.qualcomm.com Signed-off-by: Bjorn Andersson <andersson@kernel.org>
2025-10-17rust: device: fix device context of Device::parent()Danilo Krummrich
Regardless of the DeviceContext of a device, we can't give any guarantees about the DeviceContext of its parent device. This is very subtle, since it's only caused by a simple typo, i.e. Self::from_raw(parent) which preserves the DeviceContext in this case, vs. Device::from_raw(parent) which discards the DeviceContext. (I should have noticed it doing the correct thing in auxiliary::Device subsequently, but somehow missed it.) Hence, fix both Device::parent() and auxiliary::Device::parent(). Cc: stable@vger.kernel.org Fixes: a4c9f71e3440 ("rust: device: implement Device::parent()") Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Alexandre Courbot <acourbot@nvidia.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
2025-10-17Documentation/rtla: rename common_xxx.rst files to common_xxx.txtGopi Krishna Menon
Sphinx reports htmldocs errors: Documentation/tools/rtla/common_options.rst:58: ERROR: Undefined substitution referenced: "threshold". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tool". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "thresharg". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tracer". Documentation/tools/rtla/common_options.rst:92: ERROR: Undefined substitution referenced: "tracer". Documentation/tools/rtla/common_options.rst:98: ERROR: Undefined substitution referenced: "actionsperf". Documentation/tools/rtla/common_options.rst:113: ERROR: Undefined substitution referenced: "tool". common_*.rst files are snippets that are intended to be included by rtla docs (rtla*.rst). common_options.rst in particular contains substitutions which depend on other common_* includes, so building it independently as reST source results in above errors. Rename all common_*.rst files to common_*.txt to prevent Sphinx from building these snippets as standalone reST source and update all include references accordingly. Link: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions Suggested-by: Tomas Glozar <tglozar@redhat.com> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com> Reviewed-by: Tomas Glozar <tglozar@redhat.com> Fixes: 05b7e10687c6 ("tools/rtla: Add remaining support for osnoise actions") Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20251008184522.13201-1-krishnagopi487@gmail.com [Bagas: massage commit message and apply trailers] Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013092719.30780-2-bagasdotme@gmail.com>
2025-10-17Documentation: assoc_array: Format internal tree layout tablesBagas Sanjaya
Format tables in "Basic internal tree layout" as reST tables. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013095630.34235-4-bagasdotme@gmail.com>
2025-10-17Documentation: assoc_array: Indent function explanation textBagas Sanjaya
Paragraphs of function explanation are currently not indented following their appropriate numbered list item, which causes only the first paragraph and function prototype code blocks to be indented in the numbered list in htmldocs output. Indent the explanation. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013095630.34235-3-bagasdotme@gmail.com>
2025-10-17docs: admin-guide: Fix a typo in kernel-parameters.txtYohei Kojima
Fix a typo in the stacktrace parameter description in kernel-parameters.txt Signed-off-by: Yohei Kojima <Yohei.Kojima@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <edda15e3fcae13265278d3c3bd93ab077345d78f.1760498951.git.Yohei.Kojima@sony.com>
2025-10-17Merge branch 'build-script' into docs-mwJonathan Corbet
Quoth Mauro: This series should probably be called: "Move the trick-or-treat build hacks accumulated over time into a single place and document them." as this reflects its main goal. As such: - it places the jobserver logic on a library; - it removes sphinx/parallel-wrapper.sh; - the code now properly implements a jobserver-aware logic to do the parallelism when called via GNU make, failing back to "-j" when there's no jobserver; - converts check-variable-fonts.sh to Python and uses it via function call; - drops an extra script to generate man pages, adding a makefile target for it; - ensures that return code is 0 when PDF successfully builds; - about half of the script is comments and documentation. I tried to do my best to document all tricks that are inside the script. This way, the docs build steps is now documented. It should be noticed that it is out of the scope of this series to change the implementation. Surely the process can be improved, but first let's consolidate and document everything on a single place. Such script was written in a way that it can be called either directly or via a Makefile. Running outside Makefile is interesting specially when debug is needed. The command line interface replaces the need of having lots of env vars before calling sphinx-build: $ ./tools/docs/sphinx-build-wrapper --help usage: sphinx-build-wrapper [-h] [--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]] [--conf CONF] [--builddir BUILDDIR] [--theme THEME] [--css CSS] [--paper {,a4,letter}] [-v] [-j JOBS] [-i] [-V [VENV]] {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Kernel documentation builder positional arguments: {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Documentation target to build options: -h, --help show this help message and exit --sphinxdirs SPHINXDIRS [SPHINXDIRS ...] Specific directories to build --conf CONF Sphinx configuration file --builddir BUILDDIR Sphinx configuration file --theme THEME Sphinx theme to use --css CSS Custom CSS file for HTML/EPUB --paper {,a4,letter} Paper size for LaTeX/PDF output -v, --verbose place build in verbose mode -j, --jobs JOBS Sets number of jobs to use with sphinx-build -i, --interactive Change latex default to run in interactive mode -V, --venv [VENV] If used, run Sphinx from a venv dir (default dir: sphinx_latest) the only mandatory argument is the target, which is identical with "make" targets. The call inside Makefile doesn't use the last four arguments. They're there to help identifying problems at the build: -v makes the output verbose; -j helps to test parallelism; -i runs latexmk in interactive mode, allowing to debug PDF build issues; -V is useful when testing it with different venvs. When used with GNU make (or some other make which implements jobserver), a call like: make -j <targets> htmldocs will make the wrapper to automatically use POSIX jobserver to claim the number of available job slots, calling sphinx-build with a "-j" parameter reflecting it. ON such case, the default can be overriden via SPHINXDIRS argument. Visiable changes when compared with the old behavior: When V=0, the only visible difference is that: - pdfdocs target now returns 0 on success, 1 on failures. This addresses an issue over the current process where we it always return success even on failures; - it will now print the name of PDF files that failed to build, if any. In verbose mode, sphinx-build-wrapper and sphinx-build command lines are now displayed.
2025-10-17Merge branch 'media-uapi' into docs-mwJonathan Corbet
Mauro says: In the past, media used Docbook to generate documentation, together with some logic to ensure that cross-references would match the actual defined uAPI. The rationale is that we wanted to automatically check for uAPI documentation gaps. The same logic was migrated to Sphinx. Back then, broken links were reported. However, recent versions of it and/or changes at conf.py disabled such checks. The result is that several symbols are now not cross-referenced, and we don't get warnings anymore when something breaks. This series consist on 2 parts: Part 1: extra patches to parse_data_structs.py and kernel_include.py; Part 2: media documentation fixes.
2025-10-17docs: media: dvb: fix dmx.h.rst.exceptionsMauro Carvalho Chehab
There are lots of broken links on dmx. Those are mostly linked to namespace handling. Yet, some symbols were pointed to the wrong locations, and there are some definitions that aren't needed. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b2acf243771529daa925afddd2b68d07d7bbb164.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: headers: warn about broken cross referencesMauro Carvalho Chehab
Enable cross-reference warnings for demux header. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8f98dde399df8b937dadf09168194bacce682c7d.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dmx_types: place kerneldoc at the right namespaceMauro Carvalho Chehab
The DVB documentation is using DTV.dmx for all demux symbols. Use such domain for kernel-doc documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <27fcc036fb5c80bda8116029e1964ad229208095.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: cec: show broken xrefs and show TOC instead of cec.h contentMauro Carvalho Chehab
Enable xref broken warnings. While here, change the output to only show cross-references, as there's no need to show the entire cec.h header at the docs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <c587872ca3685213d9f8e88277404c9e253633df.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: cec: cec.h.rst.exceptions: fix broken references from cec.hMauro Carvalho Chehab
All references there belong to CEC namespace. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dd1270dd5d91538cdfb0b087127c53a9f4ba7885.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: add some C domain missing referencesMauro Carvalho Chehab
Some enum/struct fields don't contain C domain references. Add them to avoid broken xrefs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <c9b036938197f1dd5bc93f5c5be0245bd9e5d1ee.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: videodev2.h.rst.exceptions: ignore struct __kernel_v4l2_timevalMauro Carvalho Chehab
This is an ancillary struct used for year-2038 compat logic. It is not meant to be used directly on userspace. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <a6a0dc7366b1a5d7184b8f7d4ba27689051a1f6a.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: add a missing reference for VIDIOC_QUERY_CTRLMauro Carvalho Chehab
This one is missing its c:macro definition. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <46f86be6ace28abe83ea9ce6fa6138e40185a23a.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: videodev2.h.rst.exceptions: fix namespace on refsMauro Carvalho Chehab
Media uses V4L domain, but the replace rules are not considering it. Fix them. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <927f9c19d90b62ffda950cdac9bba23c2ca09f53.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: add missing c namespace to V4L headersMauro Carvalho Chehab
Media references belong to V4L namespace. Fix a lot of broken links when including videodev2.h and probably fixing several other broken cross-references between different files inside media docs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b69fc5bd43da7d326b9f4720df59388088c64065.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: use get_close_matches() to propose alternativesMauro Carvalho Chehab
Improve the suggestions algorithm by using get_close_matches() if no suggestions with the same name are found. As we're now building a dict, when the name is identical, but on a different domain, the search is O(1), making it a lot faster. The get_close_matches is also fast, as there is just one loop, instead of 3. This can be useful to detect typos on references, with could be the base of a futuere extension that will handle ref unmatches for the entire build, allowing someone to find typos and fix them. As difflib and get_close_matches are there since the early Python 3.x days, we don't need to handle any extra dependencies to use it. We're keeping the default values for the search, e.g. n=3, cutoff=0.6. With that, we now have things like: $ make SPHINXDIRS="userspace-api/media" htmldocs ... include/uapi/linux/videodev2.h:199: WARNING: Invalid xref: c:type:`v4l2_memory`. Possible alternatives: c:type:`v4l2_meta_format` (from v4l/dev-meta) c:type:`v4l2_rect` (from v4l/dev-overlay) c:type:`v4l2_area` (from v4l/ext-ctrls-image-source) [ref.missing] ... include/uapi/linux/videodev2.h:1985: WARNING: Invalid xref: c:type:`V4L.v4l2_queryctrl`. Possible alternatives: std:label:`v4l2-queryctrl` (from v4l/vidioc-queryctrl) std:label:`v4l2-query-ext-ctrl` (from v4l/vidioc-queryctrl) At the first example, it was not a typo, but a symbol that doesn't seem to be properly documented. The second example points to v4l2-queryctrl, which is a close match for the symbol. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <7365feb74cbdd6b982c87baf5863360ab98cf727.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: mediactl: use TOC instead of file contentsMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for media controller and enable warnings. Here, we need to adjust the exceptions file to setup the C namespace accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5c8a87be712397563fc8ca914c3d92fe675e4071.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: rc: use TOC instead of file contents for LIRC headerMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for LIRC and enable warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <94dc601b4777ca544489ffc6cef9a2da5fe28e0e.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: enable warnings for most headersMauro Carvalho Chehab
Except for two exception rules and dmx.h, the other files are already handling properly cross references. Fix the two exception rules for frontend.h, as those are false-positives: include/uapi/linux/dvb/frontend.h:959: WARNING: can't link to: c:type:: FE_GET_PROPERTY include/uapi/linux/dvb/frontend.h:933: WARNING: can't link to: c:func:: FE_SET_FRONTEND_TUNE_MODE The dmx.h are actual issues that will require an extra patch to fill gaps. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <9ae6556ebd47de4f066a149ab0bbe7ce27acf2c4.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: use TOC instead of file contents at headersMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for DVB. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dbe95d83ae2117ed532fda423fd1c1d9906b7a19.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: accept more reftypesMauro Carvalho Chehab
Current regex is limited to only some c-domain reftypes. There are several others. Change the code to pick the name specified there. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5c146923d1e3183893f290216fb1378954e2e540.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: add namespace supportMauro Carvalho Chehab
C domain supports a ".. c:namespace::" tag that allows setting a symbol namespace. This is used within the kernel to avoid warnings about duplicated symbols. This is specially important for syscalls, as each subsystem may have their own documentation for them. This is specially true for ioctl. When such tag is used, all C domain symbols have c++ style, e.g. they'll become "{namespace}.{reference}". Allow specifying C namespace at the exception files, avoiding the need of override rules for every symbol. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <cc27ec60ceb3bdac4197fb7266d2df8155edacda.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: get rid of process_exceptions()Mauro Carvalho Chehab
Add an extra parameter to parse_file to make it handle exceptions internally, cleaning up the API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs: make process_exceptions two stagesMauro Carvalho Chehab
Split the logic which parses exceptions on two stages, preparing the exceptions file to have rules that will affect xref generation. For now, preserve the original API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <da9ca5f2ce1ffcfb355e32e676ff013607c227e0.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: propose alternativesMauro Carvalho Chehab
Specially when using c::namespace, it is not hard to break a reference by forgetting to add a domain. Also, different cases and using "-"/"_" the wrong way are typical cases that people often gets wrong. We might use a more complex logic here to also check for typos, but let's keep it plain, simple. This is enough to get thos exeptions from media controller: .../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_device_info`. Possible alternatives: c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info) .../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_entity_desc`. Possible alternatives: c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities) .../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_link_desc`. Possible alternatives: c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_links_enum`. Possible alternatives: c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_pad_desc`. Possible alternatives: c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_v2_entity`. Possible alternatives: c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_v2_interface`. Possible alternatives: c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_v2_intf_devnode`. Possible alternatives: c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_v2_link`. Possible alternatives: c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_v2_pad`. Possible alternatives: c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_v2_topology`. Possible alternatives: c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology) Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <4c75d277e950e619ea00ba2dea336853a4aac976.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: fix line numbers for TOCMauro Carvalho Chehab
On TOC output, we need to embeed line numbers with ViewList. Change the parse class to produce a line-number parsed result, and adjust the output accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <74eed96e32f79eaaef7a99ffe7c3224fed369c27.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: output a line numberMauro Carvalho Chehab
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dcffa6844dede00052f5fb851a857991468f22b5.1759329363.git.mchehab+huawei@kernel.org>
generated by cgit v1.3 (git 2.53.0) at 2026-11-11 23:59:24 +0000