diff --git a/.pylintrc b/.pylintrc index 89eaf2100edd..8c6fc2b628b3 100644 --- a/.pylintrc +++ b/.pylintrc @@ -1,2 +1,2 @@ [MASTER] -init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi", "tools/docs/lib"]' +init-hook='import sys; sys.path += ["tools/lib/python"]' diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module index 62addab47d0c..6bc9af6229f0 100644 --- a/Documentation/ABI/testing/sysfs-module +++ b/Documentation/ABI/testing/sysfs-module @@ -59,6 +59,8 @@ Description: Module taint flags: F force-loaded module C staging driver module E unsigned module + K livepatch module + N in-kernel test module == ===================== What: /sys/module/grant_table/parameters/free_per_iteration diff --git a/Documentation/Kconfig b/Documentation/Kconfig index 3a0e7ac0c4e3..8b6c4b84b218 100644 --- a/Documentation/Kconfig +++ b/Documentation/Kconfig @@ -19,7 +19,7 @@ config WARN_ABI_ERRORS described at Documentation/ABI/README. Yet, as they're manually written, it would be possible that some of those files would have errors that would break them for being parsed by - scripts/get_abi.pl. Add a check to verify them. + tools/docs/get_abi.py. Add a check to verify them. If unsure, select 'N'. diff --git a/Documentation/Makefile b/Documentation/Makefile index 3609cb86137b..e96ac6dcac4f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -8,12 +8,12 @@ subdir- := devicetree/bindings ifneq ($(MAKECMDGOALS),cleandocs) # Check for broken documentation file references ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) -$(shell $(srctree)/scripts/documentation-file-ref-check --warn) +$(shell $(srctree)/tools/docs/documentation-file-ref-check --warn) endif # Check for broken ABI files ifeq ($(CONFIG_WARN_ABI_ERRORS),y) -$(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI validate) +$(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate) endif endif @@ -23,21 +23,22 @@ SPHINXOPTS = SPHINXDIRS = . DOCS_THEME = DOCS_CSS = -_SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) -SPHINX_CONF = conf.py +RUSTDOC = PAPER = BUILDDIR = $(obj)/output PDFLATEX = xelatex LATEXOPTS = -interaction=batchmode -no-shell-escape +PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__) + +# Wrapper for sphinx-build + +BUILD_WRAPPER = $(srctree)/tools/docs/sphinx-build-wrapper + # 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 - # User-friendly check for sphinx-build HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) @@ -46,141 +47,46 @@ ifeq ($(HAVE_SPHINX),0) .DEFAULT: $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) @echo - @$(srctree)/scripts/sphinx-pre-install + @$(srctree)/tools/docs/sphinx-pre-install @echo " SKIP Sphinx $@ target." else # HAVE_SPHINX -# User-friendly check for pdflatex and latexmk -HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) -HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) +# Common documentation targets +htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs: + $(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ + $(srctree)/tools/docs/sphinx-pre-install --version-check + +$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ + $(PYTHON3) $(BUILD_WRAPPER) $@ \ + --sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \ + --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \ + --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER) -ifeq ($(HAVE_LATEXMK),1) - PDFLATEX := latexmk -$(PDFLATEX) -endif #HAVE_LATEXMK -# Internal variables. -PAPEROPT_a4 = -D latex_elements.papersize=a4paper -PAPEROPT_letter = -D latex_elements.papersize=letterpaper -ALLSPHINXOPTS = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -ifneq ($(wildcard $(srctree)/.config),) -ifeq ($(CONFIG_RUST),y) - # Let Sphinx know we will include rustdoc - ALLSPHINXOPTS += -t rustdoc endif -endif -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* -loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; - -# $2 sphinx builder e.g. "html" -# $3 name of the build subfolder / e.g. "userspace-api/media", used as: -# * dest folder relative to $(BUILDDIR) and -# * cache folder relative to $(BUILDDIR)/.doctrees -# $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man -# $5 reST source folder relative to $(src), -# e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media - -PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__) - -quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = \ - PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ - BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ - $(PYTHON3) $(srctree)/scripts/jobserver-exec \ - $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ - $(SPHINXBUILD) \ - -b $2 \ - -c $(abspath $(src)) \ - -d $(abspath $(BUILDDIR)/.doctrees/$3) \ - -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ - $(ALLSPHINXOPTS) \ - $(abspath $(src)/$5) \ - $(abspath $(BUILDDIR)/$3/$4) && \ - if [ "x$(DOCS_CSS)" != "x" ]; then \ - cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ - fi - -htmldocs: - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) - -htmldocs-redirects: $(srctree)/Documentation/.renames.txt - @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< - -# If Rust support is available and .config exists, add rustdoc generated contents. -# If there are any, the errors from this make rustdoc will be displayed but -# won't stop the execution of htmldocs - -ifneq ($(wildcard $(srctree)/.config),) -ifeq ($(CONFIG_RUST),y) - $(Q)$(MAKE) rustdoc || true -endif -endif - -texinfodocs: - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) - -# Note: the 'info' Make target is generated by sphinx itself when -# running the texinfodocs target define above. -infodocs: texinfodocs - $(MAKE) -C $(BUILDDIR)/texinfo info - -linkcheckdocs: - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) - -latexdocs: - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) - -ifeq ($(HAVE_PDFLATEX),0) - -pdfdocs: - $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) - @echo " SKIP Sphinx $@ target." - -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)" $(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/; \ - ) - -endif # HAVE_PDFLATEX - -epubdocs: - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) - -xmldocs: - @$(srctree)/scripts/sphinx-pre-install --version-check - @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) - -endif # HAVE_SPHINX # The following targets are independent of HAVE_SPHINX, and the rules should # work or silently pass without Sphinx. +htmldocs-redirects: $(srctree)/Documentation/.renames.txt + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< + refcheckdocs: - $(Q)cd $(srctree);scripts/documentation-file-ref-check + $(Q)cd $(srctree); tools/docs/documentation-file-ref-check cleandocs: $(Q)rm -rf $(BUILDDIR) +# Used only on help +_SPHINXDIRS = $(shell printf "%s\n" $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)) | sort -f) + dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' @echo ' htmldocs - HTML' @echo ' htmldocs-redirects - generate HTML redirects for moved pages' @echo ' texinfodocs - Texinfo' @echo ' infodocs - Info' + @echo ' mandocs - Man pages' @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' @@ -192,13 +98,17 @@ dochelp: @echo ' cleandocs - clean all generated files' @echo @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' - @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' - @echo - @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' - @echo ' configuration. This is e.g. useful to build with nit-picking config.' + @echo ' top level values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo ' you may also use a subdirectory like SPHINXDIRS=userspace-api/media,' + @echo ' provided that there is an index.rst file at the subdirectory.' @echo @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' @echo @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' @echo + @echo ' make PAPER={a4|letter} Specifies the paper size used for LaTeX/PDF output.' + @echo + @echo ' make FONTS_CONF_DENY_VF={path} sets a deny list to block variable Noto CJK fonts' + @echo ' for PDF build. See tools/lib/python/kdoc/latex_fonts.py for more details' + @echo @echo ' Default location for the generated documents is Documentation/output' diff --git a/Documentation/accounting/taskstats.rst b/Documentation/accounting/taskstats.rst index 2a28b7f55c10..173c1e7bf5ef 100644 --- a/Documentation/accounting/taskstats.rst +++ b/Documentation/accounting/taskstats.rst @@ -76,41 +76,43 @@ The messages are in the format:: The taskstats payload is one of the following three kinds: 1. Commands: Sent from user to kernel. Commands to get data on -a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID, -containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes -the task/process for which userspace wants statistics. + a pid/tgid consist of one attribute, of type TASKSTATS_CMD_ATTR_PID/TGID, + containing a u32 pid or tgid in the attribute payload. The pid/tgid denotes + the task/process for which userspace wants statistics. -Commands to register/deregister interest in exit data from a set of cpus -consist of one attribute, of type -TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the -attribute payload. The cpumask is specified as an ascii string of -comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8 -the cpumask would be "1-3,5,7-8". If userspace forgets to deregister interest -in cpus before closing the listening socket, the kernel cleans up its interest -set over time. However, for the sake of efficiency, an explicit deregistration -is advisable. + Commands to register/deregister interest in exit data from a set of cpus + consist of one attribute, of type + TASKSTATS_CMD_ATTR_REGISTER/DEREGISTER_CPUMASK and contain a cpumask in the + attribute payload. The cpumask is specified as an ascii string of + comma-separated cpu ranges e.g. to listen to exit data from cpus 1,2,3,5,7,8 + the cpumask would be "1-3,5,7-8". If userspace forgets to deregister + interest in cpus before closing the listening socket, the kernel cleans up + its interest set over time. However, for the sake of efficiency, an explicit + deregistration is advisable. 2. Response for a command: sent from the kernel in response to a userspace -command. The payload is a series of three attributes of type: + command. The payload is a series of three attributes of type: -a) TASKSTATS_TYPE_AGGR_PID/TGID : attribute containing no payload but indicates -a pid/tgid will be followed by some stats. + a) TASKSTATS_TYPE_AGGR_PID/TGID: attribute containing no payload but + indicates a pid/tgid will be followed by some stats. -b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose stats -are being returned. + b) TASKSTATS_TYPE_PID/TGID: attribute whose payload is the pid/tgid whose + stats are being returned. -c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The -same structure is used for both per-pid and per-tgid stats. + c) TASKSTATS_TYPE_STATS: attribute with a struct taskstats as payload. The + same structure is used for both per-pid and per-tgid stats. 3. New message sent by kernel whenever a task exits. The payload consists of a series of attributes of the following type: -a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats -b) TASKSTATS_TYPE_PID: contains exiting task's pid -c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats -d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be tgid+stats -e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs -f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's process + a) TASKSTATS_TYPE_AGGR_PID: indicates next two attributes will be pid+stats + b) TASKSTATS_TYPE_PID: contains exiting task's pid + c) TASKSTATS_TYPE_STATS: contains the exiting task's per-pid stats + d) TASKSTATS_TYPE_AGGR_TGID: indicates next two attributes will be + tgid+stats + e) TASKSTATS_TYPE_TGID: contains tgid of process to which task belongs + f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's + process per-tgid stats diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst index 090f3a185e18..f8e7407698bd 100644 --- a/Documentation/admin-guide/efi-stub.rst +++ b/Documentation/admin-guide/efi-stub.rst @@ -79,6 +79,9 @@ because the image we're executing is interpreted by the EFI shell, which understands relative paths, whereas the rest of the command line is passed to bzImage.efi. +.. hint:: + It is also possible to provide an initrd using a Linux-specific UEFI + protocol at boot time. See :ref:`pe-coff-entry-point` for details. The "dtb=" option ----------------- diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst index 210020bc3f56..35dc25159b28 100644 --- a/Documentation/admin-guide/hw-vuln/l1d_flush.rst +++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst @@ -31,7 +31,7 @@ specifically opt into the feature to enable it. Mitigation ---------- -When PR_SET_L1D_FLUSH is enabled for a task a flush of the L1D cache is +When PR_SPEC_L1D_FLUSH is enabled for a task a flush of the L1D cache is performed when the task is scheduled out and the incoming task belongs to a different process and therefore to a different address space. diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 991f12adef8d..4bb8549bee82 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -406,7 +406,7 @@ The possible values in this file are: - Single threaded indirect branch prediction (STIBP) status for protection between different hyper threads. This feature can be controlled through - prctl per process, or through kernel command line options. This is x86 + prctl per process, or through kernel command line options. This is an x86 only feature. For more details see below. ==================== ======================================================== diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 7bf8cc7df6b5..02a725536cc5 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -110,102 +110,7 @@ The parameters listed below are only valid if certain kernel build options were enabled and if respective hardware is present. This list should be kept in alphabetical order. The text in square brackets at the beginning of each description states the restrictions within which a parameter -is applicable:: - - ACPI ACPI support is enabled. - AGP AGP (Accelerated Graphics Port) is enabled. - ALSA ALSA sound support is enabled. - APIC APIC support is enabled. - APM Advanced Power Management support is enabled. - APPARMOR AppArmor support is enabled. - ARM ARM architecture is enabled. - ARM64 ARM64 architecture is enabled. - AX25 Appropriate AX.25 support is enabled. - CLK Common clock infrastructure is enabled. - CMA Contiguous Memory Area support is enabled. - DRM Direct Rendering Management support is enabled. - DYNAMIC_DEBUG Build in debug messages and enable them at runtime - EARLY Parameter processed too early to be embedded in initrd. - EDD BIOS Enhanced Disk Drive Services (EDD) is enabled - EFI EFI Partitioning (GPT) is enabled - EVM Extended Verification Module - FB The frame buffer device is enabled. - FTRACE Function tracing enabled. - GCOV GCOV profiling is enabled. - HIBERNATION HIBERNATION is enabled. - HW Appropriate hardware is enabled. - HYPER_V HYPERV support is enabled. - IMA Integrity measurement architecture is enabled. - IP_PNP IP DHCP, BOOTP, or RARP is enabled. - IPV6 IPv6 support is enabled. - ISAPNP ISA PnP code is enabled. - ISDN Appropriate ISDN support is enabled. - ISOL CPU Isolation is enabled. - JOY Appropriate joystick support is enabled. - KGDB Kernel debugger support is enabled. - KVM Kernel Virtual Machine support is enabled. - LIBATA Libata driver is enabled - LOONGARCH LoongArch architecture is enabled. - LOOP Loopback device support is enabled. - LP Printer support is enabled. - M68k M68k architecture is enabled. - These options have more detailed description inside of - Documentation/arch/m68k/kernel-options.rst. - MDA MDA console support is enabled. - MIPS MIPS architecture is enabled. - MOUSE Appropriate mouse support is enabled. - MSI Message Signaled Interrupts (PCI). - MTD MTD (Memory Technology Device) support is enabled. - NET Appropriate network support is enabled. - NFS Appropriate NFS support is enabled. - NUMA NUMA support is enabled. - OF Devicetree is enabled. - PARISC The PA-RISC architecture is enabled. - PCI PCI bus support is enabled. - PCIE PCI Express support is enabled. - PCMCIA The PCMCIA subsystem is enabled. - PNP Plug & Play support is enabled. - PPC PowerPC architecture is enabled. - PPT Parallel port support is enabled. - PS2 Appropriate PS/2 support is enabled. - PV_OPS A paravirtualized kernel is enabled. - RAM RAM disk support is enabled. - RDT Intel Resource Director Technology. - RISCV RISCV architecture is enabled. - S390 S390 architecture is enabled. - SCSI Appropriate SCSI support is enabled. - A lot of drivers have their options described inside - the Documentation/scsi/ sub-directory. - SDW SoundWire support is enabled. - SECURITY Different security models are enabled. - SELINUX SELinux support is enabled. - SERIAL Serial support is enabled. - SH SuperH architecture is enabled. - SMP The kernel is an SMP kernel. - SPARC Sparc architecture is enabled. - SUSPEND System suspend states are enabled. - SWSUSP Software suspend (hibernation) is enabled. - TPM TPM drivers are enabled. - UMS USB Mass Storage support is enabled. - USB USB support is enabled. - USBHID USB Human Interface Device support is enabled. - V4L Video For Linux support is enabled. - VGA The VGA console has been enabled. - VMMIO Driver for memory mapped virtio devices is enabled. - VT Virtual terminal support is enabled. - WDT Watchdog support is enabled. - X86-32 X86-32, aka i386 architecture is enabled. - X86-64 X86-64 architecture is enabled. - X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) - X86_UV SGI UV support is enabled. - XEN Xen support is enabled - XTENSA xtensa architecture is enabled. - -In addition, the following text indicates that the option:: - - BOOT Is a boot loader parameter. - BUGS= Relates to possible processor bugs on the said processor. - KNL Is a kernel start-up parameter. +is applicable. Parameters denoted with BOOT are actually interpreted by the boot loader, and have no meaning to the kernel directly. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 2b465eab41a1..1e89d122f084 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1,3 +1,101 @@ + ACPI ACPI support is enabled. + AGP AGP (Accelerated Graphics Port) is enabled. + ALSA ALSA sound support is enabled. + APIC APIC support is enabled. + APM Advanced Power Management support is enabled. + APPARMOR AppArmor support is enabled. + ARM ARM architecture is enabled. + ARM64 ARM64 architecture is enabled. + AX25 Appropriate AX.25 support is enabled. + CLK Common clock infrastructure is enabled. + CMA Contiguous Memory Area support is enabled. + DRM Direct Rendering Management support is enabled. + DYNAMIC_DEBUG Build in debug messages and enable them at runtime + EARLY Parameter processed too early to be embedded in initrd. + EDD BIOS Enhanced Disk Drive Services (EDD) is enabled + EFI EFI Partitioning (GPT) is enabled + EVM Extended Verification Module + FB The frame buffer device is enabled. + FTRACE Function tracing enabled. + GCOV GCOV profiling is enabled. + HIBERNATION HIBERNATION is enabled. + HW Appropriate hardware is enabled. + HYPER_V HYPERV support is enabled. + IMA Integrity measurement architecture is enabled. + IP_PNP IP DHCP, BOOTP, or RARP is enabled. + IPV6 IPv6 support is enabled. + ISAPNP ISA PnP code is enabled. + ISDN Appropriate ISDN support is enabled. + ISOL CPU Isolation is enabled. + JOY Appropriate joystick support is enabled. + KGDB Kernel debugger support is enabled. + KVM Kernel Virtual Machine support is enabled. + LIBATA Libata driver is enabled + LOONGARCH LoongArch architecture is enabled. + LOOP Loopback device support is enabled. + LP Printer support is enabled. + M68k M68k architecture is enabled. + These options have more detailed description inside of + Documentation/arch/m68k/kernel-options.rst. + MDA MDA console support is enabled. + MIPS MIPS architecture is enabled. + MOUSE Appropriate mouse support is enabled. + MSI Message Signaled Interrupts (PCI). + MTD MTD (Memory Technology Device) support is enabled. + NET Appropriate network support is enabled. + NFS Appropriate NFS support is enabled. + NUMA NUMA support is enabled. + OF Devicetree is enabled. + PARISC The PA-RISC architecture is enabled. + PCI PCI bus support is enabled. + PCIE PCI Express support is enabled. + PCMCIA The PCMCIA subsystem is enabled. + PNP Plug & Play support is enabled. + PPC PowerPC architecture is enabled. + PPT Parallel port support is enabled. + PS2 Appropriate PS/2 support is enabled. + PV_OPS A paravirtualized kernel is enabled. + RAM RAM disk support is enabled. + RDT Intel Resource Director Technology. + RISCV RISCV architecture is enabled. + S390 S390 architecture is enabled. + SCSI Appropriate SCSI support is enabled. + A lot of drivers have their options described inside + the Documentation/scsi/ sub-directory. + SDW SoundWire support is enabled. + SECURITY Different security models are enabled. + SELINUX SELinux support is enabled. + SERIAL Serial support is enabled. + SH SuperH architecture is enabled. + SMP The kernel is an SMP kernel. + SPARC Sparc architecture is enabled. + SUSPEND System suspend states are enabled. + SWSUSP Software suspend (hibernation) is enabled. + TPM TPM drivers are enabled. + UMS USB Mass Storage support is enabled. + USB USB support is enabled. + USBHID USB Human Interface Device support is enabled. + V4L Video For Linux support is enabled. + VGA The VGA console has been enabled. + VMMIO Driver for memory mapped virtio devices is enabled. + VT Virtual terminal support is enabled. + WDT Watchdog support is enabled. + X86-32 X86-32, aka i386 architecture is enabled. + X86-64 X86-64 architecture is enabled. + X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) + X86_UV SGI UV support is enabled. + XEN Xen support is enabled + XTENSA xtensa architecture is enabled. + +In addition, the following text indicates that the option + + BOOT Is a boot loader parameter. + BUGS= Relates to possible processor bugs on the said processor. + KNL Is a kernel start-up parameter. + + +Kernel parameters + accept_memory= [MM] Format: { eager | lazy } default: lazy @@ -6414,7 +6512,7 @@ that don't. off - no mitigation - auto - automatically select a migitation + auto - automatically select a mitigation auto,nosmt - automatically select a mitigation, disabling SMT if necessary for the full mitigation (only on Zen1 @@ -7164,7 +7262,7 @@ limit. Default value is 8191 pools. stacktrace [FTRACE] - Enabled the stack tracer on boot up. + Enable the stack tracer on boot up. stacktrace_filter=[function-list] [FTRACE] Limit the functions that the stack tracer diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index a0cc017e4424..ed1f8f1e86c5 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -186,6 +186,6 @@ More detailed explanation for tainting 18) ``N`` if an in-kernel test, such as a KUnit test, has been run. - 19) ``J`` if userpace opened /dev/fwctl/* and performed a FWTCL_RPC_DEBUG_WRITE + 19) ``J`` if userspace opened /dev/fwctl/* and performed a FWTCL_RPC_DEBUG_WRITE to use the devices debugging features. Device debugging features could cause the device to malfunction in undefined ways. diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst index d6313890ee41..35963491b9f1 100644 --- a/Documentation/admin-guide/workload-tracing.rst +++ b/Documentation/admin-guide/workload-tracing.rst @@ -196,11 +196,11 @@ Let’s checkout the latest Linux repository and build cscope database:: cscope -R -p10 # builds cscope.out database before starting browse session cscope -d -p10 # starts browse session on cscope.out database -Note: Run "cscope -R -p10" to build the database and c"scope -d -p10" to -enter into the browsing session. cscope by default cscope.out database. -To get out of this mode press ctrl+d. -p option is used to specify the -number of file path components to display. -p10 is optimal for browsing -kernel sources. +Note: Run "cscope -R -p10" to build the database and "cscope -d -p10" to +enter into the browsing session. cscope by default uses the cscope.out +database. To get out of this mode press ctrl+d. -p option is used to +specify the number of file path components to display. -p10 is optimal +for browsing kernel sources. What is perf and how do we use it? ================================== diff --git a/Documentation/arch/x86/boot.rst b/Documentation/arch/x86/boot.rst index 77e6163288db..32eea3d2807e 100644 --- a/Documentation/arch/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -1431,12 +1431,34 @@ The boot loader *must* fill out the following fields in bp:: All other fields should be zero. .. note:: - The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF - entry point, combined with the LINUX_EFI_INITRD_MEDIA_GUID based initrd - loading protocol (refer to [0] for an example of the bootloader side of - this), which removes the need for any knowledge on the part of the EFI - bootloader regarding the internal representation of boot_params or any - requirements/limitations regarding the placement of the command line - and ramdisk in memory, or the placement of the kernel image itself. + The EFI Handover Protocol is deprecated in favour of the ordinary PE/COFF + entry point described below. -[0] https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 +.. _pe-coff-entry-point: + +PE/COFF entry point +=================== + +When compiled with ``CONFIG_EFI_STUB=y``, the kernel can be executed as a +regular PE/COFF binary. See Documentation/admin-guide/efi-stub.rst for +implementation details. + +The stub loader can request the initrd via a UEFI protocol. For this to work, +the firmware or bootloader needs to register a handle which carries +implementations of the ``EFI_LOAD_FILE2`` protocol and the device path +protocol exposing the ``LINUX_EFI_INITRD_MEDIA_GUID`` vendor media device path. +In this case, a kernel booting via the EFI stub will invoke +``LoadFile2::LoadFile()`` method on the registered protocol to instruct the +firmware to load the initrd into a memory location chosen by the kernel/EFI +stub. + +This approach removes the need for any knowledge on the part of the EFI +bootloader regarding the internal representation of boot_params or any +requirements/limitations regarding the placement of the command line and +ramdisk in memory, or the placement of the kernel image itself. + +For sample implementations, refer to `the original u-boot implementation`_ or +`the OVMF implementation`_. + +.. _the original u-boot implementation: https://github.com/u-boot/u-boot/commit/ec80b4735a593961fe701cc3a5d717d4739b0fd0 +.. _the OVMF implementation: https://github.com/tianocore/edk2/blob/1780373897f12c25075f8883e073144506441168/OvmfPkg/LinuxInitrdDynamicShellCommand/LinuxInitrdDynamicShellCommand.c diff --git a/Documentation/conf.py b/Documentation/conf.py index 574896cca198..1ea2ae5c6276 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -18,8 +18,6 @@ import sphinx # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath("sphinx")) -from load_config import loadConfig # pylint: disable=C0413,E0401 - # Minimal supported version needs_sphinx = "3.4.3" @@ -93,8 +91,12 @@ def config_init(app, config): # LaTeX and PDF output require a list of documents with are dependent # of the app.srcdir. Add them here - # When SPHINXDIRS is used, we just need to get index.rst, if it exists + # Handle the case where SPHINXDIRS is used if not os.path.samefile(doctree, app.srcdir): + # Add a tag to mark that the build is actually a subproject + tags.add("subproject") + + # get index.rst, if it exists doc = os.path.basename(app.srcdir) fname = "index" if os.path.exists(os.path.join(app.srcdir, fname + ".rst")): @@ -583,13 +585,6 @@ pdf_documents = [ kerneldoc_bin = "../scripts/kernel-doc.py" kerneldoc_srctree = ".." -# ------------------------------------------------------------------------------ -# Since loadConfig overwrites settings from the global namespace, it has to be -# the last statement in the conf.py file -# ------------------------------------------------------------------------------ -loadConfig(globals()) - - def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-api/assoc_array.rst index 792bbf9939e1..19d89f92bf8d 100644 --- a/Documentation/core-api/assoc_array.rst +++ b/Documentation/core-api/assoc_array.rst @@ -92,18 +92,18 @@ There are two functions for dealing with the script: void assoc_array_apply_edit(struct assoc_array_edit *edit); -This will perform the edit functions, interpolating various write barriers -to permit accesses under the RCU read lock to continue. The edit script -will then be passed to ``call_rcu()`` to free it and any dead stuff it points -to. + This will perform the edit functions, interpolating various write barriers + to permit accesses under the RCU read lock to continue. The edit script + will then be passed to ``call_rcu()`` to free it and any dead stuff it + points to. 2. Cancel an edit script:: void assoc_array_cancel_edit(struct assoc_array_edit *edit); -This frees the edit script and all preallocated memory immediately. If -this was for insertion, the new object is _not_ released by this function, -but must rather be released by the caller. + This frees the edit script and all preallocated memory immediately. If + this was for insertion, the new object is *not* released by this function, + but must rather be released by the caller. These functions are guaranteed not to fail. @@ -123,43 +123,43 @@ This points to a number of methods, all of which need to be provided: unsigned long (*get_key_chunk)(const void *index_key, int level); -This should return a chunk of caller-supplied index key starting at the -*bit* position given by the level argument. The level argument will be a -multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return -``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. + This should return a chunk of caller-supplied index key starting at the + *bit* position given by the level argument. The level argument will be a + multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return + ``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``. No error is possible. 2. Get a chunk of an object's index key:: unsigned long (*get_object_key_chunk)(const void *object, int level); -As the previous function, but gets its data from an object in the array -rather than from a caller-supplied index key. + As the previous function, but gets its data from an object in the array + rather than from a caller-supplied index key. 3. See if this is the object we're looking for:: bool (*compare_object)(const void *object, const void *index_key); -Compare the object against an index key and return ``true`` if it matches and -``false`` if it doesn't. + Compare the object against an index key and return ``true`` if it matches + and ``false`` if it doesn't. 4. Diff the index keys of two objects:: int (*diff_objects)(const void *object, const void *index_key); -Return the bit position at which the index key of the specified object -differs from the given index key or -1 if they are the same. + Return the bit position at which the index key of the specified object + differs from the given index key or -1 if they are the same. 5. Free an object:: void (*free_object)(void *object); -Free the specified object. Note that this may be called an RCU grace period -after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` may be -necessary on module unloading. + Free the specified object. Note that this may be called an RCU grace period + after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` may + be necessary on module unloading. Manipulation Functions @@ -171,7 +171,7 @@ There are a number of functions for manipulating an associative array: void assoc_array_init(struct assoc_array *array); -This initialises the base structure for an associative array. It can't fail. + This initialises the base structure for an associative array. It can't fail. 2. Insert/replace an object in an associative array:: @@ -182,21 +182,21 @@ This initialises the base structure for an associative array. It can't fail. const void *index_key, void *object); -This inserts the given object into the array. Note that the least -significant bit of the pointer must be zero as it's used to type-mark -pointers internally. + This inserts the given object into the array. Note that the least + significant bit of the pointer must be zero as it's used to type-mark + pointers internally. -If an object already exists for that key then it will be replaced with the -new object and the old one will be freed automatically. + If an object already exists for that key then it will be replaced with the + new object and the old one will be freed automatically. -The ``index_key`` argument should hold index key information and is -passed to the methods in the ops table when they are called. + The ``index_key`` argument should hold index key information and is + passed to the methods in the ops table when they are called. -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case of -an out-of-memory error. + This function makes no alteration to the array itself, but rather returns + an edit script that must be applied. ``-ENOMEM`` is returned in the case of + an out-of-memory error. -The caller should lock exclusively against other modifiers of the array. + The caller should lock exclusively against other modifiers of the array. 3. Delete an object from an associative array:: @@ -206,15 +206,15 @@ The caller should lock exclusively against other modifiers of the array. const struct assoc_array_ops *ops, const void *index_key); -This deletes an object that matches the specified data from the array. + This deletes an object that matches the specified data from the array. -The ``index_key`` argument should hold index key information and is -passed to the methods in the ops table when they are called. + The ``index_key`` argument should hold index key information and is + passed to the methods in the ops table when they are called. -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case of -an out-of-memory error. ``NULL`` will be returned if the specified object is -not found within the array. + This function makes no alteration to the array itself, but rather returns + an edit script that must be applied. ``-ENOMEM`` is returned in the case of + an out-of-memory error. ``NULL`` will be returned if the specified object + is not found within the array. The caller should lock exclusively against other modifiers of the array. @@ -225,14 +225,14 @@ The caller should lock exclusively against other modifiers of the array. assoc_array_clear(struct assoc_array *array, const struct assoc_array_ops *ops); -This deletes all the objects from an associative array and leaves it -completely empty. + This deletes all the objects from an associative array and leaves it + completely empty. -This function makes no alteration to the array itself, but rather returns -an edit script that must be applied. ``-ENOMEM`` is returned in the case of -an out-of-memory error. + This function makes no alteration to the array itself, but rather returns + an edit script that must be applied. ``-ENOMEM`` is returned in the case of + an out-of-memory error. -The caller should lock exclusively against other modifiers of the array. + The caller should lock exclusively against other modifiers of the array. 5. Destroy an associative array, deleting all objects:: @@ -240,14 +240,14 @@ The caller should lock exclusively against other modifiers of the array. void assoc_array_destroy(struct assoc_array *array, const struct assoc_array_ops *ops); -This destroys the contents of the associative array and leaves it -completely empty. It is not permitted for another thread to be traversing -the array under the RCU read lock at the same time as this function is -destroying it as no RCU deferral is performed on memory release - -something that would require memory to be allocated. + This destroys the contents of the associative array and leaves it + completely empty. It is not permitted for another thread to be traversing + the array under the RCU read lock at the same time as this function is + destroying it as no RCU deferral is performed on memory release - + something that would require memory to be allocated. -The caller should lock exclusively against other modifiers and accessors -of the array. + The caller should lock exclusively against other modifiers and accessors + of the array. 6. Garbage collect an associative array:: @@ -257,24 +257,24 @@ of the array. bool (*iterator)(void *object, void *iterator_data), void *iterator_data); -This iterates over the objects in an associative array and passes each one to -``iterator()``. If ``iterator()`` returns ``true``, the object is kept. If it -returns ``false``, the object will be freed. If the ``iterator()`` function -returns ``true``, it must perform any appropriate refcount incrementing on the -object before returning. + This iterates over the objects in an associative array and passes each one + to ``iterator()``. If ``iterator()`` returns ``true``, the object is kept. + If it returns ``false``, the object will be freed. If the ``iterator()`` + function returns ``true``, it must perform any appropriate refcount + incrementing on the object before returning. -The internal tree will be packed down if possible as part of the iteration -to reduce the number of nodes in it. + The internal tree will be packed down if possible as part of the iteration + to reduce the number of nodes in it. -The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise -ignored by the function. + The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise + ignored by the function. -The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't -enough memory. + The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't + enough memory. -It is possible for other threads to iterate over or search the array under -the RCU read lock while this function is in progress. The caller should -lock exclusively against other modifiers of the array. + It is possible for other threads to iterate over or search the array under + the RCU read lock while this function is in progress. The caller should + lock exclusively against other modifiers of the array. Access Functions @@ -289,19 +289,19 @@ There are two functions for accessing an associative array: void *iterator_data), void *iterator_data); -This passes each object in the array to the iterator callback function. -``iterator_data`` is private data for that function. + This passes each object in the array to the iterator callback function. + ``iterator_data`` is private data for that function. -This may be used on an array at the same time as the array is being -modified, provided the RCU read lock is held. Under such circumstances, -it is possible for the iteration function to see some objects twice. If -this is a problem, then modification should be locked against. The -iteration algorithm should not, however, miss any objects. + This may be used on an array at the same time as the array is being + modified, provided the RCU read lock is held. Under such circumstances, + it is possible for the iteration function to see some objects twice. If + this is a problem, then modification should be locked against. The + iteration algorithm should not, however, miss any objects. -The function will return ``0`` if no objects were in the array or else it will -return the result of the last iterator function called. Iteration stops -immediately if any call to the iteration function results in a non-zero -return. + The function will return ``0`` if no objects were in the array or else it + will return the result of the last iterator function called. Iteration + stops immediately if any call to the iteration function results in a + non-zero return. 2. Find an object in an associative array:: @@ -310,14 +310,14 @@ return. const struct assoc_array_ops *ops, const void *index_key); -This walks through the array's internal tree directly to the object -specified by the index key.. + This walks through the array's internal tree directly to the object + specified by the index key. -This may be used on an array at the same time as the array is being -modified, provided the RCU read lock is held. + This may be used on an array at the same time as the array is being + modified, provided the RCU read lock is held. -The function will return the object if found (and set ``*_type`` to the object -type) or will return ``NULL`` if the object was not found. + The function will return the object if found (and set ``*_type`` to the + object type) or will return ``NULL`` if the object was not found. Index Key Form @@ -399,10 +399,11 @@ fixed levels. For example:: In the above example, there are 7 nodes (A-G), each with 16 slots (0-f). Assuming no other meta data nodes in the tree, the key space is divided -thusly:: +thusly: + =========== ==== KEY PREFIX NODE - ========== ==== + =========== ==== 137* D 138* E 13[0-69-f]* C @@ -410,10 +411,12 @@ thusly:: e6* G e[0-57-f]* F [02-df]* A + =========== ==== So, for instance, keys with the following example index keys will be found in -the appropriate nodes:: +the appropriate nodes: + =============== ======= ==== INDEX KEY PREFIX NODE =============== ======= ==== 13694892892489 13 C @@ -422,12 +425,13 @@ the appropriate nodes:: 138bbb89003093 138 E 1394879524789 12 C 1458952489 1 B - 9431809de993ba - A - b4542910809cd - A + 9431809de993ba \- A + b4542910809cd \- A e5284310def98 e F e68428974237 e6 G e7fffcbd443 e F - f3842239082 - A + f3842239082 \- A + =============== ======= ==== To save memory, if a node can hold all the leaves in its portion of keyspace, then the node will have all those leaves in it and will not have any metadata @@ -441,8 +445,9 @@ metadata pointer. If the metadata pointer is there, any leaf whose key matches the metadata key prefix must be in the subtree that the metadata pointer points to. -In the above example list of index keys, node A will contain:: +In the above example list of index keys, node A will contain: + ==== =============== ================== SLOT CONTENT INDEX KEY (PREFIX) ==== =============== ================== 1 PTR TO NODE B 1* @@ -450,11 +455,16 @@ In the above example list of index keys, node A will contain:: any LEAF b4542910809cd e PTR TO NODE F e* any LEAF f3842239082 + ==== =============== ================== -and node B:: +and node B: - 3 PTR TO NODE C 13* - any LEAF 1458952489 + ==== =============== ================== + SLOT CONTENT INDEX KEY (PREFIX) + ==== =============== ================== + 3 PTR TO NODE C 13* + any LEAF 1458952489 + ==== =============== ================== Shortcuts diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst index d5c47e560324..dfaad0a279ff 100644 --- a/Documentation/dev-tools/checkpatch.rst +++ b/Documentation/dev-tools/checkpatch.rst @@ -461,16 +461,9 @@ Comments line comments is:: /* - * This is the preferred style - * for multi line comments. - */ - - The networking comment style is a bit different, with the first line - not empty like the former:: - - /* This is the preferred comment style - * for files in net/ and drivers/net/ - */ + * This is the preferred style + * for multi line comments. + */ See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst index dfaf9d373747..7b25375cc6d9 100644 --- a/Documentation/doc-guide/checktransupdate.rst +++ b/Documentation/doc-guide/checktransupdate.rst @@ -27,15 +27,15 @@ Usage :: - ./scripts/checktransupdate.py --help + tools/docs/checktransupdate.py --help Please refer to the output of argument parser for usage details. Samples -- ``./scripts/checktransupdate.py -l zh_CN`` +- ``tools/docs/checktransupdate.py -l zh_CN`` This will print all the files that need to be updated in the zh_CN locale. -- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` +- ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` This will only print the status of the specified file. Then the output is something like: diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst index 662c7a840cd5..f8047e633113 100644 --- a/Documentation/doc-guide/contributing.rst +++ b/Documentation/doc-guide/contributing.rst @@ -152,7 +152,7 @@ generate links to that documentation. Adding ``kernel-doc`` directives to the documentation to bring those comments in can help the community derive the full value of the work that has gone into creating them. -The ``scripts/find-unused-docs.sh`` tool can be used to find these +The ``tools/docs/find-unused-docs.sh`` tool can be used to find these overlooked comments. Note that the most value comes from pulling in the documentation for diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index af9697e60165..fd89a6d56ea9 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -405,6 +405,10 @@ Domain`_ references. ``%CONST`` Name of a constant. (No cross-referencing, just formatting.) + Examples:: + + %0 %NULL %-1 %-EFAULT %-EINVAL %-ENOMEM + ````literal```` A literal block that should be handled as-is. The output will use a ``monospaced font``. @@ -579,20 +583,23 @@ source. How to use kernel-doc to generate man pages ------------------------------------------- -If you just want to use kernel-doc to generate man pages you can do this -from the kernel git tree:: +To generate man pages for all files that contain kernel-doc markups, run:: - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- :^Documentation :^tools) \ - | scripts/split-man.pl /tmp/man + $ make mandocs -Some older versions of git do not support some of the variants of syntax for -path exclusion. One of the following commands may work for those versions:: +Or calling ``script-build-wrapper`` directly:: - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ - | scripts/split-man.pl /tmp/man + $ ./tools/docs/sphinx-build-wrapper mandocs - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ - | scripts/split-man.pl /tmp/man +The output will be at ``/man`` directory inside the output directory +(by default: ``Documentation/output``). + +Optionally, it is possible to generate a partial set of man pages by +using SPHINXDIRS: + + $ make SPHINXDIRS=driver-api/media mandocs + +.. note:: + + When SPHINXDIRS={subdir} is used, it will only generate man pages for + the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file. diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 204b025f1349..a7bb01ff04eb 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -5,173 +5,168 @@ Including uAPI header files Sometimes, it is useful to include header files and C example codes in order to describe the userspace API and to generate cross-references between the code and the documentation. Adding cross-references for -userspace API files has an additional vantage: Sphinx will generate warnings +userspace API files has an additional advantage: Sphinx will generate warnings if a symbol is not found at the documentation. That helps to keep the uAPI documentation in sync with the Kernel changes. -The :ref:`parse_headers.pl ` provide a way to generate such +The :ref:`parse_headers.py ` provides a way to generate such cross-references. It has to be called via Makefile, while building the documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example about how to use it inside the Kernel tree. .. _parse_headers: -parse_headers.pl -^^^^^^^^^^^^^^^^ +tools/docs/parse_headers.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^ NAME **** - -parse_headers.pl - parse a C file, in order to identify functions, structs, +parse_headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book. +USAGE +***** + +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` SYNOPSIS ******** +Converts a C header or source file ``FILE_IN`` into a ReStructured Text +included via ..parsed-literal block with cross-references for the +documentation files that describe the API. It accepts an optional +``FILE_RULES`` file to describe what elements will be either ignored or +be pointed to a non-default reference type/name. -\ **parse_headers.pl**\ [] [] +The output is written at ``FILE_OUT``. -Where can be: --debug, --help or --usage. +It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` +and enum ``symbol``, creating cross-references for all of them. +It is also capable of distinguishing ``#define`` used for specifying +Linux-specific macros used to define ``ioctl``. + +The optional ``FILE_RULES`` contains a set of rules like:: + + ignore ioctl VIDIOC_ENUM_FMT + replace ioctl VIDIOC_DQBUF vidioc_qbuf + replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` + +POSITIONAL ARGUMENTS +******************** + + ``FILE_IN`` + Input C file + + ``FILE_OUT`` + Output RST file + + ``FILE_RULES`` + Exceptions file (optional) OPTIONS ******* - - -\ **--debug**\ - - Put the script in verbose mode, useful for debugging. - - - -\ **--usage**\ - - Prints a brief help message and exits. - - - -\ **--help**\ - - Prints a more detailed help message and exits. + ``-h``, ``--help`` + show a help message and exit + ``-d``, ``--debug`` + Increase debug level. Can be used multiple times + ``-t``, ``--toc`` + instead of a literal block, outputs a TOC table at the RST file DESCRIPTION *********** +Creates an enriched version of a Kernel header file with cross-links +to each C data structure type, from ``FILE_IN``, formatting it with +reStructuredText notation, either as-is or as a table of contents. -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 -be pointed to a non-default reference. +It accepts an optional ``FILE_RULES`` which describes what elements will be +either ignored or be pointed to a non-default reference, and optionally +defines the C namespace to be used. -The output is written at the (OUT_FILE). +It is meant to allow having more comprehensive documentation, where +uAPI headers will create cross-reference links to the code. -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. -It is also capable of distinguish #define used for specifying a Linux -ioctl. +The output is written at the ``FILE_OUT``. -The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . +The ``FILE_RULES`` may contain contain three types of statements: +**ignore**, **replace** and **namespace**. -The syntax for the ignore tag is: +By default, it create rules for all symbols and defines, but it also +allows parsing an exception file. Such file contains a set of rules +using the syntax below: +1. Ignore rules: -ignore \ **type**\ \ **name**\ + ignore *type* *symbol* -The \ **ignore**\ means that it won't generate cross references for a -\ **name**\ symbol of type \ **type**\ . +Removes the symbol from reference generation. -The syntax for the replace tag is: +2. Replace rules: + replace *type* *old_symbol* *new_reference* -replace \ **type**\ \ **name**\ \ **new_value**\ + Replaces *old_symbol* with a *new_reference*. + The *new_reference* can be: -The \ **replace**\ means that it will generate cross references for a -\ **name**\ symbol of type \ **type**\ , but, instead of using the default -replacement rule, it will use \ **new_value**\ . + - A simple symbol name; + - A full Sphinx reference. -For both statements, \ **type**\ can be either one of the following: +3. Namespace rules + namespace *namespace* -\ **ioctl**\ + Sets C *namespace* to be used during cross-reference generation. Can + be overridden by replace rules. - The ignore or replace statement will apply to ioctl definitions like: +On ignore and replace rules, *type* can be: - #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + - ioctl: + for defines of the form ``_IO*``, e.g., ioctl definitions + - define: + for other defines + - symbol: + for symbols defined within enums; -\ **define**\ + - typedef: + for typedefs; - The ignore or replace statement will apply to any other #define found - at C_FILE. - - - -\ **typedef**\ - - The ignore or replace statement will apply to typedef statements at C_FILE. - - - -\ **struct**\ - - The ignore or replace statement will apply to the name of struct statements - at C_FILE. - - - -\ **enum**\ - - The ignore or replace statement will apply to the name of enum statements - at C_FILE. - - - -\ **symbol**\ - - The ignore or replace statement will apply to the name of enum value - at C_FILE. - - For replace statements, \ **new_value**\ will automatically use :c:type: - references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: - for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can - also be explicitly defined at the replace statement. + - enum: + for the name of a non-anonymous enum; + - struct: + for structs. EXAMPLES ******** +- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: -ignore define _VIDEODEV2_H + ignore define _VIDEODEV2_H + +- On an data structure like this enum:: + + enum foo { BAR1, BAR2, PRIVATE }; + + It won't generate cross-references for ``PRIVATE``:: + + ignore symbol PRIVATE + + At the same struct, instead of creating one cross reference per symbol, + make them all point to the ``enum foo`` C type:: + + replace symbol BAR1 :c:type:\`foo\` + replace symbol BAR2 :c:type:\`foo\` -Ignore a #define _VIDEODEV2_H at the C_FILE. - -ignore symbol PRIVATE - - -On a struct like: - -enum foo { BAR1, BAR2, PRIVATE }; - -It won't generate cross-references for \ **PRIVATE**\ . - -replace symbol BAR1 :c:type:\`foo\` -replace symbol BAR2 :c:type:\`foo\` - - -On a struct like: - -enum foo { BAR1, BAR2, PRIVATE }; - -It will make the BAR1 and BAR2 enum symbols to cross reference the foo -symbol at the C domain. +- Use C namespace ``MC`` for all symbols at ``FILE_IN``:: + namespace MC BUGS **** @@ -184,7 +179,7 @@ COPYRIGHT ********* -Copyright (c) 2016 by Mauro Carvalho Chehab . +Copyright (c) 2016, 2025 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 607589592bfb..51c370260f3b 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -106,7 +106,7 @@ There's a script that automatically checks for Sphinx dependencies. If it can recognize your distribution, it will also give a hint about the install command line options for your distro:: - $ ./scripts/sphinx-pre-install + $ ./tools/docs/sphinx-pre-install Checking if the needed tools for Fedora release 26 (Twenty Six) are available Warning: better to also install "texlive-luatex85". You should run: @@ -116,7 +116,7 @@ command line options for your distro:: . sphinx_2.4.4/bin/activate pip install -r Documentation/sphinx/requirements.txt - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + Can't build as 1 mandatory dependency is missing at ./tools/docs/sphinx-pre-install line 468. By default, it checks all the requirements for both html and PDF, including the requirements for images, math expressions and LaTeX build, and assumes @@ -149,7 +149,7 @@ a venv with it with, and install minimal requirements with:: A more comprehensive test can be done by using: - scripts/test_doc_build.py + tools/docs/test_doc_build.py Such script create one Python venv per supported version, optionally building documentation for a range of Sphinx versions. diff --git a/Documentation/driver-api/parport-lowlevel.rst b/Documentation/driver-api/parport-lowlevel.rst index 0633d70ffda7..a907e279f509 100644 --- a/Documentation/driver-api/parport-lowlevel.rst +++ b/Documentation/driver-api/parport-lowlevel.rst @@ -7,6 +7,7 @@ PARPORT interface documentation Described here are the following functions: Global functions:: + parport_register_driver parport_unregister_driver parport_enumerate @@ -34,6 +35,7 @@ Global functions:: Port functions (can be overridden by low-level drivers): SPP:: + port->ops->read_data port->ops->write_data port->ops->read_status @@ -46,17 +48,20 @@ Port functions (can be overridden by low-level drivers): port->ops->data_reverse EPP:: + port->ops->epp_write_data port->ops->epp_read_data port->ops->epp_write_addr port->ops->epp_read_addr ECP:: + port->ops->ecp_write_data port->ops->ecp_read_data port->ops->ecp_write_addr Other:: + port->ops->nibble_read_data port->ops->byte_read_data port->ops->compat_write_data diff --git a/Documentation/driver-api/pldmfw/index.rst b/Documentation/driver-api/pldmfw/index.rst index fd871b83f34f..e59beca374c1 100644 --- a/Documentation/driver-api/pldmfw/index.rst +++ b/Documentation/driver-api/pldmfw/index.rst @@ -14,7 +14,6 @@ the PLDM for Firmware Update standard file-format driver-ops -================================== Overview of the ``pldmfw`` library ================================== diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index 0bb96ecdf527..b748b9fb1965 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -709,7 +709,7 @@ Resources USB Home Page: https://www.usb.org -linux-usb Mailing List Archives: https://marc.info/?l=linux-usb +linux-usb Mailing List Archives: https://lore.kernel.org/linux-usb USB On-the-Go Basics: https://www.maximintegrated.com/app-notes/index.mvp/id/1822 diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.rst b/Documentation/filesystems/ramfs-rootfs-initramfs.rst index fa4f81099cb4..a9d271e171c3 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.rst +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.rst @@ -290,11 +290,11 @@ Why cpio rather than tar? This decision was made back in December, 2001. The discussion started here: - http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1538.html +- https://lore.kernel.org/lkml/a03cke$640$1@cesium.transmeta.com/ And spawned a second thread (specifically on tar vs cpio), starting here: - http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1587.html +- https://lore.kernel.org/lkml/3C25A06D.7030408@zytor.com/ The quick and dirty summary version (which is no substitute for reading the above threads) is: @@ -310,7 +310,7 @@ the above threads) is: either way about the archive format, and there are alternative tools, such as: - http://freecode.com/projects/afio + https://linux.die.net/man/1/afio 2) The cpio archive format chosen by the kernel is simpler and cleaner (and thus easier to create and parse) than any of the (literally dozens of) @@ -331,12 +331,12 @@ the above threads) is: 5) Al Viro made the decision (quote: "tar is ugly as hell and not going to be supported on the kernel side"): - http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1540.html + - https://lore.kernel.org/lkml/Pine.GSO.4.21.0112222109050.21702-100000@weyl.math.psu.edu/ explained his reasoning: - - http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1550.html - - http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1638.html + - https://lore.kernel.org/lkml/Pine.GSO.4.21.0112222240530.21702-100000@weyl.math.psu.edu/ + - https://lore.kernel.org/lkml/Pine.GSO.4.21.0112230849550.23300-100000@weyl.math.psu.edu/ and, most importantly, designed and implemented the initramfs code. diff --git a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst index 8cbcd3c26434..55e727b5f12e 100644 --- a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst @@ -249,7 +249,7 @@ sharing and lock acquisition rules as the regular filesystem. This means that scrub cannot take *any* shortcuts to save time, because doing so could lead to concurrency problems. In other words, online fsck is not a complete replacement for offline fsck, and -a complete run of online fsck may take longer than online fsck. +a complete run of online fsck may take longer than offline fsck. However, both of these limitations are acceptable tradeoffs to satisfy the different motivations of online fsck, which are to **minimize system downtime** and to **increase predictability of operation**. diff --git a/Documentation/misc-devices/amd-sbi.rst b/Documentation/misc-devices/amd-sbi.rst index 5648fc6ec572..07ceb44fbe5e 100644 --- a/Documentation/misc-devices/amd-sbi.rst +++ b/Documentation/misc-devices/amd-sbi.rst @@ -28,8 +28,10 @@ MCAMSR and register xfer commands. Register sets is common across APML protocols. IOCTL is providing synchronization among protocols as transactions may create race condition. -$ ls -al /dev/sbrmi-3c -crw------- 1 root root 10, 53 Jul 10 11:13 /dev/sbrmi-3c +.. code-block:: bash + + $ ls -al /dev/sbrmi-3c + crw------- 1 root root 10, 53 Jul 10 11:13 /dev/sbrmi-3c apml_sbrmi driver registers hwmon sensors for monitoring power_cap_max, current power consumption and managing power_cap. diff --git a/Documentation/misc-devices/mrvl_cn10k_dpi.rst b/Documentation/misc-devices/mrvl_cn10k_dpi.rst index a75e372723d8..fa9b8cd6806f 100644 --- a/Documentation/misc-devices/mrvl_cn10k_dpi.rst +++ b/Documentation/misc-devices/mrvl_cn10k_dpi.rst @@ -33,12 +33,12 @@ drivers/misc/mrvl_cn10k_dpi.c Driver IOCTLs ============= -:c:macro::`DPI_MPS_MRRS_CFG` +:c:macro:`DPI_MPS_MRRS_CFG` ioctl that sets max payload size & max read request size parameters of a pem port to which DMA engines are wired. -:c:macro::`DPI_ENGINE_CFG` +:c:macro:`DPI_ENGINE_CFG` ioctl that sets DMA engine's fifo sizes & max outstanding load request thresholds. diff --git a/Documentation/misc-devices/tps6594-pfsm.rst b/Documentation/misc-devices/tps6594-pfsm.rst index 4ada37ccdcba..5f17a4fd9579 100644 --- a/Documentation/misc-devices/tps6594-pfsm.rst +++ b/Documentation/misc-devices/tps6594-pfsm.rst @@ -39,28 +39,28 @@ include/uapi/linux/tps6594_pfsm.h Driver IOCTLs ============= -:c:macro::`PMIC_GOTO_STANDBY` +:c:macro:`PMIC_GOTO_STANDBY` All device resources are powered down. The processor is off, and no voltage domains are energized. -:c:macro::`PMIC_GOTO_LP_STANDBY` +:c:macro:`PMIC_GOTO_LP_STANDBY` The digital and analog functions of the PMIC, which are not required to be always-on, are turned off (low-power). -:c:macro::`PMIC_UPDATE_PGM` +:c:macro:`PMIC_UPDATE_PGM` Triggers a firmware update. -:c:macro::`PMIC_SET_ACTIVE_STATE` +:c:macro:`PMIC_SET_ACTIVE_STATE` One of the operational modes. The PMICs are fully functional and supply power to all PDN loads. All voltage domains are energized in both MCU and Main processor sections. -:c:macro::`PMIC_SET_MCU_ONLY_STATE` +:c:macro:`PMIC_SET_MCU_ONLY_STATE` One of the operational modes. Only the power resources assigned to the MCU Safety Island are on. -:c:macro::`PMIC_SET_RETENTION_STATE` +:c:macro:`PMIC_SET_RETENTION_STATE` One of the operational modes. Depending on the triggers set, some DDR/GPIO voltage domains can remain energized, while all other domains are off to minimize diff --git a/Documentation/misc-devices/uacce.rst b/Documentation/misc-devices/uacce.rst index 1db412e9b1a3..5f78d413e379 100644 --- a/Documentation/misc-devices/uacce.rst +++ b/Documentation/misc-devices/uacce.rst @@ -1,7 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 -Introduction of Uacce ---------------------- +Uacce (Unified/User-space-access-intended Accelerator Framework) +================================================================ + +Introduction +------------ Uacce (Unified/User-space-access-intended Accelerator Framework) targets to provide Shared Virtual Addressing (SVA) between accelerators and processes. diff --git a/Documentation/mm/active_mm.rst b/Documentation/mm/active_mm.rst index d096fc091e23..60d819d7d043 100644 --- a/Documentation/mm/active_mm.rst +++ b/Documentation/mm/active_mm.rst @@ -92,4 +92,4 @@ helpers, which abstract this config option. and register state is separate, the alpha PALcode joins the two, and you need to switch both together). - (From http://marc.info/?l=linux-kernel&m=93337278602211&w=2) + (From https://lore.kernel.org/lkml/Pine.LNX.4.10.9907301410280.752-100000@penguin.transmeta.com/) diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index ef3b116492df..7bd41838a546 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -13,24 +13,19 @@ how the process works is required in order to be an effective part of it. The big picture --------------- -The kernel developers use a loosely time-based release process, with a new -major kernel release happening every two or three months. The recent -release history looks like this: +The Linux kernel uses a loosely time-based, rolling release development +model. A new major kernel release (which we will call, as an example, 9.x) +[1]_ happens every two or three months, which comes with new features, +internal API changes, and more. A typical release can contain about 13,000 +changesets with changes to several hundred thousand lines of code. Recent +releases, along with their dates, can be found at `Wikipedia +`_. - ====== ================= - 5.0 March 3, 2019 - 5.1 May 5, 2019 - 5.2 July 7, 2019 - 5.3 September 15, 2019 - 5.4 November 24, 2019 - 5.5 January 6, 2020 - ====== ================= - -Every 5.x release is a major kernel release with new features, internal -API changes, and more. A typical release can contain about 13,000 -changesets with changes to several hundred thousand lines of code. 5.x is -the leading edge of Linux kernel development; the kernel uses a -rolling development model which is continually integrating major changes. +.. [1] Strictly speaking, the Linux kernel does not use semantic versioning + number scheme, but rather the 9.x pair identifies major release + version as a whole number. For each release, x is incremented, + but 9 is incremented only if x is deemed large enough (e.g. + Linux 5.0 is released following Linux 4.20). A relatively straightforward discipline is followed with regard to the merging of patches for each release. At the beginning of each development @@ -48,9 +43,9 @@ detail later on). The merge window lasts for approximately two weeks. At the end of this time, Linus Torvalds will declare that the window is closed and release the -first of the "rc" kernels. For the kernel which is destined to be 5.6, +first of the "rc" kernels. For the kernel which is destined to be 9.x, for example, the release which happens at the end of the merge window will -be called 5.6-rc1. The -rc1 release is the signal that the time to +be called 9.x-rc1. The -rc1 release is the signal that the time to merge new features has passed, and that the time to stabilize the next kernel has begun. @@ -99,13 +94,15 @@ release is made. In the real world, this kind of perfection is hard to achieve; there are just too many variables in a project of this size. There comes a point where delaying the final release just makes the problem worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 5.x -kernels go out with a handful of known regressions though, hopefully, none -of them are serious. +larger, creating even more regressions the next time around. So most kernels +go out with a handful of known regressions, though, hopefully, none of them +are serious. Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently Greg Kroah-Hartman. The stable team will release -occasional updates to the stable release using the 5.x.y numbering scheme. +"stable team," currently consists of Greg Kroah-Hartman and Sasha Levin. The +stable team will release occasional updates to the stable release using the +9.x.y numbering scheme. + To be considered for an update release, a patch must (1) fix a significant bug, and (2) already be merged into the mainline for the next development kernel. Kernels will typically receive stable updates for a little more diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index d1a8e5465ed9..2969ca378dbb 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -76,7 +76,7 @@ Don't use commas to avoid using braces: if (condition) do_this(), do_that(); -Always uses braces for multiple statements: +Always use braces for multiple statements: .. code-block:: c diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 910e8fc9e3c8..9a509f1a6873 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -592,8 +592,9 @@ Both Tested-by and Reviewed-by tags, once received on mailing list from tester or reviewer, should be added by author to the applicable patches when sending next versions. However if the patch has changed substantially in following version, these tags might not be applicable anymore and thus should be removed. -Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned -in the patch changelog (after the '---' separator). +Usually removal of someone's Acked-by, Tested-by or Reviewed-by tags should be +mentioned in the patch changelog with an explanation (after the '---' +separator). A Suggested-by: tag indicates that the patch idea is suggested by the person named and ensures credit to the person for the idea: if we diligently credit diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py index 4c4375201b9e..5667f207d175 100644 --- a/Documentation/sphinx/kernel_abi.py +++ b/Documentation/sphinx/kernel_abi.py @@ -14,7 +14,7 @@ :license: GPL Version 2, June 1991 see Linux/COPYING for details. The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the - scripts/get_abi.py script to parse the Kernel ABI files. + AbiParser class to parse the Kernel ABI files. Overview of directive's argument and options. @@ -43,9 +43,9 @@ from sphinx.util.docutils import switch_source_input from sphinx.util import logging srctree = os.path.abspath(os.environ["srctree"]) -sys.path.insert(0, os.path.join(srctree, "scripts/lib/abi")) +sys.path.insert(0, os.path.join(srctree, "tools/lib/python")) -from abi_parser import AbiParser +from abi.abi_parser import AbiParser __version__ = "1.0" diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index aaac76892ceb..bdc0fef5c87f 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -13,7 +13,7 @@ :license: GPL Version 2, June 1991 see Linux/COPYING for details. The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the - scripts/get_feat.pl script to parse the Kernel ABI files. + tools/docs/get_feat.pl script to parse the Kernel ABI files. Overview of directive's argument and options. @@ -34,7 +34,6 @@ import codecs import os import re -import subprocess import sys from docutils import nodes, statemachine @@ -42,6 +41,11 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from sphinx.util.docutils import switch_source_input +srctree = os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "tools/lib/python")) + +from feat.parse_features import ParseFeature # pylint: disable=C0413 + def ErrorString(exc): # Shamelessly stolen from docutils return f'{exc.__class__.__name}: {exc}' @@ -84,18 +88,16 @@ class KernelFeat(Directive): srctree = os.path.abspath(os.environ["srctree"]) - args = [ - os.path.join(srctree, 'scripts/get_feat.pl'), - 'rest', - '--enable-fname', - '--dir', - os.path.join(srctree, 'Documentation', self.arguments[0]), - ] + feature_dir = os.path.join(srctree, 'Documentation', self.arguments[0]) + + feat = ParseFeature(feature_dir, False, True) + feat.parse() if len(self.arguments) > 1: - args.extend(['--arch', self.arguments[1]]) - - lines = subprocess.check_output(args, cwd=os.path.dirname(doc.current_source)).decode('utf-8') + arch = self.arguments[1] + lines = feat.output_arch_table(arch) + else: + lines = feat.output_matrix() line_regex = re.compile(r"^\.\. FILE (\S+)$") diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index f94412cd17c9..626762ff6af3 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -87,6 +87,8 @@ import os.path import re import sys +from difflib import get_close_matches + from docutils import io, nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import Directive, directives @@ -95,15 +97,17 @@ from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from sphinx.util import logging srctree = os.path.abspath(os.environ["srctree"]) -sys.path.insert(0, os.path.join(srctree, "tools/docs/lib")) +sys.path.insert(0, os.path.join(srctree, "tools/lib/python")) -from parse_data_structs import ParseDataStructs +from kdoc.parse_data_structs import ParseDataStructs __version__ = "1.0" logger = logging.getLogger(__name__) RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\') RE_SIMPLE_REF = re.compile(r'`([^`]+)`') +RE_LINENO_REF = re.compile(r'^\s*-\s+LINENO_(\d+):\s+(.*)') +RE_SPLIT_DOMAIN = re.compile(r"(.*)\.(.*)") def ErrorString(exc): # Shamelessly stolen from docutils return f'{exc.__class__.__name}: {exc}' @@ -212,14 +216,16 @@ class KernelInclude(Directive): - a TOC table containing cross references. """ parser = ParseDataStructs() - parser.parse_file(path) if 'exception-file' in self.options: source_dir = os.path.dirname(os.path.abspath( self.state_machine.input_lines.source( self.lineno - self.state_machine.input_offset - 1))) exceptions_file = os.path.join(source_dir, self.options['exception-file']) - parser.process_exceptions(exceptions_file) + else: + exceptions_file = None + + parser.parse_file(path, exceptions_file) # Store references on a symbol dict to be used at check time if 'warn-broken' in self.options: @@ -242,23 +248,32 @@ class KernelInclude(Directive): # TOC output is a ReST file, not a literal. So, we can add line # numbers - rawtext = parser.gen_toc() - - include_lines = statemachine.string2lines(rawtext, tab_width, - convert_whitespace=True) - - # Append line numbers data - startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + + relpath = os.path.relpath(path, srctree) result = ViewList() - if startline and startline > 0: - offset = startline - 1 - else: - offset = 0 + for line in parser.gen_toc().split("\n"): + match = RE_LINENO_REF.match(line) + if not match: + result.append(line, path) + continue - for ln, line in enumerate(include_lines, start=offset): - result.append(line, path, ln) + ln, ref = match.groups() + ln = int(ln) + + # Filter line range if needed + if startline and (ln < startline): + continue + + if endline and (ln > endline): + continue + + # Sphinx numerates starting with zero, but text editors + # and other tools start from one + realln = ln + 1 + result.append(f"- {ref}: {relpath}#{realln}", path, ln) self.state_machine.insert_input(result, path) @@ -388,6 +403,63 @@ class KernelInclude(Directive): # ============================================================================== reported = set() +DOMAIN_INFO = {} +all_refs = {} + +def fill_domain_info(env): + """ + Get supported reference types for each Sphinx domain and C namespaces + """ + if DOMAIN_INFO: + return + + for domain_name, domain_instance in env.domains.items(): + try: + object_types = list(domain_instance.object_types.keys()) + DOMAIN_INFO[domain_name] = object_types + except AttributeError: + # Ignore domains that we can't retrieve object types, if any + pass + + for domain in DOMAIN_INFO.keys(): + domain_obj = env.get_domain(domain) + for name, dispname, objtype, docname, anchor, priority in domain_obj.get_objects(): + ref_name = name.lower() + + if domain == "c": + if '.' in ref_name: + ref_name = ref_name.split(".")[-1] + + if not ref_name in all_refs: + all_refs[ref_name] = [] + + all_refs[ref_name].append(f"\t{domain}:{objtype}:`{name}` (from {docname})") + +def get_suggestions(app, env, node, + original_target, original_domain, original_reftype): + """Check if target exists in the other domain or with different reftypes.""" + original_target = original_target.lower() + + # Remove namespace if present + if original_domain == "c": + if '.' in original_target: + original_target = original_target.split(".")[-1] + + suggestions = [] + + # If name exists, propose exact name match on different domains + if original_target in all_refs: + return all_refs[original_target] + + # If not found, get a close match, using difflib. + # Such method is based on Ratcliff-Obershelp Algorithm, which seeks + # for a close match within a certain distance. We're using the defaults + # here, e.g. cutoff=0.6, proposing 3 alternatives + matches = get_close_matches(original_target, all_refs.keys()) + for match in matches: + suggestions += all_refs[match] + + return suggestions def check_missing_refs(app, env, node, contnode): """Check broken refs for the files it creates xrefs""" @@ -404,11 +476,13 @@ def check_missing_refs(app, env, node, contnode): if node.source not in xref_files: return None + fill_domain_info(env) + target = node.get('reftarget', '') domain = node.get('refdomain', 'std') reftype = node.get('reftype', '') - msg = f"can't link to: {domain}:{reftype}:: {target}" + msg = f"Invalid xref: {domain}:{reftype}:`{target}`" # Don't duplicate warnings data = (node.source, msg) @@ -416,6 +490,10 @@ def check_missing_refs(app, env, node, contnode): return None reported.add(data) + suggestions = get_suggestions(app, env, node, target, domain, reftype) + if suggestions: + msg += ". Possible alternatives:\n" + '\n'.join(suggestions) + logger.warning(msg, location=node, type='ref', subtype='missing') return None diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty index 5d68395539fe..16d9ff46fdf6 100644 --- a/Documentation/sphinx/kerneldoc-preamble.sty +++ b/Documentation/sphinx/kerneldoc-preamble.sty @@ -220,7 +220,7 @@ 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}. + \sphinxcode{./tools/docs/sphinx-pre-install}. Having optional non-variable ``Noto Serif CJK'' font families will improve the looks of those translations. \end{sphinxadmonition}} diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 2586b4d4e494..d8cdf068ef35 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -42,10 +42,10 @@ from sphinx.util import logging from pprint import pformat srctree = os.path.abspath(os.environ["srctree"]) -sys.path.insert(0, os.path.join(srctree, "scripts/lib/kdoc")) +sys.path.insert(0, os.path.join(srctree, "tools/lib/python")) -from kdoc_files import KernelFiles -from kdoc_output import RestFormat +from kdoc.kdoc_files import KernelFiles +from kdoc.kdoc_output import RestFormat __version__ = '1.0' kfiles = None diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py deleted file mode 100644 index 1afb0c97f06b..000000000000 --- a/Documentation/sphinx/load_config.py +++ /dev/null @@ -1,60 +0,0 @@ -# -*- coding: utf-8; mode: python -*- -# SPDX-License-Identifier: GPL-2.0 -# pylint: disable=R0903, C0330, R0914, R0912, E0401 - -import os -import sys -from sphinx.util.osutil import fs_encoding - -# ------------------------------------------------------------------------------ -def loadConfig(namespace): -# ------------------------------------------------------------------------------ - - """Load an additional configuration file into *namespace*. - - The name of the configuration file is taken from the environment - ``SPHINX_CONF``. The external configuration file extends (or overwrites) the - configuration values from the origin ``conf.py``. With this you are able to - maintain *build themes*. """ - - config_file = os.environ.get("SPHINX_CONF", None) - if (config_file is not None - and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): - config_file = os.path.abspath(config_file) - - # Let's avoid one conf.py file just due to latex_documents - start = config_file.find('Documentation/') - if start >= 0: - start = config_file.find('/', start + 1) - - end = config_file.rfind('/') - if start >= 0 and end > 0: - dir = config_file[start + 1:end] - - print("source directory: %s" % dir) - new_latex_docs = [] - latex_documents = namespace['latex_documents'] - - for l in latex_documents: - if l[0].find(dir + '/') == 0: - has = True - fn = l[0][len(dir) + 1:] - new_latex_docs.append((fn, l[1], l[2], l[3], l[4])) - break - - namespace['latex_documents'] = new_latex_docs - - # If there is an extra conf.py file, load it - if os.path.isfile(config_file): - sys.stdout.write("load additional sphinx-config: %s\n" % config_file) - config = namespace.copy() - config['__file__'] = config_file - with open(config_file, 'rb') as f: - code = compile(f.read(), fs_encoding, 'exec') - exec(code, config) - del config['__file__'] - namespace.update(config) - else: - config = namespace.copy() - config['tags'].add("subproject") - namespace.update(config) diff --git a/Documentation/sphinx/parallel-wrapper.sh b/Documentation/sphinx/parallel-wrapper.sh deleted file mode 100644 index e54c44ce117d..000000000000 --- a/Documentation/sphinx/parallel-wrapper.sh +++ /dev/null @@ -1,33 +0,0 @@ -#!/bin/sh -# SPDX-License-Identifier: GPL-2.0+ -# -# Figure out if we should follow a specific parallelism from the make -# environment (as exported by scripts/jobserver-exec), or fall back to -# the "auto" parallelism when "-jN" is not specified at the top-level -# "make" invocation. - -sphinx="$1" -shift || true - -parallel="$PARALLELISM" -if [ -z "$parallel" ] ; then - # If no parallelism is specified at the top-level make, then - # fall back to the expected "-jauto" mode that the "htmldocs" - # target has had. - auto=$(perl -e 'open IN,"'"$sphinx"' --version 2>&1 |"; - while () { - if (m/([\d\.]+)/) { - print "auto" if ($1 >= "1.7") - } - } - close IN') - if [ -n "$auto" ] ; then - parallel="$auto" - fi -fi -# Only if some parallelism has been determined do we add the -jN option. -if [ -n "$parallel" ] ; then - parallel="-j$parallel" -fi - -exec "$sphinx" $parallel "$@" diff --git a/Documentation/tools/rtla/common_appendix.rst b/Documentation/tools/rtla/common_appendix.txt similarity index 100% rename from Documentation/tools/rtla/common_appendix.rst rename to Documentation/tools/rtla/common_appendix.txt diff --git a/Documentation/tools/rtla/common_hist_options.rst b/Documentation/tools/rtla/common_hist_options.txt similarity index 100% rename from Documentation/tools/rtla/common_hist_options.rst rename to Documentation/tools/rtla/common_hist_options.txt diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.txt similarity index 82% rename from Documentation/tools/rtla/common_options.rst rename to Documentation/tools/rtla/common_options.txt index 77ef35d3f831..1c4f3e663cf5 100644 --- a/Documentation/tools/rtla/common_options.rst +++ b/Documentation/tools/rtla/common_options.txt @@ -1,11 +1,15 @@ **-c**, **--cpus** *cpu-list* - Set the osnoise tracer to run the sample threads in the cpu-list. + Set the |tool| tracer to run the sample threads in the cpu-list. + + By default, the |tool| tracer runs the sample threads on all CPUs. **-H**, **--house-keeping** *cpu-list* Run rtla control threads only on the given cpu-list. + If omitted, rtla will attempt to auto-migrate its main thread to any CPU that is not running any workload threads. + **-d**, **--duration** *time[s|m|h|d]* Set the duration of the session. @@ -35,17 +39,21 @@ **-P**, **--priority** *o:prio|r:prio|f:prio|d:runtime:period* - Set scheduling parameters to the osnoise tracer threads, the format to set the priority are: + Set scheduling parameters to the |tool| tracer threads, the format to set the priority are: - *o:prio* - use SCHED_OTHER with *prio*; - *r:prio* - use SCHED_RR with *prio*; - *f:prio* - use SCHED_FIFO with *prio*; - *d:runtime[us|ms|s]:period[us|ms|s]* - use SCHED_DEADLINE with *runtime* and *period* in nanoseconds. + If not set, tracer threads keep their default priority. For rtla user threads, it is set to SCHED_FIFO with priority 95. For kernel threads, see *osnoise* and *timerlat* tracer documentation for the running kernel version. + **-C**, **--cgroup**\[*=cgroup*] Set a *cgroup* to the tracer's threads. If the **-C** option is passed without arguments, the tracer's thread will inherit **rtla**'s *cgroup*. Otherwise, the threads will be placed on the *cgroup* passed to the option. + If not set, the behavior differs between workload types. User workloads created by rtla will inherit rtla's cgroup. Kernel workloads are assigned the root cgroup. + **--warm-up** *s* After starting the workload, let it run for *s* seconds before starting collecting the data, allowing the system to warm-up. Statistical data generated during warm-up is discarded. @@ -53,6 +61,8 @@ **--trace-buffer-size** *kB* Set the per-cpu trace buffer size in kB for the tracing output. + If not set, the default tracefs buffer size is used. + **--on-threshold** *action* Defines an action to be executed when tracing is stopped on a latency threshold @@ -67,7 +77,7 @@ - *trace[,file=]* Saves trace output, optionally taking a filename. Alternative to -t/--trace. - Note that nlike -t/--trace, specifying this multiple times will result in + Note that unlike -t/--trace, specifying this multiple times will result in the trace being saved multiple times. - *signal,num=,pid=* diff --git a/Documentation/tools/rtla/common_osnoise_description.rst b/Documentation/tools/rtla/common_osnoise_description.txt similarity index 100% rename from Documentation/tools/rtla/common_osnoise_description.rst rename to Documentation/tools/rtla/common_osnoise_description.txt diff --git a/Documentation/tools/rtla/common_osnoise_options.rst b/Documentation/tools/rtla/common_osnoise_options.txt similarity index 100% rename from Documentation/tools/rtla/common_osnoise_options.rst rename to Documentation/tools/rtla/common_osnoise_options.txt diff --git a/Documentation/tools/rtla/common_timerlat_aa.rst b/Documentation/tools/rtla/common_timerlat_aa.txt similarity index 100% rename from Documentation/tools/rtla/common_timerlat_aa.rst rename to Documentation/tools/rtla/common_timerlat_aa.txt diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.txt similarity index 100% rename from Documentation/tools/rtla/common_timerlat_description.rst rename to Documentation/tools/rtla/common_timerlat_description.txt diff --git a/Documentation/tools/rtla/common_timerlat_options.rst b/Documentation/tools/rtla/common_timerlat_options.txt similarity index 95% rename from Documentation/tools/rtla/common_timerlat_options.rst rename to Documentation/tools/rtla/common_timerlat_options.txt index 1f5d024b53aa..33070b264cae 100644 --- a/Documentation/tools/rtla/common_timerlat_options.rst +++ b/Documentation/tools/rtla/common_timerlat_options.txt @@ -13,7 +13,7 @@ Set the automatic trace mode. This mode sets some commonly used options while debugging the system. It is equivalent to use **-T** *us* **-s** *us* **-t**. By default, *timerlat* tracer uses FIFO:95 for *timerlat* threads, - thus equilavent to **-P** *f:95*. + thus equivalent to **-P** *f:95*. **-p**, **--period** *us* @@ -56,7 +56,7 @@ **-u**, **--user-threads** Set timerlat to run without a workload, and then dispatches user-space workloads - to wait on the timerlat_fd. Once the workload is awakes, it goes to sleep again + to wait on the timerlat_fd. Once the workload is awakened, it goes to sleep again adding so the measurement for the kernel-to-user and user-to-kernel to the tracer output. **--user-threads** will be used unless the user specify **-k**. diff --git a/Documentation/tools/rtla/common_top_options.rst b/Documentation/tools/rtla/common_top_options.txt similarity index 100% rename from Documentation/tools/rtla/common_top_options.rst rename to Documentation/tools/rtla/common_top_options.txt diff --git a/Documentation/tools/rtla/rtla-hwnoise.rst b/Documentation/tools/rtla/rtla-hwnoise.rst index 3a7163c02ac8..26512b15fe7b 100644 --- a/Documentation/tools/rtla/rtla-hwnoise.rst +++ b/Documentation/tools/rtla/rtla-hwnoise.rst @@ -29,11 +29,11 @@ collection of the tracer output. OPTIONS ======= -.. include:: common_osnoise_options.rst +.. include:: common_osnoise_options.txt -.. include:: common_top_options.rst +.. include:: common_top_options.txt -.. include:: common_options.rst +.. include:: common_options.txt EXAMPLE ======= @@ -106,4 +106,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-osnoise-hist.rst b/Documentation/tools/rtla/rtla-osnoise-hist.rst index 1fc60ef26106..007521c865d9 100644 --- a/Documentation/tools/rtla/rtla-osnoise-hist.rst +++ b/Documentation/tools/rtla/rtla-osnoise-hist.rst @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_osnoise_description.rst +.. include:: common_osnoise_description.txt The **rtla osnoise hist** tool collects all **osnoise:sample_threshold** occurrence in a histogram, displaying the results in a user-friendly way. @@ -24,11 +24,11 @@ collection of the tracer output. OPTIONS ======= -.. include:: common_osnoise_options.rst +.. include:: common_osnoise_options.txt -.. include:: common_hist_options.rst +.. include:: common_hist_options.txt -.. include:: common_options.rst +.. include:: common_options.txt EXAMPLE ======= @@ -65,4 +65,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-osnoise-top.rst b/Documentation/tools/rtla/rtla-osnoise-top.rst index b1cbd7bcd4ae..6ccadae38945 100644 --- a/Documentation/tools/rtla/rtla-osnoise-top.rst +++ b/Documentation/tools/rtla/rtla-osnoise-top.rst @@ -15,7 +15,7 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_osnoise_description.rst +.. include:: common_osnoise_description.txt **rtla osnoise top** collects the periodic summary from the *osnoise* tracer, including the counters of the occurrence of the interference source, @@ -26,11 +26,11 @@ collection of the tracer output. OPTIONS ======= -.. include:: common_osnoise_options.rst +.. include:: common_osnoise_options.txt -.. include:: common_top_options.rst +.. include:: common_top_options.txt -.. include:: common_options.rst +.. include:: common_options.txt EXAMPLE ======= @@ -60,4 +60,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-osnoise.rst b/Documentation/tools/rtla/rtla-osnoise.rst index c129b206ce34..540d2bf6c152 100644 --- a/Documentation/tools/rtla/rtla-osnoise.rst +++ b/Documentation/tools/rtla/rtla-osnoise.rst @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_osnoise_description.rst +.. include:: common_osnoise_description.txt The *osnoise* tracer outputs information in two ways. It periodically prints a summary of the noise of the operating system, including the counters of @@ -56,4 +56,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-timerlat-hist.rst b/Documentation/tools/rtla/rtla-timerlat-hist.rst index 4923a362129b..f56fe546411b 100644 --- a/Documentation/tools/rtla/rtla-timerlat-hist.rst +++ b/Documentation/tools/rtla/rtla-timerlat-hist.rst @@ -16,7 +16,7 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_timerlat_description.rst +.. include:: common_timerlat_description.txt The **rtla timerlat hist** displays a histogram of each tracer event occurrence. This tool uses the periodic information, and the @@ -25,13 +25,13 @@ occurrence. This tool uses the periodic information, and the OPTIONS ======= -.. include:: common_timerlat_options.rst +.. include:: common_timerlat_options.txt -.. include:: common_hist_options.rst +.. include:: common_hist_options.txt -.. include:: common_options.rst +.. include:: common_options.txt -.. include:: common_timerlat_aa.rst +.. include:: common_timerlat_aa.txt EXAMPLE ======= @@ -110,4 +110,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-timerlat-top.rst b/Documentation/tools/rtla/rtla-timerlat-top.rst index 50968cdd2095..72d85e36c193 100644 --- a/Documentation/tools/rtla/rtla-timerlat-top.rst +++ b/Documentation/tools/rtla/rtla-timerlat-top.rst @@ -16,23 +16,23 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_timerlat_description.rst +.. include:: common_timerlat_description.txt The **rtla timerlat top** displays a summary of the periodic output from the *timerlat* tracer. It also provides information for each operating system noise via the **osnoise:** tracepoints that can be -seem with the option **-T**. +seen with the option **-T**. OPTIONS ======= -.. include:: common_timerlat_options.rst +.. include:: common_timerlat_options.txt -.. include:: common_top_options.rst +.. include:: common_top_options.txt -.. include:: common_options.rst +.. include:: common_options.txt -.. include:: common_timerlat_aa.rst +.. include:: common_timerlat_aa.txt **--aa-only** *us* @@ -133,4 +133,4 @@ AUTHOR ------ Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla-timerlat.rst b/Documentation/tools/rtla/rtla-timerlat.rst index 20e2d259467f..ce9f57e038c3 100644 --- a/Documentation/tools/rtla/rtla-timerlat.rst +++ b/Documentation/tools/rtla/rtla-timerlat.rst @@ -14,7 +14,7 @@ SYNOPSIS DESCRIPTION =========== -.. include:: common_timerlat_description.rst +.. include:: common_timerlat_description.txt The **rtla timerlat top** mode displays a summary of the periodic output from the *timerlat* tracer. The **rtla timerlat hist** mode displays @@ -51,4 +51,4 @@ AUTHOR ====== Written by Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/tools/rtla/rtla.rst b/Documentation/tools/rtla/rtla.rst index fc0d233efcd5..2a5fb7004ad4 100644 --- a/Documentation/tools/rtla/rtla.rst +++ b/Documentation/tools/rtla/rtla.rst @@ -45,4 +45,4 @@ AUTHOR ====== Daniel Bristot de Oliveira -.. include:: common_appendix.rst +.. include:: common_appendix.txt diff --git a/Documentation/trace/timerlat-tracer.rst b/Documentation/trace/timerlat-tracer.rst index 53a56823e903..68d429d454a5 100644 --- a/Documentation/trace/timerlat-tracer.rst +++ b/Documentation/trace/timerlat-tracer.rst @@ -43,12 +43,12 @@ It is possible to follow the trace by reading the trace file:: <...>-868 [001] .... 54.030347: #2 context thread timer_latency 4351 ns -The tracer creates a per-cpu kernel thread with real-time priority that -prints two lines at every activation. The first is the *timer latency* -observed at the *hardirq* context before the activation of the thread. -The second is the *timer latency* observed by the thread. The ACTIVATION -ID field serves to relate the *irq* execution to its respective *thread* -execution. +The tracer creates a per-cpu kernel thread with real-time priority +SCHED_FIFO:95 that prints two lines at every activation. The first is +the *timer latency* observed at the *hardirq* context before the activation +of the thread. The second is the *timer latency* observed by the thread. +The ACTIVATION ID field serves to relate the *irq* execution to its +respective *thread* execution. The *irq*/*thread* splitting is important to clarify in which context the unexpected high value is coming from. The *irq* context can be diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst index 026a23e49767..b0caa40fe1e9 100644 --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -13,28 +13,28 @@ dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi d'avviso se un simbolo non viene trovato nella documentazione. Questo permette di mantenere allineate la documentazione della uAPI (API spazio utente) con le modifiche del kernel. -Il programma :ref:`parse_headers.pl ` genera questi riferimenti. +Il programma :ref:`parse_headers.py ` genera questi riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera la documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel consultate ``Documentation/userspace-api/media/Makefile``. .. _it_parse_headers: -parse_headers.pl +parse_headers.py ^^^^^^^^^^^^^^^^ NOME **** -parse_headers.pl - analizza i file C al fine di identificare funzioni, +parse_headers.py - analizza i file C al fine di identificare funzioni, strutture, enumerati e definizioni, e creare riferimenti per Sphinx SINTASSI ******** -\ **parse_headers.pl**\ [] [] +\ **parse_headers.py**\ [] [] Dove può essere: --debug, --usage o --help. diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 1f513bc33618..a5c5d935febf 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -109,7 +109,7 @@ Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora sarà in grado di darvi dei suggerimenti su come procedere per completare l'installazione:: - $ ./scripts/sphinx-pre-install + $ ./tools/docs/sphinx-pre-install Checking if the needed tools for Fedora release 26 (Twenty Six) are available Warning: better to also install "texlive-luatex85". You should run: @@ -119,7 +119,7 @@ l'installazione:: . sphinx_2.4.4/bin/activate pip install -r Documentation/sphinx/requirements.txt - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + Can't build as 1 mandatory dependency is missing at ./tools/docs/sphinx-pre-install line 468. L'impostazione predefinita prevede il controllo dei requisiti per la generazione di documenti html e PDF, includendo anche il supporto per le immagini, le diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 5334db471744..b950347b5993 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -132,6 +132,25 @@ http://savannah.nongnu.org/projects/quilt platform_set_drvdata(), but left the variable "dev" unused, delete it. +特定のコミットで導入された不具合を修正する場合（例えば ``git bisect`` で原因となった +コミットを特定したときなど）は、コミットの SHA-1 の先頭12文字と1行の要約を添えた +「Fixes:」タグを付けてください。この行は75文字を超えても構いませんが、途中で +改行せず、必ず1行で記述してください。 +例: + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +以下の git の設定を使うと、git log や git show で上記形式を出力するための +専用の出力形式を追加できます:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +使用例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") 3) パッチの分割 @@ -409,7 +428,7 @@ Acked-by: が必ずしもパッチ全体の承認を示しているわけでは このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと を明文化します。 -14) Reported-by:, Tested-by:, Reviewed-by: および Suggested-by: の利用 +14) Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: および Fixes: の利用 他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を クレジットするために、Reported-by: タグを追加することを検討してください。 @@ -465,6 +484,13 @@ Suggested-by: タグは、パッチのアイデアがその人からの提案に クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に なってくれるかもしれません。 +Fixes: タグは、そのパッチが以前のコミットにあった問題を修正することを示します。 +これは、バグがどこで発生したかを特定しやすくし、バグ修正のレビューに役立ちます。 +また、このタグはstableカーネルチームが、あなたの修正をどのstableカーネル +バージョンに適用すべきか判断する手助けにもなります。パッチによって修正された +バグを示すには、この方法が推奨されます。前述の、「2) パッチに対する説明」の +セクションを参照してください。 + 15) 標準的なパッチのフォーマット 標準的なパッチのサブジェクトは以下のとおりです。 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index 82e628b77efd..7c2ffe7e87c7 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -288,4 +288,4 @@ Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 更多用GDB调试内核的信息，请参阅： Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst -和 Documentation/dev-tools/kgdb.rst 。 +和 Documentation/process/debugging/kgdb.rst 。 diff --git a/Documentation/translations/zh_CN/block/blk-mq.rst b/Documentation/translations/zh_CN/block/blk-mq.rst new file mode 100644 index 000000000000..ccc08f76ff97 --- /dev/null +++ b/Documentation/translations/zh_CN/block/blk-mq.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/block/blk-mq.rst + +:翻译: + + 柯子杰 kezijie + +:校译: + + + +================================================ +多队列块设备 I/O 排队机制 (blk-mq) +================================================ + +多队列块设备 I/O 排队机制提供了一组 API，使高速存储设备能够同时在多个队列中 +处理并发的 I/O 请求并将其提交到块设备，从而实现极高的每秒输入/输出操作次数 +(IOPS)，充分发挥现代存储设备的并行能力。 + +介绍 +==== + +背景 +---- + +磁盘从 Linux 内核开发初期就已成为事实上的标准。块 I/O 子系统的目标是尽可能 +为此类设备提供最佳性能，因为它们在进行随机访问时代价极高，性能瓶颈主要在机械 +运动部件上，其速度远低于存储栈中其他任何层。其中一个软件优化例子是根据硬盘磁 +头当前的位置重新排序读/写请求。 + +然而，随着固态硬盘和非易失性存储的发展，它们没有机械部件，也不存在随机访问代 +码，并能够进行高速并行访问，存储栈的瓶颈从存储设备转移到了操作系统。为了充分 +利用这些设备设计中的并行性，引入了多队列机制。 + +原来的设计只有一个队列来存储块设备 I/O 请求，并且只使用一个锁。由于缓存中的 +脏数据和多处理器共享单锁的瓶颈，这种设计在 SMP 系统中扩展性不佳。当不同进程 +（或同一进程在不同 CPU 上）同时执行块设备 I/O 时，该单队列模型还会出现严重 +的拥塞问题。为了解决这些问题，blk-mq API 引入了多个队列，每个队列在本地 CPU +上拥有独立的入口点，从而消除了对全局锁的需求。关于其具体工作机制的更深入说明， +请参见下一节（ `工作原理`_ ）。 + +工作原理 +-------- + +当用户空间执行对块设备的 I/O（例如读写文件）时，blk-mq 便会介入：它将存储和 +管理发送到块设备的 I/O 请求，充当用户空间（文件系统，如果存在的话）与块设备驱 +动之间的中间层。 + +blk-mq 由两组队列组成：软件暂存队列和硬件派发队列。当请求到达块层时，它会尝 +试最短路径：直接发送到硬件队列。然而，有两种情况下可能不会这样做：如果该层有 +IO 调度器或者是希望合并请求。在这两种情况下，请求将被发送到软件队列。 + +随后，在软件队列中的请求被处理后，请求会被放置到硬件队列。硬件队列是第二阶段 +的队列，硬件可以直接访问并处理这些请求。然而，如果硬件没有足够的资源来接受更 +多请求，blk-mq 会将请求放置在临时队列中，待硬件资源充足时再发送。 + +软件暂存队列 +~~~~~~~~~~~~ + +在这些请求未直接发送到驱动时，块设备 I/O 子系统会将请求添加到软件暂存队列中 +（由 struct blk_mq_ctx 表示）。一个请求可能包含一个或多个 BIO。它们通过 struct bio +数据结构到达块层。块层随后会基于这些 BIO 构建新的结构体 struct request，用于 +与设备驱动通信。每个队列都有自己的锁，队列数量由每个 CPU 和每个 node 为基础 +来决定。 + +暂存队列可用于合并相邻扇区的请求。例如，对扇区3-6、6-7、7-9的请求可以合并 +为对扇区3-9的一个请求。即便 SSD 或 NVM 的随机访问和顺序访问响应时间相同， +合并顺序访问的请求仍可减少单独请求的数量。这种合并请求的技术称为 plugging。 + +此外，I/O 调度器还可以对请求进行重新排序以确保系统资源的公平性（例如防止某 +个应用出现“饥饿”现象）或是提高 I/O 性能。 + +I/O 调度器 +^^^^^^^^^^ + +块层实现了多种调度器，每种调度器都遵循一定启发式规则以提高 I/O 性能。它们是 +“可插拔”的(plug and play)，可在运行时通过 sysfs 选择。你可以在这里阅读更 +多关于 Linux IO 调度器知识 `here +`_。调度只发 +生在同一队列内的请求之间，因此无法合并不同队列的请求，否则会造成缓存冲突并需 +要为每个队列加锁。调度后，请求即可发送到硬件。可能选择的调度器之一是 NONE 调 +度器，这是最直接的调度器：它只将请求放到进程所在的软件队列，不进行重新排序。 +当设备开始处理硬件队列中的请求时（运行硬件队列），映射到该硬件队列的软件队列 +会按映射顺序依次清空。 + +硬件派发队列 +~~~~~~~~~~~~~ + +硬件队列（由 struct blk_mq_hw_ctx 表示）是设备驱动用来映射设备提交队列 +（或设备 DMA 环缓存）的结构体，它是块层提交路径在底层设备驱动接管请求之前的 +最后一个阶段。运行此队列时，块层会从相关软件队列中取出请求，并尝试派发到硬件。 + +如果请求无法直接发送到硬件，它们会被加入到请求的链表(``hctx->dispatch``) 中。 +随后，当块层下次运行该队列时，会优先发送位于 ``dispatch`` 链表中的请求， +以确保那些最早准备好发送的请求能够得到公平调度。硬件队列的数量取决于硬件及 +其设备驱动所支持的硬件上下文数，但不会超过系统的CPU核心数。在这个阶段不 +会发生重新排序，每个软件队列都有一组硬件队列来用于提交请求。 + +.. note:: + + 块层和设备协议都不保证请求完成顺序。此问题需由更高层处理，例如文件系统。 + +基于标识的完成机制 +~~~~~~~~~~~~~~~~~~~ + +为了指示哪一个请求已经完成，每个请求都会被分配一个整数标识，该标识的取值范围 +是从0到分发队列的大小。这个标识由块层生成，并在之后由设备驱动使用，从而避 +免了为每个请求再单独创建冗余的标识符。当请求在驱动中完成时，驱动会将该标识返 +回给块层，以通知该请求已完成。这样，块层就无需再进行线性搜索来确定是哪一个 +I/O 请求完成了。 + +更多阅读 +-------- + +- `Linux 块 I/O：多队列 SSD 并发访问简介 `_ + +- `NOOP 调度器 `_ + +- `Null 块设备驱动程序 `_ + +源代码 +====== + +该API在以下内核代码中: + +include/linux/blk-mq.h + +block/blk-mq.c \ No newline at end of file diff --git a/Documentation/translations/zh_CN/block/data-integrity.rst b/Documentation/translations/zh_CN/block/data-integrity.rst new file mode 100644 index 000000000000..b31aa9ef8954 --- /dev/null +++ b/Documentation/translations/zh_CN/block/data-integrity.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/block/data-integrity.rst + +:翻译: + + 柯子杰 kezijie + +:校译: + +========== +数据完整性 +========== + +1. 引言 +======= + +现代文件系统对数据和元数据都进行了校验和保护以防止数据损坏。然而，这种损坏的 +检测是在读取时才进行，这可能发生在数据写入数月之后。到那时，应用程序尝试写入 +的原始数据很可能已经丢失。 + +解决方案是确保磁盘实际存储的内容就是应用程序想存储的。SCSI 协议族（如 SBC +数据完整性字段、SCC 保护提案）以及 SATA/T13（外部路径保护）最近新增的功能， +通过在 I/O 中附加完整性元数据的方式，试图解决这一问题。完整性元数据（在 +SCSI 术语中称为保护信息）包括每个扇区的校验和，以及一个递增计数器，用于确保 +各扇区按正确顺序被写入盘。在某些保护方案中，还能保证 I/O 写入磁盘的正确位置。 + +当前的存储控制器和设备实现了多种保护措施，例如校验和和数据清理。但这些技术通 +常只在各自的独立域内工作，或最多仅在 I/O 路径的相邻节点之间发挥作用。DIF 及 +其它数据完整性拓展有意思的点在于保护格式定义明确，I/O 路径上的每个节点都可以 +验证 I/O 的完整性，如检测到损坏可直接拒绝。这不仅可以防止数据损坏，还能够隔 +离故障点。 + +2. 数据完整性拓展 +================= + +如上所述，这些协议扩展只保护控制器与存储设备之间的路径。然而，许多控制器实际 +上允许操作系统与完整性元数据(IMD)交互。我们一直与多家 FC/SAS HBA 厂商合作， +使保护信息能够在其控制器与操作系统之间传输。 + +SCSI 数据完整性字段通过在每个扇区后附加8字节的保护信息来实现。数据 + 完整 +性元数据存储在磁盘的520字节扇区中。数据 + IMD 在控制器与目标设备之间传输 +时是交错组合在一起的。T13 提案的方式类似。 + +由于操作系统处理520字节（甚至 4104 字节）扇区非常不便，我们联系了多家 HBA +厂商，并鼓励它们分离数据与完整性元数据的 scatter-gather lists。 + +控制器在写入时会将数据缓冲区和完整性元数据缓冲区的数据交错在一起，并在读取时 +会拆分它们。这样，Linux 就能直接通过 DMA 将数据缓冲区传输到主机内存或从主机 +内存读取，而无需修改页缓存。 + +此外，SCSI 与 SATA 规范要求的16位 CRC 校验在软件中计算代价较高。基准测试发 +现，计算此校验在高负载情形下显著影响系统性能。一些控制器允许在操作系统接口处 +使用轻量级校验。例如 Emulex 支持 TCP/IP 校验。操作系统提供的 IP 校验在写入 +时会转换为16位 CRC，读取时则相反。这允许 Linux 或应用程序以极低的开销生成 +完整性元数据（与软件 RAID5 相当）。 + +IP 校验在检测位错误方面比 CRC 弱，但关键在于数据缓冲区与完整性元数据缓冲区 +的分离。只有这两个不同的缓冲区匹配，I/O 才能完成。 + +数据与完整性元数据缓冲区的分离以及校验选择被称为数据完整性扩展。由于这些扩展 +超出了协议主体(T10、T13)的范围，Oracle 及其合作伙伴正尝试在存储网络行业协 +会内对其进行标准化。 + +3. 内核变更 +=========== + +Linux 中的数据完整性框架允许将保护信息固定到 I/O 上，并在支持该功能的控制器 +之间发送和接收。 + +SCSI 和 SATA 中完整性扩展的优势在于，它们能够保护从应用程序到存储设备的整个 +路径。然而，这同时也是最大的劣势。这意味着保护信息必须采用磁盘可以理解的格式。 + +通常，Linux/POSIX 应用程序并不关心所访问存储设备的具体细节。虚拟文件系统层 +和块层会让硬件扇区大小和传输协议对应用程序完全透明。 + +然而，在准备发送到磁盘的保护信息时，就需要这种细节。因此，端到端保护方案的概 +念实际上违反了层次结构。应用程序完全不应该知道它访问的是 SCSI 还是 SATA 磁盘。 + +Linux 中实现的数据完整性支持尝试将这些细节对应用程序隐藏。就应用程序（以及在 +某种程度上内核）而言，完整性元数据是附加在 I/O 上的不透明信息。 + +当前实现允许块层自动为任何 I/O 生成保护信息。最终目标是将用户数据的完整性元 +数据计算移至用户空间。内核中产生的元数据和其他 I/O 仍将使用自动生成接口。 + +一些存储设备允许为每个硬件扇区附加一个16位的标识值。这个标识空间的所有者是 +块设备的所有者，也就是在多数情况下由文件系统掌控。文件系统可以利用这额外空间 +按需为扇区附加标识。由于标识空间有限，块接口允许通过交错方式对更大的数据块标 +识。这样，8*16位的信息可以附加到典型的 4KB 文件系统块上。 + +这也意味着诸如 fsck 和 mkfs 等应用程序需要能够从用户空间访问并操作这些标记。 +为此，正在开发一个透传接口。 + +4. 块层实现细节 +=============== + +4.1 Bio +-------- + +当启用 CONFIG_BLK_DEV_INTEGRITY 时，数据完整性补丁会在 struct bio 中添加 +一个新字段。调用 bio_integrity(bio) 会返回一个指向 struct bip 的指针，该 +结构体包含了该 bio 的完整性负载。本质上，bip 是一个精简版的 struct bio，其 +中包含一个 bio_vec，用于保存完整性元数据以及所需的维护信息（bvec 池、向量计 +数等）。 + +内核子系统可以通过调用 bio_integrity_alloc(bio) 来为某个 bio 启用数据完整 +性保护。该函数会分配并附加一个 bip 到该 bio 上。 + +随后使用 bio_integrity_add_page() 将包含完整性元数据的单独页面附加到该 bio。 + +调用 bio_free() 会自动释放bip。 + +4.2 块设备 +----------- + +块设备可以在 queue_limits 结构中的 integrity 子结构中设置完整性信息。 + +对于分层块设备，需要选择一个适用于所有子设备的完整性配置文件。可以使用 +queue_limits_stack_integrity() 来协助完成该操作。目前，DM 和 MD linear、 +RAID0 和 RAID1 已受支持。而RAID4/5/6因涉及应用标签仍需额外的开发工作。 + +5.0 块层完整性API +================== + +5.1 普通文件系统 +----------------- + + 普通文件系统并不知道其下层块设备具备发送或接收完整性元数据的能力。 + 在执行写操作时，块层会在调用 submit_bio() 时自动生成完整性元数据。 + 在执行读操作时，I/O 完成后会触发完整性验证。 + + IMD 的生成与验证行为可以通过以下开关控制:: + + /sys/block//integrity/write_generate + + and:: + + /sys/block//integrity/read_verify + + flags. + +5.2 具备完整性感知的文件系统 +---------------------------- + + 具备完整性感知能力的文件系统可以在准备 I/O 时附加完整性元数据， + 并且如果底层块设备支持应用标签空间，也可以加以利用。 + + + `bool bio_integrity_prep(bio);` + + 要为写操作生成完整性元数据或为读操作设置缓冲区，文件系统必须调用 + bio_integrity_prep(bio)。 + + 在调用此函数之前，必须先设置好 bio 的数据方向和起始扇区，并确 + 保该 bio 已经添加完所有的数据页。调用者需要自行保证，在 I/O 进行 + 期间 bio 不会被修改。如果由于某种原因准备失败，则应当以错误状态 + 完成该 bio。 + +5.3 传递已有的完整性元数据 +-------------------------- + + 能够自行生成完整性元数据或可以从用户空间传输完整性元数据的文件系统， + 可以使用如下接口： + + + `struct bip * bio_integrity_alloc(bio, gfp_mask, nr_pages);` + + 为 bio 分配完整性负载并挂载到 bio 上。nr_pages 表示需要在 + integrity bio_vec list 中存储多少页保护数据（类似 bio_alloc）。 + + 完整性负载将在 bio_free() 被调用时释放。 + + + `int bio_integrity_add_page(bio, page, len, offset);` + + 将包含完整性元数据的一页附加到已有的 bio 上。该 bio 必须已有 bip， + 即必须先调用 bio_integrity_alloc()。对于写操作，页中的完整 + 性元数据必须采用目标设备可识别的格式，但有一个例外，当请求在 I/O 栈 + 中传递时，扇区号会被重新映射。这意味着通过此接口添加的页在 I/O 过程 + 中可能会被修改！完整性元数据中的第一个引用标签必须等于 bip->bip_sector。 + + 只要 bip bio_vec array（nr_pages）有空间，就可以继续通过 + bio_integrity_add_page()添加页。 + + 当读操作完成后，附加的页将包含从存储设备接收到的完整性元数据。 + 接收方需要处理这些元数据，并在操作完成时验证数据完整性 + + +---------------------------------------------------------------------- + +2007-12-24 Martin K. Petersen \ No newline at end of file diff --git a/Documentation/translations/zh_CN/block/index.rst b/Documentation/translations/zh_CN/block/index.rst new file mode 100644 index 000000000000..f2ae5096ed68 --- /dev/null +++ b/Documentation/translations/zh_CN/block/index.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/block/index.rst + +:翻译: + + 柯子杰 ke zijie + +:校译: + +===== +Block +===== + +.. toctree:: + :maxdepth: 1 + + blk-mq + data-integrity + +TODOList: +* bfq-iosched +* biovecs +* cmdline-partition +* deadline-iosched +* inline-encryption +* ioprio +* kyber-iosched +* null_blk +* pr +* stat +* switching-sched +* writeback_cache_control +* ublk diff --git a/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst index 282aacd33442..0b382a32b3fe 100644 --- a/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/dev-tools/gdb-kernel-debugging.rst +:Original: Documentation/process/debugging/gdb-kernel-debugging.rst :Translator: 高超 gao chao 通过gdb调试内核和模块 diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst index d20b4ce66b9f..dbfd65398077 100644 --- a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst @@ -28,15 +28,15 @@ :: - ./scripts/checktransupdate.py --help + tools/docs/checktransupdate.py --help 具体用法请参考参数解析器的输出 示例 -- ``./scripts/checktransupdate.py -l zh_CN`` +- ``tools/docs/checktransupdate.py -l zh_CN`` 这将打印 zh_CN 语言中需要更新的所有文件。 -- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` +- ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` 这将只打印指定文件的状态。 然后输出类似如下的内容： diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst index 394a13b438b0..b0c8ba782b16 100644 --- a/Documentation/translations/zh_CN/doc-guide/contributing.rst +++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst @@ -124,7 +124,7 @@ C代码编译器发出的警告常常会被视为误报，从而导致出现了 这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc`` 指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。 -``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。 +``tools/docs/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。 请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部 使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中， diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst index a08819e904ed..65d9dc5143ff 100644 --- a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -13,20 +13,20 @@ 有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例 C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号， Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 -:ref:`parse_headers.pl ` 提供了生成此类交叉引用的一种方法。 +:ref:`parse_headers.py ` 提供了生成此类交叉引用的一种方法。 在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅 ``Documentation/userspace-api/media/Makefile`` 。 .. _parse_headers_zh: -parse_headers.pl +parse_headers.py ---------------- 脚本名称 ~~~~~~~~ -parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 +parse_headers.py——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 创建交叉引用。 @@ -34,7 +34,7 @@ parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、 ~~~~~~~~ -\ **parse_headers.pl**\ [<选项>] <输出文件> [<例外文件>] +\ **parse_headers.py**\ [<选项>] <输出文件> [<例外文件>] <选项> 可以是： --debug, --help 或 --usage 。 diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst index 23eac67fbc30..3375c6f3a811 100644 --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -84,7 +84,7 @@ PDF和LaTeX构建 这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行 版的安装命令:: - $ ./scripts/sphinx-pre-install + $ ./tools/docs/sphinx-pre-install Checking if the needed tools for Fedora release 26 (Twenty Six) are available Warning: better to also install "texlive-luatex85". You should run: @@ -94,7 +94,7 @@ PDF和LaTeX构建 . sphinx_2.4.4/bin/activate pip install -r Documentation/sphinx/requirements.txt - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + Can't build as 1 mandatory dependency is missing at ./tools/docs/sphinx-pre-install line 468. 默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的 需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依 diff --git a/Documentation/translations/zh_CN/filesystems/dnotify.rst b/Documentation/translations/zh_CN/filesystems/dnotify.rst new file mode 100644 index 000000000000..5ab109b9424c --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/dnotify.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/dnotify.rst + +:翻译: + + 王龙杰 Wang Longjie + +============== +Linux 目录通知 +============== + + Stephen Rothwell + +目录通知的目的是使用户应用程序能够在目录或目录中的任何文件发生变更时收到通知。基本机制包括应用程序 +通过 fcntl(2) 调用在目录上注册通知，通知本身则通过信号传递。 + +应用程序可以决定希望收到哪些 “事件” 的通知。当前已定义的事件如下： + + ========= ===================================== + DN_ACCESS 目录中的文件被访问（read） + DN_MODIFY 目录中的文件被修改（write,truncate） + DN_CREATE 目录中创建了文件 + DN_DELETE 目录中的文件被取消链接 + DN_RENAME 目录中的文件被重命名 + DN_ATTRIB 目录中的文件属性被更改（chmod,chown） + ========= ===================================== + +通常，应用程序必须在每次通知后重新注册，但如果将 DN_MULTISHOT 与事件掩码进行或运算，则注册 +将一直保持有效，直到被显式移除（通过注册为不接收任何事件）。 + +默认情况下，SIGIO 信号将被传递给进程，且不附带其他有用的信息。但是，如果使用 F_SETSIG fcntl(2) +调用让内核知道要传递哪个信号，一个 siginfo 结构体将被传递给信号处理程序，该结构体的 si_fd 成员将 +包含与发生事件的目录相关联的文件描述符。 + +应用程序最好选择一个实时信号（SIGRTMIN + ），以便通知可以被排队。如果指定了 DN_MULTISHOT， +这一点尤为重要。注意，SIGRTMIN 通常是被阻塞的，因此最好使用（至少）SIGRTMIN + 1。 + +实现预期（特性与缺陷 :-)） +-------------------------- + +对于文件的任何本地访问，通知都应能正常工作，即使实际文件系统位于远程服务器上。这意味着，对本地用户 +模式服务器提供的文件的远程访问应能触发通知。同样的，对本地内核 NFS 服务器提供的文件的远程访问 +也应能触发通知。 + +为了尽可能减小对文件系统代码的影响，文件硬链接的问题已被忽略。因此，如果一个文件（x）存在于两个 +目录（a 和 b）中，通过名称”a/x”对该文件进行的更改应通知给期望接收目录“a”通知的程序，但不会 +通知给期望接收目录“b”通知的程序。 + +此外，取消链接的文件仍会在它们链接到的最后一个目录中触发通知。 + +配置 +---- + +Dnotify 由 CONFIG_DNOTIFY 配置选项控制。禁用该选项时，fcntl(fd, F_NOTIFY, ...) 将返 +回 -EINVAL。 + +示例 +---- +具体示例可参见 tools/testing/selftests/filesystems/dnotify_test.c。 + +注意 +---- +从 Linux 2.6.13 开始，dnotify 已被 inotify 取代。有关 inotify 的更多信息，请参见 +Documentation/filesystems/inotify.rst。 diff --git a/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst b/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst new file mode 100644 index 000000000000..abfd2f2f94e9 --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/gfs2-glocks.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/gfs2-glocks.rst + +:翻译: + + 邵明寅 Shao Mingyin + +:校译: + + 杨涛 yang tao + +================== +Glock 内部加锁规则 +================== + +本文档阐述 glock 状态机内部运作的基本原理。每个 glock（即 +fs/gfs2/incore.h 中的 struct gfs2_glock）包含两把主要的内部锁： + + 1. 自旋锁（gl_lockref.lock）：用于保护内部状态（如 + gl_state、gl_target）和持有者列表（gl_holders） + 2. 非阻塞的位锁（GLF_LOCK）：用于防止其他线程同时调用 + DLM 等操作。若某线程获取此锁，则在释放时必须调用 + run_queue（通常通过工作队列），以确保所有待处理任务 + 得以完成。 + +gl_holders 列表包含与该 glock 关联的所有排队锁请求（不 +仅是持有者）。若存在已持有的锁，它们将位于列表开头的连 +续条目中。锁的授予严格遵循排队顺序。 + +glock 层用户可请求三种锁状态：共享（SH）、延迟（DF）和 +排他（EX）。它们对应以下 DLM 锁模式： + +========== ====== ===================================================== +Glock 模式 DLM 锁模式 +========== ====== ===================================================== + UN IV/NL 未加锁（无关联的 DLM 锁）或 NL + SH PR 受保护读（Protected read） + DF CW 并发写（Concurrent write） + EX EX 排他（Exclusive） +========== ====== ===================================================== + +因此，DF 本质上是一种与“常规”共享锁模式（SH）互斥的共 +享模式。在 GFS2 中，DF 模式专用于直接 I/O 操作。Glock +本质上是锁加缓存管理例程的组合，其缓存规则如下： + +========== ============== ========== ========== ============== +Glock 模式 缓存元数据 缓存数据 脏数据 脏元数据 +========== ============== ========== ========== ============== + UN 否 否 否 否 + DF 是 否 否 否 + SH 是 是 否 否 + EX 是 是 是 是 +========== ============== ========== ========== ============== + +这些规则通过为每种 glock 定义的操作函数实现。并非所有 +glock 类型都使用全部的模式，例如仅 inode glock 使用 DF 模 +式。 + +glock 操作函数及类型常量说明表： + +============== ======================================================== +字段 用途 +============== ======================================================== +go_sync 远程状态变更前调用（如同步脏数据） +go_xmote_bh 远程状态变更后调用（如刷新缓存） +go_inval 远程状态变更需使缓存失效时调用 +go_instantiate 获取 glock 时调用 +go_held 每次获取 glock 持有者时调用 +go_dump 为 debugfs 文件打印对象内容，或出错时将 glock 转储至日志 +go_callback 若 DLM 发送回调以释放此锁时调用 +go_unlocked 当 glock 解锁时调用（dlm_unlock()） +go_type glock 类型，``LM_TYPE_*`` +go_flags 若 glock 关联地址空间，则设置GLOF_ASPACE 标志 +============== ======================================================== + +每种锁的最短持有时间是指在远程锁授予后忽略远程降级请求 +的时间段。此举旨在防止锁在集群节点间持续弹跳而无实质进 +展的情况，此现象常见于多节点写入的共享内存映射文件。通 +过延迟响应远程回调的降级操作，为用户空间程序争取页面取 +消映射前的处理时间。 + +未来计划将 glock 的 "EX" 模式设为本地共享，使本地锁通 +过 i_mutex 实现而非 glock。 + +glock 操作函数的加锁规则： + +============== ====================== ============================= +操作 GLF_LOCK 位锁持有 gl_lockref.lock 自旋锁持有 +============== ====================== ============================= +go_sync 是 否 +go_xmote_bh 是 否 +go_inval 是 否 +go_instantiate 否 否 +go_held 否 否 +go_dump 有时 是 +go_callback 有时（N/A） 是 +go_unlocked 是 否 +============== ====================== ============================= + +.. Note:: + + 若入口处持有锁则操作期间不得释放位锁或自旋锁。 + go_dump 和 do_demote_ok 严禁阻塞。 + 仅当 glock 状态指示其缓存最新数据时才会调用 go_dump。 + +GFS2 内部的 glock 加锁顺序： + + 1. i_rwsem（如需要） + 2. 重命名 glock（仅用于重命名） + 3. Inode glock + （父级优先于子级，同级 inode 按锁编号排序） + 4. Rgrp glock（用于（反）分配操作） + 5. 事务 glock（通过 gfs2_trans_begin，非读操作） + 6. i_rw_mutex（如需要） + 7. 页锁（始终最后，至关重要！） + +每个 inode 对应两把 glock：一把管理 inode 本身（加锁顺 +序如上），另一把（称为 iopen glock）结合 inode 的 +i_nlink 字段决定 inode 生命周期。inode 加锁基于单个 +inode，rgrp 加锁基于单个 rgrp。通常优先获取本地锁再获 +取集群锁。 + +Glock 统计 +---------- + +统计分为两类：超级块相关统计和单个 glock 相关统计。超级 +块统计按每 CPU 执行以减少收集开销，并进一步按 glock 类 +型细分。所有时间单位为纳秒。 + +超级块和 glock 统计收集相同信息。超级块时序统计为 glock +时序统计提供默认值，使新建 glock 具有合理的初始值。每个 +glock 的计数器在创建时初始化为零，当 glock 从内存移除时 +统计丢失。 + +统计包含三组均值/方差对及两个计数器。均值/方差对为平滑 +指数估计，算法与网络代码中的往返时间计算类似（参见《 +TCP/IP详解 卷1》第21.3节及《卷2》第25.10节）。与 TCP/IP +案例不同，此处均值/方差未缩放且单位为整数纳秒。 + +三组均值/方差对测量以下内容： + + 1. DLM 锁时间（非阻塞请求） + 2. DLM 锁时间（阻塞请求） + 3. 请求间隔时间（指向 DLM） + +非阻塞请求指无论目标 DLM 锁处于何种状态均能立即完成的请求。 +当前满足条件的请求包括：(a)锁当前状态为互斥（如锁降级）、 +(b)请求状态为空置或解锁（同样如锁降级）、或(c)设置"try lock" +标志的请求。其余锁请求均属阻塞请求。 + +两个计数器分别统计： + 1. 锁请求总数（决定均值/方差计算的数据量） + 2. glock 代码顶层的持有者排队数（通常远大于 DLM 锁请求数） + +为什么收集这些统计数据？我们需深入分析时序参数的动因如下： + +1. 更精准设置 glock "最短持有时间" +2. 快速识别性能问题 +3. 改进资源组分配算法（基于锁等待时间而非盲目 "try lock"） + +因平滑更新的特性，采样量的阶跃变化需经 8 次采样（方差需 +4 次）才能完全体现，解析结果时需审慎考虑。 + +通过锁请求完成时间和 glock 平均锁请求间隔时间，可计算节 +点使用 glock 时长与集群共享时长的占比，对设置锁最短持有 +时间至关重要。 + +我们已采取严谨措施，力求精准测量目标量值。任何测量系统均 +存在误差，但我期望当前方案已达到合理精度极限。 + +超级块状态统计路径:: + + /sys/kernel/debug/gfs2//sbstats + +Glock 状态统计路径:: + + /sys/kernel/debug/gfs2//glstats + +（假设 debugfs 挂载于 /sys/kernel/debug，且 替 +换为对应 GFS2 文件系统名） + +输出缩写说明： + +========= ============================================ +srtt 非阻塞 DLM 请求的平滑往返时间 +srttvar srtt 的方差估计 +srttb （潜在）阻塞 DLM 请求的平滑往返时间 +srttvarb srttb 的方差估计 +sirt DLM 请求的平滑请求间隔时间 +sirtvar sirt 的方差估计 +dlm DLM 请求数（glstats 文件中的 dcnt） +queue 排队的 glock 请求数（glstats 文件中的 qcnt） +========= ============================================ + +sbstats文件按glock类型（每种类型8行）和CPU核心（每CPU一列） +记录统计数据集。glstats文件则为每个glock提供统计集，其格式 +与glocks文件类似，但所有时序统计量均采用均值/方差格式存储。 + +gfs2_glock_lock_time 跟踪点实时输出目标 glock 的当前统计 +值，并附带每次接收到的dlm响应附加信息： + +====== ============ +status DLM 请求状态 +flags DLM 请求标志 +tdiff 该请求的耗时 +====== ============ + +（其余字段同上表） diff --git a/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst b/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst new file mode 100644 index 000000000000..3975c4544118 --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/gfs2-uevents.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/gfs2-uevents.rst + +:翻译: + + 邵明寅 Shao Mingyin + +:校译: + + 杨涛 yang tao + +=============== +uevents 与 GFS2 +=============== + +在 GFS2 文件系统的挂载生命周期内，会生成多个 uevent。 +本文档解释了这些事件的含义及其用途（被 gfs2-utils 中的 gfs_controld 使用）。 + +GFS2 uevents 列表 +================= + +1. ADD +------ + +ADD 事件发生在挂载时。它始终是新建文件系统生成的第一个 uevent。如果挂载成 +功，随后会生成 ONLINE uevent。如果挂载失败，则随后会生成 REMOVE uevent。 + +ADD uevent 包含两个环境变量：SPECTATOR=[0|1] 和 RDONLY=[0|1]，分别用 +于指定文件系统的观察者状态（一种未分配日志的只读挂载）和只读状态（已分配日志）。 + +2. ONLINE +--------- + +ONLINE uevent 在成功挂载或重新挂载后生成。它具有与 ADD uevent 相同的环 +境变量。ONLINE uevent 及其用于标识观察者和 RDONLY 状态的两个环境变量是较 +新版本内核引入的功能（2.6.32-rc+ 及以上），旧版本内核不会生成此事件。 + +3. CHANGE +--------- + +CHANGE uevent 在两种场景下使用。一是报告第一个节点成功挂载文件系统时 +（FIRSTMOUNT=Done）。这作为信号告知 gfs_controld，此时集群中其他节点可以 +安全挂载该文件系统。 + +另一个 CHANGE uevent 用于通知文件系统某个日志的日志恢复已完成。它包含两个 +环境变量：JID= 指定刚恢复的日志 ID，RECOVERY=[Done|Failed] 表示操作成 +功与否。这些 uevent 会在每次日志恢复时生成，无论是在初始挂载过程中，还是 +gfs_controld 通过 /sys/fs/gfs2//lock_module/recovery 文件 +请求特定日志恢复的结果。 + +由于早期版本的 gfs_controld 使用 CHANGE uevent 时未检查环境变量以确定状 +态，若为其添加新功能，存在用户工具版本过旧导致集群故障的风险。因此，在新增用 +于标识成功挂载或重新挂载的 uevent 时，选择了使用 ONLINE uevent。 + +4. OFFLINE +---------- + +OFFLINE uevent 仅在文件系统发生错误时生成，是 "withdraw" 机制的一部分。 +当前该事件未提供具体错误信息，此问题有待修复。 + +5. REMOVE +--------- + +REMOVE uevent 在挂载失败结束或卸载文件系统时生成。所有 REMOVE uevent +之前都至少存在同一文件系统的 ADD uevent。与其他 uevent 不同，它由内核的 +kobject 子系统自动生成。 + + +所有 GFS2 uevents 的通用信息（uevent 环境变量） +=============================================== + +1. LOCKTABLE= +-------------- + +LOCKTABLE 是一个字符串，其值来源于挂载命令行（locktable=）或 fstab 文件。 +它用作文件系统标签，并为 lock_dlm 类型的挂载提供加入集群所需的信息。 + +2. LOCKPROTO= +------------- + +LOCKPROTO 是一个字符串，其值取决于挂载命令行或 fstab 中的设置。其值将是 +lock_nolock 或 lock_dlm。未来可能支持其他锁管理器。 + +3. JOURNALID= +------------- + +如果文件系统正在使用日志（观察者挂载不分配日志），则所有 GFS2 uevent 中都 +会包含此变量，其值为数字形式的日志 ID。 + +4. UUID= +-------- + +在较新版本的 gfs2-utils 中，mkfs.gfs2 会向文件系统超级块写入 UUID。若存 +在 UUID，所有与该文件系统相关的 uevent 中均会包含此信息。 diff --git a/Documentation/translations/zh_CN/filesystems/gfs2.rst b/Documentation/translations/zh_CN/filesystems/gfs2.rst new file mode 100644 index 000000000000..ffa62b12b019 --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/gfs2.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/gfs2.rst + +:翻译: + + 邵明寅 Shao Mingyin + +:校译: + + 杨涛 yang tao + +===================================== +全局文件系统 2 (Global File System 2) +===================================== + +GFS2 是一个集群文件系统。它允许一组计算机同时使用在它们之间共享的块设备（通 +过 FC、iSCSI、NBD 等）。GFS2 像本地文件系统一样读写块设备，但也使用一个锁 +模块来让计算机协调它们的 I/O 操作，从而维护文件系统的一致性。GFS2 的出色特 +性之一是完美一致性——在一台机器上对文件系统所做的更改会立即显示在集群中的所 +有其他机器上。 + +GFS2 使用可互换的节点间锁定机制，当前支持的机制有： + + lock_nolock + - 允许将 GFS2 用作本地文件系统 + + lock_dlm + - 使用分布式锁管理器 (dlm) 进行节点间锁定。 + 该 dlm 位于 linux/fs/dlm/ + +lock_dlm 依赖于在上述 URL 中找到的用户空间集群管理系统。 + +若要将 GFS2 用作本地文件系统，则不需要外部集群系统，只需：: + + $ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device + $ mount -t gfs2 /dev/block_device /dir + +在所有集群节点上都需要安装 gfs2-utils 软件包；对于 lock_dlm，您还需要按 +照文档配置 dlm 和 corosync 用户空间工具。 + +gfs2-utils 可在 https://pagure.io/gfs2-utils 找到。 + +GFS2 在磁盘格式上与早期版本的 GFS 不兼容，但它已相当接近。 + +以下手册页 (man pages) 可在 gfs2-utils 中找到： + + ============ ============================================= + fsck.gfs2 用于修复文件系统 + gfs2_grow 用于在线扩展文件系统 + gfs2_jadd 用于在线向文件系统添加日志 + tunegfs2 用于操作、检查和调优文件系统 + gfs2_convert 用于将 gfs 文件系统原地转换为 GFS2 + mkfs.gfs2 用于创建文件系统 + ============ ============================================= diff --git a/Documentation/translations/zh_CN/filesystems/index.rst b/Documentation/translations/zh_CN/filesystems/index.rst index 9f2a8b003778..fcc79ff9fdad 100644 --- a/Documentation/translations/zh_CN/filesystems/index.rst +++ b/Documentation/translations/zh_CN/filesystems/index.rst @@ -15,6 +15,16 @@ Linux Kernel中的文件系统 文件系统（VFS）层以及基于其上的各种文件系统如何工作呈现给大家。当前\ 可以看到下面的内容。 +核心 VFS 文档 +============= + +有关 VFS 层本身以及其算法工作方式的文档，请参阅这些手册。 + +.. toctree:: + :maxdepth: 1 + + dnotify + 文件系统 ======== @@ -26,4 +36,9 @@ Linux Kernel中的文件系统 virtiofs debugfs tmpfs - + ubifs + ubifs-authentication + gfs2 + gfs2-uevents + gfs2-glocks + inotify diff --git a/Documentation/translations/zh_CN/filesystems/inotify.rst b/Documentation/translations/zh_CN/filesystems/inotify.rst new file mode 100644 index 000000000000..b4d740aca946 --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/inotify.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/inotify.rst + +:翻译: + + 王龙杰 Wang Longjie + +========================================== +Inotify - 一个强大且简单的文件变更通知系统 +========================================== + + + +文档由 Robert Love 于 2005 年 3 月 15 日开始撰写 + +文档由 Zhang Zhen 于 2015 年 1 月 4 日更新 + + - 删除了已废弃的接口，关于用户接口请参考手册页。 + +(i) 基本原理 + +问： + 不将监控项与被监控对象打开的文件描述符（fd）绑定，这背后的设计决策是什么？ + +答： + 监控项会与打开的 inotify 设备相关联，而非与打开的文件相关联。这解决了 dnotify 的主要问题： + 保持文件打开会锁定文件，更糟的是，还会锁定挂载点。因此，dnotify 在带有可移动介质的桌面系统 + 上难以使用，因为介质将无法被卸载。监控文件不应要求文件处于打开状态。 + +问： + 与每个监控项一个文件描述符的方式相比，采用每个实例一个文件描述符的设计决策是出于什么 + 考虑？ + +答： + 每个监控项一个文件描述符会很快的消耗掉超出允许数量的文件描述符，其数量会超出实际可管理的范 + 围，也会超出 select() 能高效处理的范围。诚然，root 用户可以提高每个进程的文件描述符限制， + 用户也可以使用 epoll，但同时要求这两者是不合理且多余的。一个监控项所消耗的内存比一个打开的文 + 件要少，因此将这两个数量空间分开是合理的。当前的设计正是用户空间开发者所期望的：用户只需初始 + 化一次 inotify，然后添加 n 个监控项，而这只需要一个文件描述符，无需调整文件描述符限制。初 + 始化 inotify 实例初始化两千次是很荒谬的。如果我们能够简洁地实现用户空间的偏好——而且我们 + 确实可以，idr 层让这类事情变得轻而易举——那么我们就应该这么做。 + + 还有其他合理的理由。如果只有一个文件描述符，那就只需要在该描述符上阻塞，它对应着一个事件队列。 + 这个单一文件描述符会返回所有的监控事件以及任何可能的带外数据。而如果每个文件描述符都是一个独 + 立的监控项， + + - 将无法知晓事件的顺序。文件 foo 和文件 bar 上的事件会触发两个文件描述符上的 poll()， + 但无法判断哪个事件先发生。而用单个队列就可以很容易的提供事件的顺序。这种顺序对现有的应用程 + 序（如 Beagle）至关重要。想象一下，如果“mv a b ; mv b a”这样的事件没有顺序会是什么 + 情况。 + + - 我们将不得不维护 n 个文件描述符和 n 个带有状态的内部队列，而不是仅仅一个。这在 kernel 中 + 会混乱得多。单个线性队列是合理的数据结构。 + + - 用户空间开发者更青睐当前的 API。例如，Beagle 的开发者们就很喜欢它。相信我，我问过他们。 + 这并不奇怪：谁会想通过 select 来管理以及阻塞在 1000 个文件描述符上呢？ + + - 无法获取带外数据。 + + - 1024 这个数量仍然太少。 ;-) + + 当要设计一个可扩展到数千个目录的文件变更通知系统时，处理数千个文件描述符似乎并不是合适的接口。 + 这太繁琐了。 + + 此外，创建多个实例、处理多个队列以及相应的多个文件描述符是可行的。不必是每个进程对应一个文件描 + 述符；而是每个队列对应一个文件描述符，一个进程完全可能需要多个队列。 + +问： + 为什么采用系统调用的方式？ + +答： + 糟糕的用户空间接口是 dnotify 的第二大问题。信号对于文件通知来说是一种非常糟糕的接口。其实对 + 于其他任何事情，信号也都不是好的接口。从各个角度来看，理想的解决方案是基于文件描述符的，它允许 + 基本的文件 I/O 操作以及 poll/select 操作。获取文件描述符和管理监控项既可以通过设备文件来 + 实现，也可以通过一系列新的系统调用来实现。我们决定采用一系列系统调用，因为这是提供新的内核接口 + 的首选方法。两者之间唯一真正的区别在于，我们是想使用 open(2) 和 ioctl(2)，还是想使用几 + 个新的系统调用。系统调用比 ioctl 更有优势。 diff --git a/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst b/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst new file mode 100644 index 000000000000..0e7cf7707e26 --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/ubifs-authentication.rst @@ -0,0 +1,354 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/ubifs-authentication.rst + +:翻译: + + 邵明寅 Shao Mingyin + +:校译: + + 杨涛 yang tao + +============= +UBIFS认证支持 +============= + +引言 +==== +UBIFS 利用 fscrypt 框架为文件内容及文件名提供保密性。这能防止攻击者在单一 +时间点读取文件系统内容的攻击行为。典型案例是智能手机丢失时，攻击者若没有文件 +系统解密密钥则无法读取设备上的个人数据。 + +在现阶段，UBIFS 加密尚不能防止攻击者篡改文件系统内容后用户继续使用设备的攻 +击场景。这种情况下，攻击者可任意修改文件系统内容而不被用户察觉。例如修改二 +进制文件使其执行时触发恶意行为 [DMC-CBC-ATTACK]。由于 UBIFS 大部分文件 +系统元数据以明文存储，使得文件替换和内容篡改变得相当容易。 + +其他全盘加密系统（如 dm-crypt）可以覆盖所有文件系统元数据，这类系统虽然能 +增加这种攻击的难度，但特别是当攻击者能多次访问设备时，也有可能实现攻击。对于 +基于 Linux 块 IO 层的 dm-crypt 等文件系统，可通过 dm-integrity 或 +dm-verity 子系统[DM-INTEGRITY, DM-VERITY]在块层实现完整数据认证，这些 +功能也可与 dm-crypt 结合使用[CRYPTSETUP2]。 + +本文描述一种为 UBIFS 实现文件内容认证和完整元数据认证的方法。由于 UBIFS +使用 fscrypt 进行文件内容和文件名加密，认证系统可与 fscrypt 集成以利用密 +钥派生等现有功能。但系统同时也应支持在不启用加密的情况下使用 UBIFS 认证。 + + +MTD, UBI & UBIFS +---------------- +在 Linux 中，MTD（内存技术设备）子系统提供访问裸闪存设备的统一接口。运行于 +MTD 之上的重要子系统是 UBI（无序块映像），它为闪存设备提供卷管理功能，类似 +于块设备的 LVM。此外，UBI 还处理闪存特有的磨损均衡和透明 I/O 错误处理。 +UBI 向上层提供逻辑擦除块(LEB)，并透明地映射到闪存的物理擦除块(PEB)。 + +UBIFS 是运行于 UBI 之上的裸闪存文件系统。因此 UBI 处理磨损均衡和部分闪存 +特性，而 UBIFS专注于可扩展性、性能和可恢复性。 + +:: + + +------------+ +*******+ +-----------+ +-----+ + | | * UBIFS * | UBI-BLOCK | | ... | + | JFFS/JFFS2 | +*******+ +-----------+ +-----+ + | | +-----------------------------+ +-----------+ +-----+ + | | | UBI | | MTD-BLOCK | | ... | + +------------+ +-----------------------------+ +-----------+ +-----+ + +------------------------------------------------------------------+ + | MEMORY TECHNOLOGY DEVICES (MTD) | + +------------------------------------------------------------------+ + +-----------------------------+ +--------------------------+ +-----+ + | NAND DRIVERS | | NOR DRIVERS | | ... | + +-----------------------------+ +--------------------------+ +-----+ + + 图1：处理裸闪存的 Linux 内核子系统 + + + +UBIFS 内部维护多个持久化在闪存上的数据结构： + +- *索引*：存储在闪存上的 B+ 树，叶节点包含文件系统数据 +- *日志*：在更新闪存索引前收集文件系统变更的辅助数据结构，可减少闪存磨损 +- *树节点缓存(TNC)*：反映当前文件系统状态的内存 B+ 树，避免频繁读取闪存。 + 本质上是索引的内存表示，但包含额外属性 +- *LEB属性树(LPT)*：用于统计每个 UBI LEB 空闲空间的闪存B+树 + +本节后续将详细讨论UBIFS的闪存数据结构。因为 TNC 不直接持久化到闪存，其在此 +处的重要性较低。更多 UBIFS 细节详见[UBIFS-WP]。 + + +UBIFS 索引与树节点缓存 +~~~~~~~~~~~~~~~~~~~~~~ + +UBIFS 在闪存上的基础实体称为 *节点* ，包含多种类型。如存储文件内容块的数据 +节点 +( ``struct ubifs_data_node`` )，或表示 VFS 索引节点的 inode 节点 +( ``struct ubifs_ino_node`` )。几乎所有节点共享包含节点类型、长度、序列 +号等基础信息的通用头 +( ``ubifs_ch`` )（见内核源码 ``fs/ubifs/ubifs-media.h`` ）。LPT条目 +和填充节点（用于填充 LEB +尾部不可用空间）等次要节点类型除外。 + +为避免每次变更重写整个 B+ 树，UBIFS 采用 *wandering tree* 实现：仅重写 +变更节点，旧版本被标记废弃而非立即擦除。因此索引不固定存储于闪存某处，而是在 +闪存上 *wanders* ，在 LEB 被 UBIFS 重用前，闪存上会存在废弃部分。为定位 +最新索引，UBIFS 在 UBI LEB 1 存储称为 *主节点* 的特殊节点，始终指向最新 +UBIFS 索引根节点。为增强可恢复性，主节点还备份到 LEB 2。因此挂载 UBIFS 只 +需读取 LEB 1 和 2 获取当前主节点，进而定位最新闪存索引。 + +TNC 是闪存索引的内存表示，包含未持久化的运行时属性（如脏标记）。TNC 作为回 +写式缓存，所有闪存索引修改都通过 TNC 完成。与其他缓存类似，TNC 无需将完整 +索引全部加载到内存中，需要时从闪存读取部分内容。 *提交* 是更新闪存文件系统 +结构（如索引）的 UBIFS 操作。每次提交时，标记为脏的 TNC 节点被写入闪存以更 +新持久化索引。 + + +日志 +~~~~ + +为避免闪存磨损，索引仅在满足特定条件（如 ``fsync(2)`` ）时才持久化（提交）。 +日志用于记录索引提交之间的所有变更（以 inode 节点、数据节点等形式）。挂载时 +从闪存读取日志并重放到 TNC（此时 TNC 按需从闪存索引创建）。 + +UBIFS 保留一组专用于日志的 LEB（称为 *日志区* ）。日志区 LEB 数量在文件系 +统创建时配置（使用 ``mkfs.ubifs`` ）并存储于超级块节点。日志区仅含两类节 +点： *引用节点* 和 *提交起始节点* 。执行索引提交时写入提交起始节点，每次日 +志更新时写入引用节点。每个引用节点指向构成日志条目的其他节点（ inode 节点、 +数据节点等）在闪存上的位置，这些节点称为 *bud* ，描述包含数据的实际文件系 +统变更。 + +日志区以环形缓冲区维护。当日志将满时触发提交操作，同时写入提交起始节点。因此 +挂载时 UBIFS 查找最新提交起始节点，仅重放其后的引用节点。提交起始节点前的引 +用节点将被忽略（因其已属于闪存索引）。 + +写入日志条目时，UBIFS 首先确保有足够空间写入引用节点和该条目的 bud。然后先 +写引用节点，再写描述文件变更的 bud。在日志重放阶段，UBIFS 会记录每个参考节 +点，并检查其引用的 LEB位置以定位 buds。若这些数据损坏或丢失，UBIFS 会尝试 +通过重新读取 LEB 来恢复，但仅针对日志中最后引用的 LEB，因为只有它可能因断 +电而损坏。若恢复失败，UBIFS 将拒绝挂载。对于其他 LEB 的错误，UBIFS 会直接 +终止挂载操作。 + +:: + + | ---- LOG AREA ---- | ---------- MAIN AREA ------------ | + + -----+------+-----+--------+---- ------+-----+-----+--------------- + \ | | | | / / | | | \ + / CS | REF | REF | | \ \ DENT | INO | INO | / + \ | | | | / / | | | \ + ----+------+-----+--------+--- -------+-----+-----+---------------- + | | ^ ^ + | | | | + +------------------------+ | + | | + +-------------------------------+ + + + 图2：包含提交起始节点(CS)和引用节点(REF)的日志区闪存布局，引用节点指向含 + bud 的主区 + + +LEB属性树/表 +~~~~~~~~~~~~ + +LEB 属性树用于存储每个 LEB 的信息，包括 LEB 类型、LEB 上的空闲空间和 +*脏空间* （旧空间，废弃内容） [1]_ 的数量。因为 UBIFS 从不在单个 LEB 混 +合存储索引节点和数据节点，所以 LEB 的类型至关重要，每个 LEB 都有特定用途， +这对空闲空间计算非常有帮助。详见[UBIFS-WP]。 + +LEB 属性树也是 B+ 树，但远小于索引。因为其体积小，所以每次提交时都整块写入， +保存 LPT 是原子操作。 + + +.. [1] 由于LEB只能追加写入不能覆盖，空闲空间（即 LEB 剩余可写空间）与废弃 + 内容（先前写入但未擦除前不能覆盖）存在区别。 + + +UBIFS认证 +========= + +本章介绍UBIFS认证，使UBIFS能验证闪存上元数据和文件内容的真实性与完整性。 + + +威胁模型 +-------- + +UBIFS 认证可检测离线数据篡改。虽然不能防止篡改，但是能让（可信）代码检查闪 +存文件内容和文件系统元数据的完整性与真实性，也能检查文件内容被替换的攻击。 + +UBIFS 认证不防护全闪存内容回滚（攻击者可转储闪存内容并在后期还原）。也不防护 +单个索引提交的部分回滚（攻击者能部分撤销变更）。这是因为 UBIFS 不立即覆盖索 +引树或日志的旧版本，而是标记为废弃，稍后由垃圾回收擦除。攻击者可擦除当前树部 +分内容并还原闪存上尚未擦除的旧版本。因每次提交总会写入索引根节点和主节点的新 +版本而不覆盖旧版本，UBI 的磨损均衡操作（将内容从物理擦除块复制到另一擦除块 +且非原子擦除原块）进一步助长此问题。 + +UBIFS 认证不覆盖认证密钥提供后攻击者在设备执行代码的攻击，需结合安全启动和 +可信启动等措施确保设备仅执行可信代码。 + + +认证 +---- + +为完全信任从闪存读取的数据，所有存储在闪存的 UBIFS 数据结构均需认证： +- 包含文件内容、扩展属性、文件长度等元数据的索引 +- 通过记录文件系统变更来包含文件内容和元数据的日志 +- 存储 UBIFS 用于空闲空间统计的 UBI LEB 元数据的 LPT + + +索引认证 +~~~~~~~~ + +借助 *wandering tree* 概念，UBIFS 仅更新和持久化从叶节点到根节点的变更 +部分。这允许用子节点哈希增强索引树节点。最终索引基本成为 Merkle 树：因索引 +叶节点含实际文件系统数据，其父索引节点的哈希覆盖所有文件内容和元数据。文件 +变更时，UBIFS 索引从叶节点到根节点（含主节点）相应更新，此过程可挂钩以同步 +重新计算各变更节点的哈希。读取文件时，UBIFS 可从叶节点到根节点逐级验证哈希 +确保节点完整性。 + +为确保整个索引真实性，UBIFS 主节点存储基于密钥的哈希(HMAC)，覆盖自身内容及 +索引树根节点哈希。如前所述，主节点在索引持久化时（即索引提交时）总会写入闪存。 + +此方法仅修改 UBIFS 索引节点和主节点以包含哈希，其他类型节点保持不变，减少了 +对 UBIFS 用户（如嵌入式设备）宝贵的存储开销。 + +:: + + +---------------+ + | Master Node | + | (hash) | + +---------------+ + | + v + +-------------------+ + | Index Node #1 | + | | + | branch0 branchn | + | (hash) (hash) | + +-------------------+ + | ... | (fanout: 8) + | | + +-------+ +------+ + | | + v v + +-------------------+ +-------------------+ + | Index Node #2 | | Index Node #3 | + | | | | + | branch0 branchn | | branch0 branchn | + | (hash) (hash) | | (hash) (hash) | + +-------------------+ +-------------------+ + | ... | ... | + v v v + +-----------+ +----------+ +-----------+ + | Data Node | | INO Node | | DENT Node | + +-----------+ +----------+ +-----------+ + + + 图3：索引节点哈希与主节点 HMAC 的覆盖范围 + + + +健壮性性和断电安全性的关键在于以原子操作持久化哈希值与文件内容。UBIFS 现有 +的变更节点持久化机制专为此设计，能够确保断电时安全恢复。为索引节点添加哈希值 +不会改变该机制，因为每个哈希值都与其对应节点以原子操作同步持久化。 + + +日志认证 +~~~~~~~~ + +日志也需要认证。因为日志持续写入，必须频繁地添加认证信息以确保断电时未认证数 +据量可控。方法是从提交起始节点开始，对先前引用节点、当前引用节点和 bud 节点 +创建连续哈希链。适时地在bud节点间插入认证节点，这种新节点类型包含哈希链当前 +状态的 HMAC。因此日志可认证至最后一个认证节点。日志尾部无认证节点的部分无法 +认证，在日志重放时跳过。 + +日志认证示意图如下:: + + ,,,,,,,, + ,......,........................................... + ,. CS , hash1.----. hash2.----. + ,. | , . |hmac . |hmac + ,. v , . v . v + ,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ... + ,..|...,........................................... + , | , + , | ,,,,,,,,,,,,,,, + . | hash3,----. + , | , |hmac + , v , v + , REF#1 -> bud -> bud,-> auth ... + ,,,|,,,,,,,,,,,,,,,,,, + v + REF#2 -> ... + | + V + ... + +因为哈希值包含引用节点，攻击者无法重排或跳过日志头重放，仅能移除日志尾部的 +bud 节点或引用节点，最大限度将文件系统回退至上次提交。 + +日志区位置存储于主节点。因为主节点通过 HMAC 认证，所以未经检测无法篡改。日 +志区大小在文件系统创建时由 `mkfs.ubifs` 指定并存储于超级块节点。为避免篡 +改此值及其他参数，超级块结构添加 HMAC。超级块节点存储在 LEB 0，仅在功能标 +志等变更时修改，文件变更时不修改。 + + +LPT认证 +~~~~~~~ + +LPT 根节点在闪存上的位置存储于 UBIFS 主节点。因为 LPT 每次提交时都以原子 +操作写入和读取，无需单独认证树节点。通过主节点存储的简单哈希保护完整 LPT +即可。因为主节点自身已认证，通过验证主节点真实性并比对存储的 LTP 哈希与读 +取的闪存 LPT 计算哈希值，即可验证 LPT 真实性。 + + +密钥管理 +-------- + +为了简化实现，UBIFS 认证使用单一密钥计算超级块、主节点、提交起始节点和引用 +节点的 HMAC。创建文件系统(`mkfs.ubifs`) 时需提供此密钥以认证超级块节点。 +挂载文件系统时也需此密钥验证认证节点并为变更生成新 HMAC。 + +UBIFS 认证旨在与 UBIFS 加密(fscrypt)协同工作以提供保密性和真实性。因为 +UBIFS 加密采用基于目录的差异化加密策略，可能存在多个 fscrypt 主密钥甚至未 +加密目录。而 UBIFS 认证采用全有或全无方式，要么认证整个文件系统要么完全不 +认证。基于此特性，且为确保认证机制可独立于加密功能使用，UBIFS 认证不与 +fscrypt 共享主密钥，而是维护独立的认证专用密钥。 + +提供认证密钥的API尚未定义，但可通过类似 fscrypt 的用户空间密钥环提供。需注 +意当前 fscrypt 方案存在缺陷，用户空间 API 终将变更[FSCRYPT-POLICY2]。 + +用户仍可通过用户空间提供单一口令或密钥覆盖 UBIFS 认证与加密。相应用户空间工 +具可解决此问题：除派生的 fscrypt 加密主密钥外，额外派生认证密钥。 + +为检查挂载时密钥可用性，UBIFS 超级块节点将额外存储认证密钥的哈希。此方法类 +似 fscrypt 加密策略 v2 提出的方法[FSCRYPT-POLICY2]。 + + +未来扩展 +======== + +特定场景下，若供应商需要向客户提供认证文件系统镜像，应该能在不共享 UBIFS 认 +证密钥的前提下实现。方法是在每个 HMAC 外额外存储数字签名，供应商随文件系统 +镜像分发公钥。若该文件系统后续需要修改，若后续需修改该文件系统，UBIFS 可在 +首次挂载时将全部数字签名替换为 HMAC，其处理逻辑与 IMA/EVM 子系统应对此类情 +况的方式类似。此时，HMAC 密钥需按常规方式预先提供。 + + +参考 +==== + +[CRYPTSETUP2] https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html + +[DMC-CBC-ATTACK] https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-en +crypted-luks-partitions/ + +[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst + +[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.rst + +[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html + +[UBIFS-WP] http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf diff --git a/Documentation/translations/zh_CN/filesystems/ubifs.rst b/Documentation/translations/zh_CN/filesystems/ubifs.rst new file mode 100644 index 000000000000..d1873fc6a67c --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/ubifs.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/filesystems/ubifs.rst + +:翻译: + + 邵明寅 Shao Mingyin + +:校译: + + 杨涛 yang tao + +============ +UBI 文件系统 +============ + +简介 +==== + +UBIFS 文件系统全称为 UBI 文件系统（UBI File System）。UBI 代表无序块镜 +像（Unsorted Block Images）。UBIFS 是一种闪存文件系统，这意味着它专为闪 +存设备设计。需要理解的是，UBIFS与 Linux 中任何传统文件系统（如 Ext2、 +XFS、JFS 等）完全不同。UBIFS 代表一类特殊的文件系统，它们工作在 MTD 设备 +而非块设备上。该类别的另一个 Linux 文件系统是 JFFS2。 + +为更清晰说明，以下是 MTD 设备与块设备的简要比较： + +1. MTD 设备代表闪存设备，由较大尺寸的擦除块组成，通常约 128KiB。块设备由 + 小块组成，通常 512 字节。 +2. MTD 设备支持 3 种主要操作：在擦除块内偏移位置读取、在擦除块内偏移位置写 + 入、以及擦除整个擦除块。块设备支持 2 种主要操作：读取整个块和写入整个块。 +3. 整个擦除块必须先擦除才能重写内容。块可直接重写。 +4. 擦除块在经历一定次数的擦写周期后会磨损，通常 SLC NAND 和 NOR 闪存为 + 100K-1G 次，MLC NAND 闪存为 1K-10K 次。块设备不具备磨损特性。 +5. 擦除块可能损坏（仅限 NAND 闪存），软件需处理此问题。硬盘上的块通常不会损 + 坏，因为硬件有坏块替换机制（至少现代 LBA 硬盘如此）。 + +这充分说明了 UBIFS 与传统文件系统的本质差异。 + +UBIFS 工作在 UBI 层之上。UBI 是一个独立的软件层（位于 drivers/mtd/ubi）， +本质上是卷管理和磨损均衡层。它提供称为 UBI 卷的高级抽象，比 MTD 设备更上层。 +UBI 设备的编程模型与 MTD 设备非常相似，仍由大容量擦除块组成，支持读/写/擦 +除操作，但 UBI 设备消除了磨损和坏块限制（上述列表的第 4 和第 5 项）。 + +某种意义上，UBIFS 是 JFFS2 文件系统的下一代产品，但它与 JFFS2 差异巨大且 +不兼容。主要区别如下： + +* JFFS2 工作在 MTD 设备之上，UBIFS 依赖于 UBI 并工作在 UBI 卷之上。 +* JFFS2 没有介质索引，需在挂载时构建索引，这要求全介质扫描。UBIFS 在闪存 + 介质上维护文件系统索引信息，无需全介质扫描，因此挂载速度远快于 JFFS2。 +* JFFS2 是直写（write-through）文件系统，而 UBIFS 支持回写 + （write-back），这使得 UBIFS 写入速度快得多。 + +与 JFFS2 类似，UBIFS 支持实时压缩，可将大量数据存入闪存。 + +与 JFFS2 类似，UBIFS 能容忍异常重启和断电。它不需要类似 fsck.ext2 的工 +具。UBIFS 会自动重放日志并从崩溃中恢复，确保闪存数据结构的一致性。 + +UBIFS 具有对数级扩展性（其使用的数据结构多为树形），因此挂载时间和内存消耗不 +像 JFFS2 那样线性依赖于闪存容量。这是因为 UBIFS 在闪存介质上维护文件系统 +索引。但 UBIFS 依赖于线性扩展的 UBI 层，因此整体 UBI/UBIFS 栈仍是线性扩 +展。尽管如此，UBIFS/UBI 的扩展性仍显著优于 JFFS2。 + +UBIFS 开发者认为，未来可开发同样具备对数级扩展性的 UBI2。UBI2 将支持与 +UBI 相同的 API，但二进制不兼容。因此 UBIFS 无需修改即可使用 UBI2。 + +挂载选项 +======== + +(*) 表示默认选项。 + +==================== ======================================================= +bulk_read 批量读取以利用闪存介质的顺序读取加速特性 +no_bulk_read (*) 禁用批量读取 +no_chk_data_crc (*) 跳过数据节点的 CRC 校验以提高读取性能。 仅在闪存 + 介质高度可靠时使用此选项。 此选项可能导致文件内容损坏无法被 + 察觉。 +chk_data_crc 强制校验数据节点的 CRC +compr=none 覆盖默认压缩器，设置为"none" +compr=lzo 覆盖默认压缩器，设置为"LZO" +compr=zlib 覆盖默认压缩器，设置为"zlib" +auth_key= 指定用于文件系统身份验证的密钥。 + 使用此选项将强制启用身份验证。 + 传入的密钥必须存在于内核密钥环中， 且类型必须是'logon' +auth_hash_name= 用于身份验证的哈希算法。同时用于哈希计算和 HMAC + 生成。典型值包括"sha256"或"sha512" +==================== ======================================================= + +快速使用指南 +============ + +挂载的 UBI 卷通过 "ubiX_Y" 或 "ubiX:NAME" 语法指定，其中 "X" 是 UBI +设备编号，"Y" 是 UBI 卷编号，"NAME" 是 UBI 卷名称。 + +将 UBI 设备 0 的卷 0 挂载到 /mnt/ubifs:: + + $ mount -t ubifs ubi0_0 /mnt/ubifs + +将 UBI 设备 0 的 "rootfs" 卷挂载到 /mnt/ubifs（"rootfs" 是卷名）:: + + $ mount -t ubifs ubi0:rootfs /mnt/ubifs + +以下是内核启动参数的示例，用于将 mtd0 附加到 UBI 并挂载 "rootfs" 卷： +ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs + +参考资料 +======== + +UBIFS 文档及常见问题解答/操作指南请访问 MTD 官网： + +- http://www.linux-mtd.infradead.org/doc/ubifs.html +- http://www.linux-mtd.infradead.org/faq/ubifs.html diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst index ddd99c0f9b4d..7ae5d8765888 100644 --- a/Documentation/translations/zh_CN/how-to.rst +++ b/Documentation/translations/zh_CN/how-to.rst @@ -64,7 +64,7 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了 :: cd linux - ./scripts/sphinx-pre-install + ./tools/docs/sphinx-pre-install 以 Fedora 为例，它的输出是这样的:: @@ -437,7 +437,7 @@ git email 默认会抄送给您一份，所以您可以切换为审阅者的角 对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令： :: - ./script/checktransupdate.py -l zh_CN`` + tools/docs/checktransupdate.py -l zh_CN`` 该命令会列出需要翻译或更新的英文文档，结果同时保存在 checktransupdate.log 中。 diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst index e5e2aebe1ebc..57f5cf5b2cdd 100644 --- a/Documentation/translations/zh_CN/kbuild/kbuild.rst +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst @@ -93,6 +93,16 @@ HOSTRUSTFLAGS ------------- 在构建主机程序时传递给 $(HOSTRUSTC) 的额外标志。 +PROCMACROLDFLAGS +---------------- +用于链接 Rust 过程宏的标志。由于过程宏是由 rustc 在构建时加载的， +因此必须以与当前使用的 rustc 工具链兼容的方式进行链接。 + +例如，当 rustc 使用的 C 库与用户希望用于主机程序的 C 库不同时， +此设置会非常有用。 + +如果未设置，则默认使用链接主机程序时传递的标志。 + HOSTLDFLAGS ----------- 链接主机程序时传递的额外选项。 @@ -135,12 +145,18 @@ KBUILD_OUTPUT 指定内核构建的输出目录。 在单独的构建目录中为预构建内核构建外部模块时，这个变量也可以指向内核输出目录。请注意， -这并不指定外部模块本身的输出目录。 +这并不指定外部模块本身的输出目录(使用 KBUILD_EXTMOD_OUTPUT 来达到这个目的)。 输出目录也可以使用 "O=..." 指定。 设置 "O=..." 优先于 KBUILD_OUTPUT。 +KBUILD_EXTMOD_OUTPUT +-------------------- +指定外部模块的输出目录 + +设置 "MO=..." 优先于 KBUILD_EXTMOD_OUTPUT. + KBUILD_EXTRA_WARN ----------------- 指定额外的构建检查。也可以通过在命令行传递 "W=..." 来设置相同的值。 @@ -290,8 +306,13 @@ IGNORE_DIRS KBUILD_BUILD_TIMESTAMP ---------------------- 将该环境变量设置为日期字符串，可以覆盖在 UTS_VERSION 定义中使用的时间戳 -（运行内核时的 uname -v）。该值必须是一个可以传递给 date -d 的字符串。默认值是 -内核构建某个时刻的 date 命令输出。 +(运行内核时的 uname -v) 。该值必须是一个可以传递给 date -d 的字符串。例如:: + + $ KBUILD_BUILD_TIMESTAMP="Mon Oct 13 00:00:00 UTC 2025" make + +默认值是内核构建某个时刻的 date 命令输出。如果提供该时戳，它还用于任何 initramfs 归 +档文件中的 mtime 字段。 Initramfs mtimes 是 32 位的，因此早于 Unix 纪元 1970 年，或 +晚于协调世界时 (UTC) 2106 年 2 月 7 日 6 时 28 分 15 秒的日期是无效的。 KBUILD_BUILD_USER, KBUILD_BUILD_HOST ------------------------------------ diff --git a/Documentation/translations/zh_CN/mm/active_mm.rst b/Documentation/translations/zh_CN/mm/active_mm.rst index b3352668c4c8..9496a0bb7d07 100644 --- a/Documentation/translations/zh_CN/mm/active_mm.rst +++ b/Documentation/translations/zh_CN/mm/active_mm.rst @@ -87,4 +87,4 @@ Active MM 最丑陋的之一--不像其他架构的MM和寄存器状态是分开的，alpha的PALcode将两者 连接起来，你需要同时切换两者）。 - (文档来源 http://marc.info/?l=linux-kernel&m=93337278602211&w=2) + (文档来源 https://lore.kernel.org/lkml/Pine.LNX.4.10.9907301410280.752-100000@penguin.transmeta.com/) diff --git a/Documentation/translations/zh_CN/networking/generic-hdlc.rst b/Documentation/translations/zh_CN/networking/generic-hdlc.rst new file mode 100644 index 000000000000..9e493dc9721e --- /dev/null +++ b/Documentation/translations/zh_CN/networking/generic-hdlc.rst @@ -0,0 +1,176 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/networking/generic-hdlc.rst + +:翻译: + + 孙渔喜 Sun yuxi + +========== +通用HDLC层 +========== + +Krzysztof Halasa + + +通用HDLC层当前支持以下协议: + +1. 帧中继（支持ANSI、CCITT、Cisco及无LMI模式） + + - 常规（路由）接口和以太网桥接（以太网设备仿真）接口 + 可共享同一条PVC。 + - 支持ARP（内核暂不支持InARP，但可通过实验性用户空间守护程序实现， + 下载地址：http://www.kernel.org/pub/linux/utils/net/hdlc/）。 + +2. 原始HDLC —— 支持IP（IPv4）接口或以太网设备仿真 +3. Cisco HDLC +4. PPP +5. X.25（使用X.25协议栈） + +通用HDLC仅作为协议驱动 - 必须配合具体硬件的底层驱动 +才能运行。 + +以太网设备仿真（使用HDLC或帧中继PVC）兼容IEEE 802.1Q（VLAN）和 +802.1D（以太网桥接）。 + + +请确保已加载 hdlc.o 和硬件驱动程序。系统将为每个WAN端口创建一个 +"hdlc"网络设备（如hdlc0等）。您需要使用"sethdlc"工具，可从以下 +地址获取： + + http://www.kernel.org/pub/linux/utils/net/hdlc/ + +编译 sethdlc.c 工具:: + + gcc -O2 -Wall -o sethdlc sethdlc.c + +请确保使用与您内核版本匹配的 sethdlc 工具。 + +使用 sethdlc 工具设置物理接口、时钟频率、HDLC 模式， +若使用帧中继还需添加所需的 PVC。 +通常您需要执行类似以下命令:: + + sethdlc hdlc0 clock int rate 128000 + sethdlc hdlc0 cisco interval 10 timeout 25 + +或:: + + sethdlc hdlc0 rs232 clock ext + sethdlc hdlc0 fr lmi ansi + sethdlc hdlc0 create 99 + ifconfig hdlc0 up + ifconfig pvc0 localIP pointopoint remoteIP + +在帧中继模式下，请先启用主hdlc设备（不分配IP地址），再 +使用pvc设备。 + + +接口设置选项： + +* v35 | rs232 | x21 | t1 | e1 + - 当网卡支持软件可选接口时，可为指定端口设置物理接口 + loopback + - 启用硬件环回（仅用于测试） +* clock ext + - RX与TX时钟均使用外部时钟源 +* clock int + - RX与TX时钟均使用内部时钟源 +* clock txint + - RX时钟使用外部时钟源，TX时钟使用内部时钟源 +* clock txfromrx + - RX时钟使用外部时钟源，TX时钟从RX时钟派生 +* rate + - 设置时钟速率（仅适用于"int"或"txint"时钟模式） + + +设置协议选项： + +* hdlc - 设置原始HDLC模式（仅支持IP协议） + + nrz / nrzi / fm-mark / fm-space / manchester - 传输编码选项 + + no-parity / crc16 / crc16-pr0 (预设零值的CRC16) / crc32-itu + + crc16-itu (使用ITU-T多项式的CRC16) / crc16-itu-pr0 - 校验方式选项 + +* hdlc-eth - 使用HDLC进行以太网设备仿真. 校验和编码方式同上 + as above. + +* cisco - 设置Cisco HDLC模式（支持IP、IPv6和IPX协议） + + interval - 保活数据包发送间隔（秒） + + timeout - 未收到保活数据包的超时时间（秒），超过此时长将判定 + 链路断开 + +* ppp - 设置同步PPP模式 + +* x25 - 设置X.25模式 + +* fr - 帧中继模式 + + lmi ansi / ccitt / cisco / none - LMI(链路管理)类型 + + dce - 将帧中继设置为DCE（网络侧）LMI模式（默认为DTE用户侧）。 + + 此设置与时钟无关！ + + - t391 - 链路完整性验证轮询定时器（秒）- 用户侧 + - t392 - 轮询验证定时器（秒）- 网络侧 + - n391 - 全状态轮询计数器 - 用户侧 + - n392 - 错误阈值 - 用户侧和网络侧共用 + - n393 - 监控事件计数 - 用户侧和网络侧共用 + +帧中继专用命令: + +* create n | delete n - 添加/删除DLCI编号为n的PVC接口。 + 新创建的接口将命名为pvc0、pvc1等。 + +* create ether n | delete ether n - 添加/删除用于以太网 + 桥接帧的设备设备将命名为pvceth0、pvceth1等。 + + + + +板卡特定问题 +------------ + +n2.o 和 c101.o 驱动模块需要参数才能工作:: + + insmod n2 hw=io,irq,ram,ports[:io,irq,...] + +示例:: + + insmod n2 hw=0x300,10,0xD0000,01 + +或:: + + insmod c101 hw=irq,ram[:irq,...] + +示例:: + + insmod c101 hw=9,0xdc000 + +若直接编译进内核，这些驱动需要通过内核(命令行)参数配置:: + + n2.hw=io,irq,ram,ports:... + +或:: + + c101.hw=irq,ram:... + + + +若您的N2、C101或PLX200SYN板卡出现问题，可通过"private" +命令查看端口数据包描述符环（显示在内核日志中） + + sethdlc hdlc0 private + +硬件驱动需使用#define DEBUG_RINGS编译选项构建。 +在提交错误报告时附上这些信息将很有帮助。如在使用过程中遇 +到任何问题，请随时告知。 + +获取补丁和其他信息，请访问： +. \ No newline at end of file diff --git a/Documentation/translations/zh_CN/networking/index.rst b/Documentation/translations/zh_CN/networking/index.rst index bb0edcffd144..c276c0993c51 100644 --- a/Documentation/translations/zh_CN/networking/index.rst +++ b/Documentation/translations/zh_CN/networking/index.rst @@ -27,6 +27,9 @@ xfrm_proc netmem alias + mptcp-sysctl + generic-hdlc + timestamping Todolist: @@ -76,7 +79,6 @@ Todolist: * eql * fib_trie * filter -* generic-hdlc * generic_netlink * netlink_spec/index * gen_stats @@ -96,7 +98,6 @@ Todolist: * mctp * mpls-sysctl * mptcp -* mptcp-sysctl * multiqueue * multi-pf-netdev * net_cachelines/index @@ -126,7 +127,6 @@ Todolist: * sctp * secid * seg6-sysctl -* skbuff * smc-sysctl * sriov * statistics @@ -138,7 +138,6 @@ Todolist: * tcp_ao * tcp-thin * team -* timestamping * tipc * tproxy * tuntap diff --git a/Documentation/translations/zh_CN/networking/mptcp-sysctl.rst b/Documentation/translations/zh_CN/networking/mptcp-sysctl.rst new file mode 100644 index 000000000000..0b1b9ed7c647 --- /dev/null +++ b/Documentation/translations/zh_CN/networking/mptcp-sysctl.rst @@ -0,0 +1,139 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/networking/mptcp-sysctl.rst + +:翻译: + + 孙渔喜 Sun yuxi + +================ +MPTCP Sysfs 变量 +================ + +/proc/sys/net/mptcp/* Variables +=============================== + +add_addr_timeout - INTEGER (秒) + 设置ADD_ADDR控制消息的重传超时时间。当MPTCP对端未确认 + 先前的ADD_ADDR消息时，将在该超时时间后重新发送。 + + 默认值与TCP_RTO_MAX相同。此为每个命名空间的sysctl参数。 + + 默认值：120 + +allow_join_initial_addr_port - BOOLEAN + 控制是否允许对端向初始子流使用的IP地址和端口号发送加入 + 请求（1表示允许）。此参数会设置连接时发送给对端的标志位， + 并决定是否接受此类加入请求。 + + 通过ADD_ADDR通告的地址不受此参数影响。 + + 此为每个命名空间的sysctl参数。 + + 默认值：1 + +available_path_managers - STRING + 显示已注册的可用路径管理器选项。可能有更多路径管理器可用 + 但尚未加载。 + +available_schedulers - STRING + 显示已注册的可用调度器选项。可能有更多数据包调度器可用 + 但尚未加载。 + +blackhole_timeout - INTEGER (秒) + 当发生MPTCP防火墙黑洞问题时，初始禁用活跃MPTCP套接字上MPTCP + 功能的时间（秒）。如果在重新启用MPTCP后立即检测到更多黑洞问题， + 此时间段将呈指数增长；当黑洞问题消失时，将重置为初始值。 + + 设置为0可禁用黑洞检测功能。此为每个命名空间的sysctl参数。 + + 默认值：3600 + +checksum_enabled - BOOLEAN + 控制是否启用DSS校验和功能。 + + 当值为非零时可启用DSS校验和。此为每个命名空间的sysctl参数。 + + 默认值：0 + +close_timeout - INTEGER (seconds) + 设置"先断后连"超时时间：在未调用close或shutdown系统调用时， + MPTCP套接字将在最后一个子流移除后保持当前状态达到该时长，才 + 会转为TCP_CLOSE状态。 + + 默认值与TCP_TIMEWAIT_LEN相同。此为每个命名空间的sysctl参数。 + + 默认值：60 + +enabled - BOOLEAN + 控制是否允许创建MPTCP套接字。 + + 当值为1时允许创建MPTCP套接字。此为每个命名空间的sysctl参数。 + + 默认值：1（启用） + +path_manager - STRING + 设置用于每个新MPTCP套接字的默认路径管理器名称。内核路径管理将 + 根据通过MPTCP netlink API配置的每个命名空间值来控制子流连接 + 和地址通告。用户空间路径管理将每个MPTCP连接的子流连接决策和地 + 址通告交由特权用户空间程序控制，代价是需要更多netlink流量来 + 传播所有相关事件和命令。 + + 此为每个命名空间的sysctl参数。 + + * "kernel" - 内核路径管理器 + * "userspace" - 用户空间路径管理器 + + 默认值："kernel" + +pm_type - INTEGER + 设置用于每个新MPTCP套接字的默认路径管理器类型。内核路径管理将 + 根据通过MPTCP netlink API配置的每个命名空间值来控制子流连接 + 和地址通告。用户空间路径管理将每个MPTCP连接的子流连接决策和地 + 址通告交由特权用户空间程序控制，代价是需要更多netlink流量来 + 传播所有相关事件和命令。 + + 此为每个命名空间的sysctl参数。 + + 自v6.15起已弃用，请改用path_manager参数。 + + * 0 - 内核路径管理器 + * 1 - 用户空间路径管理器 + + 默认值：0 + +scheduler - STRING + 选择所需的调度器类型。 + + 支持选择不同的数据包调度器。此为每个命名空间的sysctl参数。 + + 默认值："default" + +stale_loss_cnt - INTEGER + 用于判定子流失效（stale）的MPTCP层重传间隔次数阈值。当指定 + 子流在连续多个重传间隔内既无数据传输又有待处理数据时，将被标 + 记为失效状态。失效子流将被数据包调度器忽略。 + 设置较低的stale_loss_cnt值可实现快速主备切换，较高的值则能 + 最大化边缘场景（如高误码率链路或对端暂停数据处理等异常情况） + 的链路利用率。 + + 此为每个命名空间的sysctl参数。 + + 默认值：4 + +syn_retrans_before_tcp_fallback - INTEGER + 在回退到 TCP（即丢弃 MPTCP 选项）之前，SYN + MP_CAPABLE + 报文的重传次数。换句话说，如果所有报文在传输过程中都被丢弃， + 那么将会： + + * 首次SYN携带MPTCP支持选项 + * 按本参数值重传携带MPTCP选项的SYN包 + * 后续重传将不再携带MPTCP支持选项 + + 0 表示首次重传即丢弃MPTCP选项。 + >=128 表示所有SYN重传均保留MPTCP选项设置过低的值可能增加 + MPTCP黑洞误判几率。此为每个命名空间的sysctl参数。 + + 默认值：2 diff --git a/Documentation/translations/zh_CN/networking/timestamping.rst b/Documentation/translations/zh_CN/networking/timestamping.rst new file mode 100644 index 000000000000..4593f53ad09a --- /dev/null +++ b/Documentation/translations/zh_CN/networking/timestamping.rst @@ -0,0 +1,674 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/networking/timestamping.rst + +:翻译: + + 王亚鑫 Wang Yaxin + +====== +时间戳 +====== + + +1. 控制接口 +=========== + +接收网络数据包时间戳的接口包括： + +SO_TIMESTAMP + 为每个传入数据包生成（不一定是单调的）系统时间时间戳。通过 recvmsg() + 在控制消息中以微秒分辨率报告时间戳。 + SO_TIMESTAMP 根据架构类型和 libc 的 lib 中的 time_t 表示方式定义为 + SO_TIMESTAMP_NEW 或 SO_TIMESTAMP_OLD。 + SO_TIMESTAMP_OLD 和 SO_TIMESTAMP_NEW 的控制消息格式分别为 + struct __kernel_old_timeval 和 struct __kernel_sock_timeval。 + +SO_TIMESTAMPNS + 与 SO_TIMESTAMP 相同的时间戳机制，但以 struct timespec 格式报告时间戳， + 纳秒分辨率。 + SO_TIMESTAMPNS 根据架构类型和 libc 的 time_t 表示方式定义为 + SO_TIMESTAMPNS_NEW 或 SO_TIMESTAMPNS_OLD。 + 控制消息格式对于 SO_TIMESTAMPNS_OLD 为 struct timespec， + 对于 SO_TIMESTAMPNS_NEW 为 struct __kernel_timespec。 + +IP_MULTICAST_LOOP + SO_TIMESTAMP[NS] + 仅用于多播：通过读取回环数据包接收时间戳，获得近似的传输时间戳。 + +SO_TIMESTAMPING + 在接收、传输或两者时生成时间戳。支持多个时间戳源，包括硬件。 + 支持为流套接字生成时间戳。 + + +1.1 SO_TIMESTAMP（也包括 SO_TIMESTAMP_OLD 和 SO_TIMESTAMP_NEW） +--------------------------------------------------------------- + +此套接字选项在接收路径上启用数据报的时间戳。由于目标套接字（如果有） +在网络栈早期未知，因此必须为所有数据包启用此功能。所有早期接收的时间 +戳选项也是如此。 + +有关接口详细信息，请参阅 `man 7 socket`。 + +始终使用 SO_TIMESTAMP_NEW 时间戳以获得 struct __kernel_sock_timeval +格式的时间戳。 + +如果时间在 2038 年后，SO_TIMESTAMP_OLD 在 32 位机器上将返回错误的时间戳。 + +1.2 SO_TIMESTAMPNS（也包括 SO_TIMESTAMPNS_OLD 和 SO_TIMESTAMPNS_NEW） +--------------------------------------------------------------------- + +此选项与 SO_TIMESTAMP 相同，但返回数据类型有所不同。其 struct timespec +能达到比 SO_TIMESTAMP 的 timeval（毫秒）更高的分辨率（纳秒）时间戳。 + +始终使用 SO_TIMESTAMPNS_NEW 时间戳获得 struct __kernel_timespec 格式 +的时间戳。 + +如果时间在 2038 年后，SO_TIMESTAMPNS_OLD 在 32 位机器上将返回错误的时间戳。 + +1.3 SO_TIMESTAMPING（也包括 SO_TIMESTAMPING_OLD 和 SO_TIMESTAMPING_NEW） +------------------------------------------------------------------------ + +支持多种类型的时间戳请求。因此，此套接字选项接受标志位图，而不是布尔值。在:: + + err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val)); + +val 是一个整数，设置了以下任何位。设置其他位将返回 EINVAL 且不更改当前状态。 + +这个套接字选项配置以下几个方面的时间戳生成： +为单个 sk_buff 结构体生成时间戳（1.3.1）； +将时间戳报告到套接字的错误队列（1.3.2）； +配置相关选项（1.3.3）； +也可以通过 cmsg 为单个 sendmsg 调用启用时间戳生成（1.3.4）。 + +1.3.1 时间戳生成 +^^^^^^^^^^^^^^^^ + +某些位是向协议栈请求尝试生成时间戳。它们的任何组合都是有效的。对这些位的更改适 +用于新创建的数据包，而不是已经在协议栈中的数据包。因此，可以通过在两个 setsockopt +调用之间嵌入 send() 调用来选择性地为数据包子集请求时间戳（例如，用于采样）， +一个用于启用时间戳生成，一个用于禁用它。时间戳也可能由于特定套接字请求之外的原 +因而生成，例如在当系统范围内启用接收时间戳时，如前所述。 + +SOF_TIMESTAMPING_RX_HARDWARE: + 请求由网络适配器生成的接收时间戳。 + +SOF_TIMESTAMPING_RX_SOFTWARE: + 当数据进入内核时请求接收时间戳。这些时间戳在设备驱动程序将数据包交给内核接收 + 协议栈后生成。 + +SOF_TIMESTAMPING_TX_HARDWARE: + 请求由网络适配器生成的传输时间戳。此标志可以通过套接字选项和控制消息启用。 + +SOF_TIMESTAMPING_TX_SOFTWARE: + 当数据离开内核时请求传输（TX）时间戳。这些时间戳由设备驱动程序生成，并且尽 + 可能贴近网络接口发送点，但始终在内核将数据包传递给网络接口之前生成。因此， + 它们需要驱动程序支持，且可能并非所有设备都可用。此标志可通过套接字选项和 + 控制消息两种方式启用。 + +SOF_TIMESTAMPING_TX_SCHED: + 在进入数据包调度器之前请求传输时间戳。内核传输延迟（如果很长）通常由排队 + 延迟主导。此时间戳与在 SOF_TIMESTAMPING_TX_SOFTWARE 处获取的时间戳之 + 间的差异将暴露此延迟，并且与协议处理无关。协议处理中产生的延迟（如果有） + 可以通过从 send() 之前立即获取的用户空间时间戳中减去此时间戳来计算。在 + 具有虚拟设备的机器上，传输的数据包通过多个设备和多个数据包调度器，在每层 + 生成时间戳。这允许对排队延迟进行细粒度测量。此标志可以通过套接字选项和控 + 制消息启用。 + +SOF_TIMESTAMPING_TX_ACK: + 请求在发送缓冲区中的所有数据都已得到确认时生成传输（TX）时间戳。此选项 + 仅适用于可靠协议，目前仅在TCP协议中实现。对于该协议，它可能会过度报告 + 测量结果，因为时间戳是在send()调用时缓冲区中的所有数据（包括该缓冲区） + 都被确认时生成的，即累积确认。该机制会忽略选择确认（SACK）和前向确认 + （FACK）。此标志可通过套接字选项和控制消息两种方式启用。 + +SOF_TIMESTAMPING_TX_COMPLETION: + 在数据包传输完成时请求传输时间戳。完成时间戳由内核在从硬件接收数据包完成 + 报告时生成。硬件可能一次报告多个数据包，完成时间戳反映报告的时序而不是实 + 际传输时间。此标志可以通过套接字选项和控制消息启用。 + + +1.3.2 时间戳报告 +^^^^^^^^^^^^^^^^ + +其他三个位控制将在生成的控制消息中报告哪些时间戳。对这些位的更改在协议栈中 +的时间戳报告位置立即生效。仅当数据包设置了相关的时间戳生成请求时，才会报告 +其时间戳。 + +SOF_TIMESTAMPING_SOFTWARE: + 在可用时报告任何软件时间戳。 + +SOF_TIMESTAMPING_SYS_HARDWARE: + 此选项已被弃用和忽略。 + +SOF_TIMESTAMPING_RAW_HARDWARE: + 在可用时报告由 SOF_TIMESTAMPING_TX_HARDWARE 或 SOF_TIMESTAMPING_RX_HARDWARE + 生成的硬件时间戳。 + + +1.3.3 时间戳选项 +^^^^^^^^^^^^^^^^ + +接口支持以下选项 + +SOF_TIMESTAMPING_OPT_ID: + 每个数据包生成一个唯一标识符。一个进程可以同时存在多个未完成的时间戳请求。 + 数据包在传输路径中可能会发生重排序（例如在数据包调度器中）。在这种情况下， + 时间戳会以与原始send()调用不同的顺序排队到错误队列中。如此一来，仅根据 + 时间戳顺序或 payload（有效载荷）检查，并不总能将时间戳与原始send()调用 + 唯一匹配。 + + 此选项在 send() 时将每个数据包与唯一标识符关联，并与时间戳一起返回。 + 标识符源自每个套接字的 u32 计数器（会回绕）。对于数据报套接字，计数器 + 随每个发送的数据包递增。对于流套接字，它随每个字节递增。对于流套接字， + 还要设置 SOF_TIMESTAMPING_OPT_ID_TCP，请参阅下面的部分。 + + 计数器从零开始。在首次启用套接字选项时初始化。在禁用后再重新启用选项时 + 重置。重置计数器不会更改系统中现有数据包的标识符。 + + 此选项仅针对传输时间戳实现。在这种情况下，时间戳总是与sock_extended_err + 结构体一起回环。该选项会修改ee_data字段，以传递一个在该套接字所有同时 + 存在的未完成时间戳请求中唯一的 ID。 + + 进程可以通过控制消息SCM_TS_OPT_ID（TCP 套接字不支持）传递特定 ID， + 从而选择性地覆盖默认生成的 ID，示例如下:: + + struct msghdr *msg; + ... + cmsg = CMSG_FIRSTHDR(msg); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SCM_TS_OPT_ID; + cmsg->cmsg_len = CMSG_LEN(sizeof(__u32)); + *((__u32 *) CMSG_DATA(cmsg)) = opt_id; + err = sendmsg(fd, msg, 0); + + +SOF_TIMESTAMPING_OPT_ID_TCP: + 与 SOF_TIMESTAMPING_OPT_ID 一起传递给新的 TCP 时间戳应用程序。 + SOF_TIMESTAMPING_OPT_ID 定义了流套接字计数器的增量，但其起始点 + 并不完全显而易见。此选项修复了这一点。 + + 对于流套接字，如果设置了 SOF_TIMESTAMPING_OPT_ID，则此选项应始终 + 设置。在数据报套接字上，选项没有效果。 + + 一个合理的期望是系统调用后计数器重置为零，因此后续写入 N 字节将生成 + 计数器为 N-1 的时间戳。SOF_TIMESTAMPING_OPT_ID_TCP 在所有条件下 + 都实现了此行为。 + + SOF_TIMESTAMPING_OPT_ID 不带修饰符时通常报告相同，特别是在套接字选项 + 在无数据传输时设置时。如果正在传输数据，它可能与输出队列的长度（SIOCOUTQ） + 偏差。 + + 差异是由于基于 snd_una 与 write_seq 的。snd_una 是 peer 确认的 stream + 的偏移量。这取决于外部因素，例如网络 RTT。write_seq 是进程写入的最后一个 + 字节。此偏移量不受外部输入影响。 + + 差异细微，在套接字选项初始化时配置时不易察觉，但 SOF_TIMESTAMPING_OPT_ID_TCP + 行为在任何时候都更稳健。 + +SOF_TIMESTAMPING_OPT_CMSG: + 支持所有时间戳数据包的 recv() cmsg。控制消息已无条件地在所有接收时间戳数据包 + 和 IPv6 数据包上支持，以及在发送时间戳数据包的 IPv4 数据包上支持。此选项扩展 + 了它们以在发送时间戳数据包的 IPv4 数据包上支持。一个用例是启用 socket 选项 + IP_PKTINFO 以关联数据包与其出口设备，通过启用 socket 选项 IP_PKTINFO 同时。 + + +SOF_TIMESTAMPING_OPT_TSONLY: + 仅适用于传输时间戳。使内核返回一个 cmsg 与一个空数据包一起，而不是与原 + 始数据包一起。这减少了套接字接收预算（SO_RCVBUF）中收取的内存量，并即使 + 在 sysctl net.core.tstamp_allow_data 为 0 时也提供时间戳。此选项禁用 + SOF_TIMESTAMPING_OPT_CMSG。 + +SOF_TIMESTAMPING_OPT_STATS: + 与传输时间戳一起获取的选项性统计信息。它必须与 SOF_TIMESTAMPING_OPT_TSONLY + 一起使用。当传输时间戳可用时，统计信息可在类型为 SCM_TIMESTAMPING_OPT_STATS + 的单独控制消息中获取，作为 TLV（struct nlattr）类型的列表。这些统计信息允许应 + 用程序将各种传输层统计信息与传输时间戳关联，例如某个数据块被 peer 的接收窗口限 + 制了多长时间。 + +SOF_TIMESTAMPING_OPT_PKTINFO: + 启用 SCM_TIMESTAMPING_PKTINFO 控制消息以接收带有硬件时间戳的数据包。 + 消息包含 struct scm_ts_pktinfo，它提供接收数据包的实际接口索引和层 2 长度。 + 只有在 CONFIG_NET_RX_BUSY_POLL 启用且驱动程序使用 NAPI 时，才会返回非零的 + 有效接口索引。该结构还包含另外两个字段，但它们是保留字段且未定义。 + +SOF_TIMESTAMPING_OPT_TX_SWHW: + 请求在 SOF_TIMESTAMPING_TX_HARDWARE 和 SOF_TIMESTAMPING_TX_SOFTWARE + 同时启用时，为传出数据包生成硬件和软件时间戳。如果同时生成两个时间戳，两个单 + 独的消息将回环到套接字的错误队列，每个消息仅包含一个时间戳。 + +SOF_TIMESTAMPING_OPT_RX_FILTER: + 过滤掉虚假接收时间戳：仅当匹配的时间戳生成标志已启用时才报告接收时间戳。 + + 接收时间戳在入口路径中生成较早，在数据包的目的套接字确定之前。如果任何套接 + 字启用接收时间戳，所有套接字的数据包将接收时间戳数据包。包括那些请求时间戳 + 报告与 SOF_TIMESTAMPING_SOFTWARE 和/或 SOF_TIMESTAMPING_RAW_HARDWARE， + 但未请求接收时间戳生成。这可能发生在仅请求发送时间戳时。 + + 接收虚假时间戳通常是无害的。进程可以忽略意外的非零值。但它使行为在其他套接 + 字上微妙地依赖。此标志隔离套接字以获得更确定的行为。 + +新应用程序鼓励传递 SOF_TIMESTAMPING_OPT_ID 以区分时间戳并传递 +SOF_TIMESTAMPING_OPT_TSONLY 以操作，而不管 sysctl net.core.tstamp_allow_data +的设置。 + +例外情况是当进程需要额外的 cmsg 数据时，例如 SOL_IP/IP_PKTINFO 以检测出 +口网络接口。然后传递选项 SOF_TIMESTAMPING_OPT_CMSG。此选项依赖于访问原 +始数据包的内容，因此不能与 SOF_TIMESTAMPING_OPT_TSONLY 组合。 + + +1.3.4. 通过控制消息启用时间戳 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +除了套接字选项外，时间戳生成还可以通过 cmsg 按写入请求，仅适用于 +SOF_TIMESTAMPING_TX_*（见第 1.3.1 节）。使用此功能，应用程序可以无需启用和 +禁用时间戳即可采样每个 sendmsg() 的时间戳:: + + struct msghdr *msg; + ... + cmsg = CMSG_FIRSTHDR(msg); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SO_TIMESTAMPING; + cmsg->cmsg_len = CMSG_LEN(sizeof(__u32)); + *((__u32 *) CMSG_DATA(cmsg)) = SOF_TIMESTAMPING_TX_SCHED | + SOF_TIMESTAMPING_TX_SOFTWARE | + SOF_TIMESTAMPING_TX_ACK; + err = sendmsg(fd, msg, 0); + +通过 cmsg 设置的 SOF_TIMESTAMPING_TX_* 标志将覆盖通过 setsockopt 设置的 +SOF_TIMESTAMPING_TX_* 标志。 + +此外，应用程序仍然需要通过 setsockopt 启用时间戳报告以接收时间戳:: + + __u32 val = SOF_TIMESTAMPING_SOFTWARE | + SOF_TIMESTAMPING_OPT_ID /* 或任何其他标志 */; + err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val)); + + +1.4 字节流时间戳 +---------------- + +SO_TIMESTAMPING 接口支持字节流的时间戳。每个请求解释为请求当整个缓冲区内容 +通过时间戳点时。也就是说，对于流选项 SOF_TIMESTAMPING_TX_SOFTWARE 将记录 +当所有字节都到达设备驱动程序时，无论数据被转换成多少个数据包。 + +一般来说，字节流没有自然分隔符，因此将时间戳与数据相关联是非平凡的。字节范围 +可能跨段，任何段可能合并（可能合并先前分段缓冲区关联的独立 send() 调用）。段 +可以重新排序，同一字节范围可以在多个段中并存，对于实现重传的协议。 + +所有时间戳必须实现相同的语义，否则它们是不可比较的。以不同于简单情况（缓冲区 +到 skb 的 1:1 映射）的方式处理“罕见”角落情况是不够的，因为性能调试通常需要 +关注这些异常。 + +在实践中，时间戳可以与字节流段一致地关联，如果时间戳语义和测量时序的选择正确。 +此挑战与决定 IP 分片策略没有不同。在那里，定义是仅对第一个分片进行时间戳。对 +于字节流，我们选择仅在所有字节通过某个点时生成时间戳。SOF_TIMESTAMPING_TX_ACK +定义的实现和推理是容易的。一个需要考虑 SACK 的实现会更复杂，因为可能存在传输 +空洞和乱序到达。 + +在主机上，TCP 也可以通过 Nagle、cork、autocork、分段和 GSO 打破简单的 1:1 +缓冲区到 skbuff 映射。实现确保在所有情况下都正确，通过跟踪每个 send() 传递 +给send() 的最后一个字节，即使它在 skbuff 扩展或合并操作后不再是最后一个字 +节。它存储相关的序列号在 skb_shinfo(skb)->tskey。因为一个 skbuff 只有一 +个这样的字段，所以只能生成一个时间戳。 + +在罕见情况下，如果两个请求折叠到同一个 skb，则时间戳请求可能会被错过。进程可 +以通过始终在请求之间刷新 TCP 栈来检测此情况，例如启用 TCP_NODELAY 和禁用 +TCP_CORK和 autocork。在 linux-4.7 之后，更好的预防合并方法是使用 MSG_EOR +标志在sendmsg()时。 + +这些预防措施确保时间戳仅在所有字节通过时间戳点时生成，假设网络栈本身不会重新 +排序段。栈确实试图避免重新排序。唯一的例外是管理员控制：可以构造一个数据包调 +度器配置，将来自同一流的不同段延迟不同。这种设置通常不常见。 + + +2 数据接口 +========== + +时间戳通过 recvmsg() 的辅助数据功能读取。请参阅 `man 3 cmsg` 了解此接口的 +详细信息。套接字手册页面 (`man 7 socket`) 描述了如何检索SO_TIMESTAMP 和 +SO_TIMESTAMPNS 生成的数据包时间戳。 + + +2.1 SCM_TIMESTAMPING 记录 +------------------------- + +这些时间戳在 cmsg_level SOL_SOCKET、cmsg_type SCM_TIMESTAMPING 和类型为 + +对于 SO_TIMESTAMPING_OLD:: + + struct scm_timestamping { + struct timespec ts[3]; + }; + +对于 SO_TIMESTAMPING_NEW:: + + struct scm_timestamping64 { + struct __kernel_timespec ts[3]; + +始终使用 SO_TIMESTAMPING_NEW 时间戳以始终获得 struct scm_timestamping64 +格式的时间戳。 + +SO_TIMESTAMPING_OLD 在 32 位机器上 2038 年后返回错误的时间戳。 + +该结构可以返回最多三个时间戳。这是一个遗留功能。任何时候至少有一个字 +段不为零。大多数时间戳都通过 ts[0] 传递。硬件时间戳通过 ts[2] 传递。 + +ts[1] 以前用于存储硬件时间戳转换为系统时间。相反，将硬件时钟设备直接 +暴露为HW PTP时钟源，以允许用户空间进行时间转换，并可选地与用户空间 +PTP 堆栈（如linuxptp）同步系统时间。对于 PTP 时钟 API，请参阅 +Documentation/driver-api/ptp.rst。 + +注意，如果同时启用了 SO_TIMESTAMP 或 SO_TIMESTAMPNS 与 +SO_TIMESTAMPING 使用 SOF_TIMESTAMPING_SOFTWARE，在 recvmsg() +调用时会生成一个虚假的软件时间戳，并传递给 ts[0] 当真实软件时间戳缺 +失时。这也发生在硬件传输时间戳上。 + +2.1.1 传输时间戳与 MSG_ERRQUEUE +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +对于传输时间戳，传出数据包回环到套接字的错误队列，并附加发送时间戳（s）。 +进程通过调用带有 MSG_ERRQUEUE 标志的 recvmsg() 接收时间戳，并传递 +一个足够大的 msg_control缓冲区以接收相关的元数据结构。recvmsg 调用 +返回原始传出数据包，并附加两个辅助消息。 + +一个 cm_level SOL_IP(V6) 和 cm_type IP(V6)_RECVERR 嵌入一个 +struct sock_extended_err这定义了错误类型。对于时间戳，ee_errno +字段是 ENOMSG。另一个辅助消息将具有 cm_level SOL_SOCKET 和 cm_type +SCM_TIMESTAMPING。这嵌入了 struct scm_timestamping。 + + +2.1.1.2 时间戳类型 +~~~~~~~~~~~~~~~~~~ + +三个 struct timespec 的语义由 struct sock_extended_err 中的 +ee_info 字段定义。它包含一个类型 SCM_TSTAMP_* 来定义实际传递给 +scm_timestamping 的时间戳。 + +SCM_TSTAMP_* 类型与之前讨论的 SOF_TIMESTAMPING_* 控制字段完全 +匹配，只有一个例外对于遗留原因，SCM_TSTAMP_SND 等于零，可以设置为 +SOF_TIMESTAMPING_TX_HARDWARE 和 SOF_TIMESTAMPING_TX_SOFTWARE。 +它是第一个，如果 ts[2] 不为零，否则是第二个，在这种情况下，时间戳存 +储在ts[0] 中。 + + +2.1.1.3 分片 +~~~~~~~~~~~~ + +传出数据报分片很少见，但可能发生，例如通过显式禁用 PMTU 发现。如果 +传出数据包被分片，则仅对第一个分片进行时间戳，并返回给发送套接字。 + + +2.1.1.4 数据包负载 +~~~~~~~~~~~~~~~~~~ + +调用应用程序通常不关心接收它传递给堆栈的整个数据包负载：套接字错误队 +列机制仅是一种将时间戳附加到其上的方法。在这种情况下，应用程序可以选 +择读取较小的数据报，甚至长度为 0。负载相应地被截断。直到进程调用 +recvmsg() 到错误队列，然而，整个数据包仍在队列中，占用 SO_RCVBUF 预算。 + + +2.1.1.5 阻塞读取 +~~~~~~~~~~~~~~~~ + +从错误队列读取始终是非阻塞操作。要阻塞等待时间戳，请使用 poll 或 +select。poll() 将在 pollfd.revents 中返回 POLLERR，如果错误队列 +中有数据。没有必要在 pollfd.events中传递此标志。此标志在请求时被忽 +略。另请参阅 `man 2 poll`。 + + +2.1.2 接收时间戳 +^^^^^^^^^^^^^^^^ + +在接收时，没有理由从套接字错误队列读取。SCM_TIMESTAMPING 辅助数据与 +数据包数据一起通过正常 recvmsg() 发送。由于这不是套接字错误，它不伴 +随消息 SOL_IP(V6)/IP(V6)_RECVERROR。在这种情况下，struct +scm_timestamping 中的三个字段含义隐式定义。ts[0] 在设置时包含软件 +时间戳，ts[1] 再次被弃用，ts[2] 在设置时包含硬件时间戳。 + + +3. 硬件时间戳配置：ETHTOOL_MSG_TSCONFIG_SET/GET +=============================================== + +硬件时间戳也必须为每个设备驱动程序初始化，该驱动程序预期执行硬件时间戳。 +参数在 include/uapi/linux/net_tstamp.h 中定义为:: + + struct hwtstamp_config { + int flags; /* 目前没有定义的标志，必须为零 */ + int tx_type; /* HWTSTAMP_TX_* */ + int rx_filter; /* HWTSTAMP_FILTER_* */ + }; + +期望的行为通过 tsconfig netlink 套接字 ``ETHTOOL_MSG_TSCONFIG_SET`` +传递到内核，并通过 ``ETHTOOL_A_TSCONFIG_TX_TYPES``、 +``ETHTOOL_A_TSCONFIG_RX_FILTERS`` 和 ``ETHTOOL_A_TSCONFIG_HWTSTAMP_FLAGS`` +netlink 属性设置 struct hwtstamp_config 相应地。 + +``ETHTOOL_A_TSCONFIG_HWTSTAMP_PROVIDER`` netlink 嵌套属性用于选择 +硬件时间戳的来源。它由设备源的索引和时间戳类型限定符组成。 + +驱动程序可以自由使用比请求更宽松的配置。预期驱动程序应仅实现可以直接支持的 +最通用模式。例如，如果硬件可以支持 HWTSTAMP_FILTER_PTP_V2_EVENT，则它 +通常应始终升级HWTSTAMP_FILTER_PTP_V2_L2_SYNC，依此类推，因为 +HWTSTAMP_FILTER_PTP_V2_EVENT 更通用（更实用）。 + +支持硬件时间戳的驱动程序应更新 struct，并可能返回更宽松的实际配置。如果 +请求的数据包无法进行时间戳，则不应更改任何内容，并返回 ERANGE（与 EINVAL +相反，这表明 SIOCSHWTSTAMP 根本不支持）。 + +只有具有管理权限的进程才能更改配置。用户空间负责确保多个进程不会相互干扰， +并确保设置被重置。 + +任何进程都可以通过请求 tsconfig netlink 套接字 ``ETHTOOL_MSG_TSCONFIG_GET`` +读取实际配置。 + +遗留配置是使用 ioctl(SIOCSHWTSTAMP) 与指向 struct ifreq 的指针，其 +ifr_data指向 struct hwtstamp_config。tx_type 和 rx_filter 是驱动 +程序期望执行的提示。如果请求的细粒度过滤对传入数据包不支持，驱动程序可能 +会对请求的数据包进行时间戳。ioctl(SIOCGHWTSTAMP) 以与 +ioctl(SIOCSHWTSTAMP) 相同的方式使用。然而,并非所有驱动程序都实现了这一点。 + +:: + + /* 可能的 hwtstamp_config->tx_type 值 */ + enum { + /* + * 不会需要硬件时间戳的传出数据包； + * 如果数据包到达并请求它，则不会进行硬件时间戳 + */ + HWTSTAMP_TX_OFF, + + /* + * 启用传出数据包的硬件时间戳； + * 数据包的发送者决定哪些数据包需要时间戳， + * 在发送数据包之前设置 SOF_TIMESTAMPING_TX_SOFTWARE + */ + HWTSTAMP_TX_ON, + }; + + /* 可能的 hwtstamp_config->rx_filter 值 */ + enum { + /* 时间戳不传入任何数据包 */ + HWTSTAMP_FILTER_NONE, + + /* 时间戳任何传入数据包 */ + HWTSTAMP_FILTER_ALL, + + /* 返回值：时间戳所有请求的数据包加上一些其他数据包 */ + HWTSTAMP_FILTER_SOME, + + /* PTP v1，UDP，任何事件数据包 */ + HWTSTAMP_FILTER_PTP_V1_L4_EVENT, + + /* 有关完整值列表，请检查 + * 文件 include/uapi/linux/net_tstamp.h + */ + }; + +3.1 硬件时间戳实现：设备驱动程序 +-------------------------------- + +支持硬件时间戳的驱动程序必须支持 ndo_hwtstamp_set NDO 或遗留 SIOCSHWTSTAMP +ioctl 并更新提供的 struct hwtstamp_config 与实际值，如 SIOCSHWTSTAMP 部分 +所述。它还应支持 ndo_hwtstamp_get 或遗留 SIOCGHWTSTAMP。 + +接收数据包的时间戳必须存储在 skb 中。要获取 skb 的共享时间戳结构，请调用 +skb_hwtstamps()。然后设置结构中的时间戳:: + + struct skb_shared_hwtstamps { + /* 硬件时间戳转换为自任意时间点的持续时间 + * 自定义点 + */ + ktime_t hwtstamp; + }; + +传出数据包的时间戳应按如下方式生成： + +- 在 hard_start_xmit() 中，检查 (skb_shinfo(skb)->tx_flags & SKBTX_HW_TSTAMP) + 是否不为零。如果是，则驱动程序期望执行硬件时间戳。 +- 如果此 skb 和请求都可能，则声明驱动程序正在执行时间戳，通过设置 skb_shinfo(skb)->tx_flags + 中的标志SKBTX_IN_PROGRESS，例如:: + + skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS; + + 您可能希望保留与 skb 关联的指针，而不是释放 skb。不支持硬件时间戳的驱 + 动程序不会这样做。驱动程序绝不能触及 sk_buff::tstamp！它用于存储网络 + 子系统生成的软件时间戳。 +- 驱动程序应在尽可能接近将 sk_buff 传递给硬件时调用 skb_tx_timestamp()。 + skb_tx_timestamp()提供软件时间戳（如果请求），并且硬件时间戳不可用 + （SKBTX_IN_PROGRESS 未设置）。 +- 一旦驱动程序发送数据包并/或获取硬件时间戳，它就会通过 skb_tstamp_tx() + 传递时间戳，原始 skb，原始硬件时间戳。skb_tstamp_tx() 克隆原始 skb 并 + 添加时间戳，因此原始 skb 现在必须释放。如果获取硬件时间戳失败，则驱动程序 + 不应回退到软件时间戳。理由是，这会在处理管道中的稍后时间发生，而不是其他软 + 件时间戳，因此可能导致时间戳之间的差异。 + +3.2 堆叠 PTP 硬件时钟的特殊考虑 +------------------------------- + +在数据包的路径中可能存在多个 PHC（PTP 硬件时钟）。内核没有明确的机制允许用 +户选择用于时间戳以太网帧的 PHC。相反，假设最外层的 PHC 始终是最优的，并且 +内核驱动程序协作以实现这一目标。目前有 3 种堆叠 PHC 的情况，如下所示： + +3.2.1 DSA（分布式交换架构）交换机 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +这些是具有一个端口连接到（完全不知情的）主机以太网接口的以太网交换机，并且 +执行端口多路复用或可选转发加速功能。每个 DSA 交换机端口在用户看来都是独立的 +（虚拟）网络接口，其网络 I/O 在底层通过主机接口（在 TX 上重定向到主机端口， +在 RX 上拦截帧）执行。 + +当 DSA 交换机连接到主机端口时，PTP 同步必须受到限制，因为交换机的可变排队 +延迟引入了主机端口与其 PTP 伙伴之间的路径延迟抖动。因此，一些 DSA 交换机 +包含自己的时间戳时钟，并具有在自身 MAC上执行网络时间戳的能力，因此路径延迟 +仅测量线缆和 PHY 传播延迟。支持 Linux 的 DSA 交换机暴露了与任何其他网络 +接口相同的 ABI（除了 DSA 接口在网络 I/O 方面实际上是虚拟的，它们确实有自 +己的PHC）。典型地，但不是强制性地，所有DSA 交换机接口共享相同的 PHC。 + +通过设计，DSA 交换机对连接到其主机端口的 PTP 时间戳不需要任何特殊的驱动程 +序处理。然而，当主机端口也支持 PTP 时间戳时，DSA 将负责拦截 +``.ndo_eth_ioctl`` 调用，并阻止尝试在主机端口上启用硬件时间戳。这是因为 +SO_TIMESTAMPING API 不允许为同一数据包传递多个硬件时间戳，因此除了 DSA +交换机端口之外的任何人都不应阻止这样做。 + +在通用层，DSA 提供了以下基础设施用于 PTP 时间戳： + +- ``.port_txtstamp()``：在用户空间从用户空间请求带有硬件 TX 时间戳请求 + 的数据包之前调用的钩子。这是必需的，因为硬件时间戳在实际 MAC 传输后才可 + 用，因此驱动程序必须准备将时间戳与原始数据包相关联，以便它可以重新入队数 + 据包到套接字的错误队列。为了保存可能在时间戳可用时需要的数据包，驱动程序 + 可以调用 ``skb_clone_sk``，在 skb->cb 中保存克隆指针，并入队一个 tx + skb 队列。通常，交换机会有一个PTP TX 时间戳寄存器（或有时是一个 FIFO）， + 其中时间戳可用。在 FIFO 的情况下，硬件可能会存储PTP 序列 ID/消息类型/ + 域号和实际时间戳的键值对。为了在等待时间戳的数据包队列和实际时间戳之间正 + 确关联，驱动程序可以使用 BPF 分类器(``ptp_classify_raw``) 来识别 PTP + 传输类型，并使用 ``ptp_parse_header`` 解释 PTP 头字段。可能存在一个 IRQ， + 当此时间戳可用时触发，或者驱动程序可能需要轮询，在调用 ``dev_queue_xmit()`` + 到主机接口之后。单步 TX 时间戳不需要数据包克隆，因为 PTP 协议不需要后续消 + 息（因为TX 时间戳已嵌入到数据包中），因此用户空间不期望数据包带有 TX 时间戳 + 被重新入队到其套接字的错误队列。 + +- ``.port_rxtstamp()``：在 RX 上，DSA 运行 BPF 分类器以识别 PTP 事件消息 + （任何其他数据包，包括 PTP 通用消息，不进行时间戳）。驱动程序提供原始（也是唯一） + 时间戳数据包，以便它可以标记它，如果它是立即可用的，或者延迟。在接收时，时间 + 戳可能要么在频带内（通过DSA 头中的元数据，或以其他方式附加到数据包），要么在频 + 带外（通过另一个 RX 时间戳FIFO）。在 RX 上延迟通常是必要的，当检索时间戳需要 + 可睡眠上下文时。在这种情况下，DSA驱动程序有责任调用 ``netif_rx()`` 在新鲜时 + 间戳的 skb 上。 + +3.2.2 以太网 PHYs +^^^^^^^^^^^^^^^^^ + +这些是通常在网络栈中履行第 1 层角色的设备，因此它们在 DSA 交换机中没有网络接 +口的表示。然而，PHY可能能够检测和时间戳 PTP 数据包，出于性能原因：在尽可能接 +近导线的地方获取的时间戳具有更稳定的同步性和更精确的精度。 + +支持 PTP 时间戳的 PHY 驱动程序必须创建 ``struct mii_timestamper`` 并添加 +指向它的指针在 ``phydev->mii_ts`` 中。 ``phydev->mii_ts`` 的存在将由网络 +堆栈检查。 + +由于 PHY 没有网络接口表示，PHY 的时间戳和 ethtool ioctl 操作需要通过其各自 +的 MAC驱动程序进行中介。因此，与 DSA 交换机不同，需要对每个单独的 MAC 驱动 +程序进行 PHY时间戳支持的修改。这包括： + +- 在 ``.ndo_eth_ioctl`` 中检查，是否 ``phy_has_hwtstamp(netdev->phydev)`` + 为真或假。如果是，则 MAC 驱动程序不应处理此请求，而应将其传递给 PHY 使用 + ``phy_mii_ioctl()``。 + +- 在 RX 上，特殊干预可能或可能不需要，具体取决于将 skb 传递到网络堆栈的函数。 + 在 plain ``netif_rx()`` 和类似情况下，MAC 驱动程序必须检查是否 + ``skb_defer_rx_timestamp(skb)`` 是必要的，如果是，则不调用 ``netif_rx()``。 + 如果 ``CONFIG_NETWORK_PHY_TIMESTAMPING`` 启用，并且 + ``skb->dev->phydev->mii_ts`` 存在，它的 ``.rxtstamp()`` 钩子现在将被调 + 用，以使用与 DSA 类似的逻辑确定 RX 时间戳延迟是否必要。同样像 DSA，它成为 + PHY 驱动程序的责任，在时间戳可用时发送数据包到堆栈。 + + 对于其他 skb 接收函数，例如 ``napi_gro_receive`` 和 ``netif_receive_skb``， + 堆栈会自动检查是否 ``skb_defer_rx_timestamp()`` 是必要的，因此此检查不 + 需要在驱动程序内部。 + +- 在 TX 上，同样，特殊干预可能或可能不需要。调用 ``mii_ts->txtstamp()``钩 + 子的函数名为``skb_clone_tx_timestamp()``。此函数可以直接调用（在这种情 + 况下，确实需要显式 MAC 驱动程序支持），但函数也 piggybacks 从 + ``skb_tx_timestamp()`` 调用，许多 MAC 驱动程序已经为软件时间戳目的执行。 + 因此，如果 MAC 支持软件时间戳，则它不需要在此阶段执行任何其他操作。 + +3.2.3 MII 总线嗅探设备 +^^^^^^^^^^^^^^^^^^^^^^ + +这些执行与时间戳以太网 PHY 相同的角色，除了它们是离散设备，因此可以与任何 PHY +组合，即使它不支持时间戳。在 Linux 中，它们是可发现的，可以通过 Device Tree +附加到 ``struct phy_device``，对于其余部分，它们使用与那些相同的 mii_ts 基 +础设施。请参阅 Documentation/devicetree/bindings/ptp/timestamper.txt 了 +解更多详细信息。 + +3.2.4 MAC 驱动程序的其他注意事项 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +堆叠 PHC 可能会暴露 MAC 驱动程序的错误，这些错误在未堆叠 PHC 时无法触发。一个 +例子涉及此行代码，已经在前面的部分中介绍过:: + + skb_shinfo(skb)->tx_flags |= SKBTX_IN_PROGRESS; + +任何 TX 时间戳逻辑，无论是普通的 MAC 驱动程序、DSA 交换机驱动程序、PHY 驱动程 +序还是 MII 总线嗅探设备驱动程序，都应该设置此标志。但一个未意识到 PHC 堆叠的 +MAC 驱动程序可能会被其他不是它自己的实体设置此标志，并传递一个重复的时间戳。例 +如，典型的 TX 时间戳逻辑可能是将传输部分分为 2 个部分： + +1. "TX"：检查是否通过 ``.ndo_eth_ioctl``（"``priv->hwtstamp_tx_enabled + == true``"）和当前 skb 是否需要 TX 时间戳（"``skb_shinfo(skb)->tx_flags + & SKBTX_HW_TSTAMP``"）。如果为真，则设置 "``skb_shinfo(skb)->tx_flags + |= SKBTX_IN_PROGRESS``" 标志。注意：如上所述，在堆叠 PHC 系统中，此条件 + 不应触发，因为此 MAC 肯定不是最外层的 PHC。但这是典型的错误所在。传输继续 + 使用此数据包。 + +2. "TX 确认"：传输完成。驱动程序检查是否需要收集任何 TX 时间戳。这里通常是典 + 型的错误所在：驱动程序采取捷径，只检查 "``skb_shinfo(skb)->tx_flags & + SKBTX_IN_PROGRESS``" 是否设置。在堆叠 PHC 系统中，这是错误的，因为此 MAC + 驱动程序不是唯一在 TX 数据路径中启用 SKBTX_IN_PROGRESS 的实体。 + +此问题的正确解决方案是 MAC 驱动程序在其 "TX 确认" 部分中有一个复合检查，不仅 +针对 "``skb_shinfo(skb)->tx_flags & SKBTX_IN_PROGRESS``"，还针对 +"``priv->hwtstamp_tx_enabled == true``"。因为系统确保 PTP 时间戳仅对最 +外层 PHC 启用，此增强检查将避免向用户空间传递重复的 TX 时间戳。 diff --git a/Documentation/translations/zh_CN/rust/general-information.rst b/Documentation/translations/zh_CN/rust/general-information.rst index 251f6ee2bb44..9b5e37e13f38 100644 --- a/Documentation/translations/zh_CN/rust/general-information.rst +++ b/Documentation/translations/zh_CN/rust/general-information.rst @@ -13,6 +13,7 @@ 本文档包含了在内核中使用Rust支持时需要了解的有用信息。 +.. _rust_code_documentation_zh_cn: 代码文档 -------- diff --git a/Documentation/translations/zh_CN/rust/index.rst b/Documentation/translations/zh_CN/rust/index.rst index b01f887e7167..5347d4729588 100644 --- a/Documentation/translations/zh_CN/rust/index.rst +++ b/Documentation/translations/zh_CN/rust/index.rst @@ -10,7 +10,35 @@ Rust ==== -与内核中的Rust有关的文档。若要开始在内核中使用Rust，请阅读quick-start.rst指南。 +与内核中的Rust有关的文档。若要开始在内核中使用Rust，请阅读 quick-start.rst 指南。 + +Rust 实验 +--------- +Rust 支持在 v6.1 版本中合并到主线，以帮助确定 Rust 作为一种语言是否适合内核， +即是否值得进行权衡。 + +目前，Rust 支持主要面向对 Rust 支持感兴趣的内核开发人员和维护者， +以便他们可以开始处理抽象和驱动程序，并帮助开发基础设施和工具。 + +如果您是终端用户，请注意，目前没有适合或旨在生产使用的内置驱动程序或模块， +并且 Rust 支持仍处于开发/实验阶段，尤其是对于特定内核配置。 + +代码文档 +-------- + +给定一个内核配置，内核可能会生成 Rust 代码文档，即由 ``rustdoc`` 工具呈现的 HTML。 + +.. only:: rustdoc and html + + 该内核文档使用 `Rust 代码文档 `_ 构建。 + +.. only:: not rustdoc and html + + 该内核文档不使用 Rust 代码文档构建。 + +预生成版本提供在：https://rust.docs.kernel.org。 + +请参阅 :ref:`代码文档 ` 部分以获取更多详细信息。 .. toctree:: :maxdepth: 1 @@ -19,6 +47,9 @@ Rust general-information coding-guidelines arch-support + testing + +你还可以在 :doc:`../../../process/kernel-docs` 中找到 Rust 的学习材料。 .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/rust/testing.rst b/Documentation/translations/zh_CN/rust/testing.rst new file mode 100644 index 000000000000..ca81f1cef6eb --- /dev/null +++ b/Documentation/translations/zh_CN/rust/testing.rst @@ -0,0 +1,215 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/rust/testing.rst + +:翻译: + + 郭杰 Ben Guo + +测试 +==== + +本文介绍了如何在内核中测试 Rust 代码。 + +有三种测试类型： + +- KUnit 测试 +- ``#[test]`` 测试 +- Kselftests + +KUnit 测试 +---------- + +这些测试来自 Rust 文档中的示例。它们会被转换为 KUnit 测试。 + +使用 +**** + +这些测试可以通过 KUnit 运行。例如，在命令行中使用 ``kunit_tool`` （ ``kunit.py`` ）:: + + ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y + +或者，KUnit 也可以在内核启动时以内置方式运行。获取更多 KUnit 信息，请参阅 +Documentation/dev-tools/kunit/index.rst。 +关于内核内置与命令行测试的详细信息，请参阅 Documentation/dev-tools/kunit/architecture.rst。 + +要使用这些 KUnit 文档测试，需要在内核配置中启用以下选项:: + + CONFIG_KUNIT + Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests + CONFIG_RUST_KERNEL_DOCTESTS + Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate + +KUnit 测试即文档测试 +******************** + +文档测试（ *doctests* ）一般用于展示函数、结构体或模块等的使用方法。 + +它们非常方便，因为它们就写在文档旁边。例如： + +.. code-block:: rust + + /// 求和两个数字。 + /// + /// ``` + /// assert_eq!(mymod::f(10, 20), 30); + /// ``` + pub fn f(a: i32, b: i32) -> i32 { + a + b + } + +在用户空间中，这些测试由 ``rustdoc`` 负责收集并运行。单独使用这个工具已经很有价值， +因为它可以验证示例能否成功编译（确保和代码保持同步）， +同时还可以运行那些不依赖内核 API 的示例。 + +然而，在内核中，这些测试会转换成 KUnit 测试套件。 +这意味着文档测试会被编译成 Rust 内核对象，从而可以在构建的内核环境中运行。 + +通过与 KUnit 集成，Rust 的文档测试可以复用内核现有的测试设施。 +例如，内核日志会显示:: + + KTAP version 1 + 1..1 + KTAP version 1 + # Subtest: rust_doctests_kernel + 1..59 + # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13 + ok 1 rust_doctest_kernel_build_assert_rs_0 + # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56 + ok 2 rust_doctest_kernel_build_assert_rs_1 + # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122 + ok 3 rust_doctest_kernel_init_rs_0 + ... + # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 + ok 59 rust_doctest_kernel_types_rs_2 + # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59 + # Totals: pass:59 fail:0 skip:0 total:59 + ok 1 rust_doctests_kernel + +文档测试中，也可以正常使用 `? `_ 运算符，例如： + +.. code-block:: rust + + /// ``` + /// # use kernel::{spawn_work_item, workqueue}; + /// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?; + /// # Ok::<(), Error>(()) + /// ``` + +这些测试和普通代码一样，也可以在 ``CLIPPY=1`` 条件下通过 Clippy 进行编译， +因此可以从额外的 lint 检查中获益。 + +为了便于开发者定位文档测试出错的具体行号，日志会输出一条 KTAP 诊断信息。 +其中标明了原始测试的文件和行号（不是 ``rustdoc`` 生成的临时 Rust 文件位置）:: + + # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 + +Rust 测试中常用的断言宏是来自 Rust 标准库（ ``core`` ）中的 ``assert!`` 和 ``assert_eq!`` 宏。 +内核提供了一个定制版本，这些宏的调用会被转发到 KUnit。 +和 KUnit 测试不同的是，这些宏不需要传递上下文参数（ ``struct kunit *`` ）。 +这使得它们更易于使用，同时文档的读者无需关心底层用的是什么测试框架。 +此外，这种方式未来也许可以让我们更容易测试第三方代码。 + +当前有一个限制：KUnit 不支持在其他任务中执行断言。 +因此，如果断言真的失败了，我们只是简单地把错误打印到内核日志里。 +另外，文档测试不适用于非公开的函数。 + +作为文档中的测试示例，应当像 “实际代码” 一样编写。 +例如：不要使用 ``unwrap()`` 或 ``expect()``，请使用 `? `_ 运算符。 +更多背景信息，请参阅： + + https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust + +``#[test]`` 测试 +---------------- + +此外，还有 ``#[test]`` 测试。与文档测试类似，这些测试与用户空间中的测试方式也非常相近，并且同样会映射到 KUnit。 + +这些测试通过 ``kunit_tests`` 过程宏引入，该宏将测试套件的名称作为参数。 + +例如，假设想要测试前面文档测试示例中的函数 ``f``，我们可以在定义该函数的同一文件中编写： + +.. code-block:: rust + + #[kunit_tests(rust_kernel_mymod)] + mod tests { + use super::*; + + #[test] + fn test_f() { + assert_eq!(f(10, 20), 30); + } + } + +如果我们执行这段代码，内核日志会显示:: + + KTAP version 1 + # Subtest: rust_kernel_mymod + # speed: normal + 1..1 + # test_f.speed: normal + ok 1 test_f + ok 1 rust_kernel_mymod + +与文档测试类似， ``assert!`` 和 ``assert_eq!`` 宏被映射回 KUnit 并且不会发生 panic。 +同样，支持 `? `_ 运算符， +测试函数可以什么都不返回（单元类型 ``()``）或 ``Result`` （任何 ``Result``）。例如： + +.. code-block:: rust + + #[kunit_tests(rust_kernel_mymod)] + mod tests { + use super::*; + + #[test] + fn test_g() -> Result { + let x = g()?; + assert_eq!(x, 30); + Ok(()) + } + } + +如果我们运行测试并且调用 ``g`` 失败，那么内核日志会显示:: + + KTAP version 1 + # Subtest: rust_kernel_mymod + # speed: normal + 1..1 + # test_g: ASSERTION FAILED at rust/kernel/lib.rs:335 + Expected is_test_result_ok(test_g()) to be true, but is false + # test_g.speed: normal + not ok 1 test_g + not ok 1 rust_kernel_mymod + +如果 ``#[test]`` 测试可以对用户起到示例作用，那就应该改用文档测试。 +即使是 API 的边界情况，例如错误或边界问题，放在示例中展示也同样有价值。 + +``rusttest`` 宿主机测试 +----------------------- + +这类测试运行在用户空间，可以通过 ``rusttest`` 目标在构建内核的宿主机中编译并运行:: + + make LLVM=1 rusttest + +当前操作需要内核 ``.config``。 + +目前，它们主要用于测试 ``macros`` crate 的示例。 + +Kselftests +---------- + +Kselftests 可以在 ``tools/testing/selftests/rust`` 文件夹中找到。 + +测试所需的内核配置选项列在 ``tools/testing/selftests/rust/config`` 文件中， +可以借助 ``merge_config.sh`` 脚本合并到现有配置中:: + + ./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config + +Kselftests 会在内核源码树中构建，以便在运行相同版本内核的系统上执行测试。 + +一旦安装并启动了与源码树匹配的内核，测试即可通过以下命令编译并执行:: + + make TARGETS="rust" kselftest + +请参阅 Documentation/dev-tools/kselftest.rst 文档以获取更多信息。 diff --git a/Documentation/translations/zh_CN/scsi/index.rst b/Documentation/translations/zh_CN/scsi/index.rst new file mode 100644 index 000000000000..5f1803e2706c --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/index.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/index.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +========== +SCSI子系统 +========== + +.. toctree:: + :maxdepth: 1 + +简介 +==== + +.. toctree:: + :maxdepth: 1 + + scsi + +SCSI驱动接口 +============ + +.. toctree:: + :maxdepth: 1 + + scsi_mid_low_api + scsi_eh + +SCSI驱动参数 +============ + +.. toctree:: + :maxdepth: 1 + + scsi-parameters + link_power_management_policy + +SCSI主机适配器驱动 +================== + +.. toctree:: + :maxdepth: 1 + + libsas + sd-parameters + wd719x + +Todolist: + +* 53c700 +* aacraid +* advansys +* aha152x +* aic79xx +* aic7xxx +* arcmsr_spec +* bfa +* bnx2fc +* BusLogic +* cxgb3i +* dc395x +* dpti +* FlashPoint +* g_NCR5380 +* hpsa +* hptiop +* lpfc +* megaraid +* ncr53c8xx +* NinjaSCSI +* ppa +* qlogicfas +* scsi-changer +* scsi_fc_transport +* scsi-generic +* smartpqi +* st +* sym53c500_cs +* sym53c8xx_2 +* tcm_qla2xxx +* ufs + +* scsi_transport_srp/figures diff --git a/Documentation/translations/zh_CN/scsi/libsas.rst b/Documentation/translations/zh_CN/scsi/libsas.rst new file mode 100644 index 000000000000..15fa71cdd821 --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/libsas.rst @@ -0,0 +1,425 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/libsas.rst + +:翻译: + + 张钰杰 Yujie Zhang + +:校译: + +====== +SAS 层 +====== + +SAS 层是一个管理基础架构，用于管理 SAS LLDD。它位于 SCSI Core +与 SAS LLDD 之间。 体系结构如下: SCSI Core 关注的是 SAM/SPC 相 +关的问题；SAS LLDD 及其序列控制器负责 PHY 层、OOB 信号以及链路 +管理；而 SAS 层则负责以下任务:: + + * SAS Phy、Port 和主机适配器（HA）事件管理（事件由 LLDD + 生成，由 SAS 层处理）； + * SAS 端口的管理（创建与销毁）； + * SAS 域的发现与重新验证； + * SAS 域内设备的管理； + * SCSI 主机的注册与注销； + * 将设备注册到 SCSI Core（SAS 设备）或 libata（SATA 设备）； + * 扩展器的管理，并向用户空间导出扩展器控制接口。 + +SAS LLDD 是一种 PCI 设备驱动程序。它负责 PHY 层和 OOB（带外） +信号的管理、厂商特定的任务，并向 SAS 层上报事件。 + +SAS 层实现了 SAS 1.1 规范中定义的大部分 SAS 功能。 + +sas_ha_struct 结构体用于向 SAS 层描述一个 SAS LLDD。该结构的 +大部分字段由 SAS 层使用，但其中少数字段需要由 LLDD 进行初始化。 + +在完成硬件初始化之后，应当在驱动的 probe() 函数中调用 +sas_register_ha()。该函数会将 LLDD 注册到 SCSI 子系统中，创 +建一个对应的 SCSI 主机，并将你的 SAS 驱动程序注册到其在 sysfs +下创建的 SAS 设备树中。随后该函数将返回。接着，你需要使能 PHY， +以启动实际的 OOB（带外）过程；此时驱动将开始调用 notify_* 系 +列事件回调函数。 + +结构体说明 +========== + +``struct sas_phy`` +------------------ + +通常情况下，该结构体会被静态地嵌入到驱动自身定义的 PHY 结构体中, +例如:: + + struct my_phy { + blah; + struct sas_phy sas_phy; + bleh; + } + +随后，在主机适配器（HA）的结构体中，所有的 PHY 通常以 my_phy +数组的形式存在（如下文所示）。 + +在初始化各个 PHY 时，除了初始化驱动自定义的 PHY 结构体外，还 +需要同时初始化其中的 sas_phy 结构体。 + +一般来说，PHY 的管理由 LLDD 负责，而端口（port）的管理由 SAS +层负责。因此，PHY 的初始化与更新由 LLDD 完成，而端口的初始化与 +更新则由 SAS 层完成。系统设计中规定，某些字段可由 LLDD 进行读 +写，而 SAS 层只能读取这些字段；反之亦然。其设计目的是为了避免不 +必要的锁操作。 + +在该设计中，某些字段可由 LLDD 进行读写（RW），而 SAS 层仅可读 +取这些字段；反之亦然。这样设计的目的在于避免不必要的锁操作。 + +enabled + - 必须设置(0/1) + +id + - 必须设置[0,MAX_PHYS)] + +class, proto, type, role, oob_mode, linkrate + - 必须设置。 + +oob_mode + - 当 OOB（带外信号）完成后，设置此字段，然后通知 SAS 层。 + +sas_addr + - 通常指向一个保存该 PHY 的 SAS 地址的数组，该数组可能位于 + 驱动自定义的 my_phy 结构体中。 + +attached_sas_addr + - 当 LLDD 接收到 IDENTIFY 帧或 FIS 帧时，应在通知 SAS 层 + 之前设置该字段。其设计意图在于：有时 LLDD 可能需要伪造或 + 提供一个与实际不同的 SAS 地址用于该 PHY/端口，而该机制允许 + LLDD 这样做。理想情况下，应将 SAS 地址从 IDENTIFY 帧中 + 复制过来；对于直接连接的 SATA 设备，也可以由 LLDD 生成一 + 个 SAS 地址。后续的发现过程可能会修改此字段。 + +frame_rcvd + - 当接收到 IDENTIFY 或 FIS 帧时，将该帧复制到此处。正确的 + 操作流程是获取锁 → 复制数据 → 设置 frame_rcvd_size → 释 + 放锁 → 调用事件通知。该字段是一个指针，因为驱动无法精确确 + 定硬件帧的大小；因此，实际的帧数据数组应定义在驱动自定义的 + PHY 结构体中，然后让此指针指向该数组。在持锁状态下，将帧从 + DMA 可访问内存区域复制到该数组中。 + +sas_prim + - 用于存放接收到的原语（primitive）。参见 sas.h。操作流程同 + 样是：获取锁 → 设置 primitive → 释放锁 → 通知事件。 + +port + - 如果该 PHY 属于某个端口（port），此字段指向对应的 sas_port + 结构体。LLDD 仅可读取此字段。它由 SAS 层设置，用于指向当前 + PHY 所属的 sas_port。 + +ha + - 可以由 LLDD 设置；但无论是否设置，SAS 层都会再次对其进行赋值。 + +lldd_phy + - LLDD 应将此字段设置为指向自身定义的 PHY 结构体，这样当 SAS + 层调用某个回调并传入 sas_phy 时，驱动可以快速定位自身的 PHY + 结构体。如果 sas_phy 是嵌入式成员，也可以使用 container_of() + 宏进行访问——两种方式均可。 + +``struct sas_port`` +------------------- + +LLDD 不应修改该结构体中的任何字段——它只能读取这些字段。这些字段的 +含义应当是不言自明的。 + +phy_mask 为 32 位，目前这一长度已足够使用，因为尚未听说有主机适配 +器拥有超过8 个 PHY。 + +lldd_port + - 目前尚无明确用途。不过，对于那些希望在 LLDD 内部维护自身端 + 口表示的驱动，实现时可以利用该字段。 + +``struct sas_ha_struct`` +------------------------ + +它通常静态声明在你自己的 LLDD 结构中，用于描述您的适配器:: + + struct my_sas_ha { + blah; + struct sas_ha_struct sas_ha; + struct my_phy phys[MAX_PHYS]; + struct sas_port sas_ports[MAX_PHYS]; /* (1) */ + bleh; + }; + + (1) 如果你的 LLDD 没有自己的端口表示 + +需要初始化（示例函数如下所示）。 + +pcidev +^^^^^^ + +sas_addr + - 由于 SAS 层不想弄乱内存分配等, 因此这指向静态分配的数 + 组中的某个位置（例如，在您的主机适配器结构中），并保存您或 + 制造商等给出的主机适配器的 SAS 地址。 + +sas_port +^^^^^^^^ + +sas_phy + - 指向结构体的指针数组（参见上文关于 sas_addr 的说明）。 + 这些指针必须设置。更多细节见下文说明。 + +num_phys + - 表示 sas_phy 数组中 PHY 的数量，同时也表示 sas_port + 数组中的端口数量。一个端口最多对应一个 PHY，因此最大端口数 + 等于 num_phys。因此，结构中不再单独使用 num_ports 字段， + 而仅使用 num_phys。 + +事件接口:: + + /* LLDD 调用以下函数来通知 SAS 类层发生事件 */ + void sas_notify_port_event(struct sas_phy *, enum port_event, gfp_t); + void sas_notify_phy_event(struct sas_phy *, enum phy_event, gfp_t); + +端口事件通知:: + + /* SAS 类层调用以下回调来通知 LLDD 端口事件 */ + void (*lldd_port_formed)(struct sas_phy *); + void (*lldd_port_deformed)(struct sas_phy *); + +如果 LLDD 希望在端口形成或解散时接收通知，则应将上述回调指针设 +置为符合函数类型定义的处理函数。 + +SAS LLDD 还应至少实现 SCSI 协议中定义的一种任务管理函数（TMFs）:: + + /* 任务管理函数. 必须在进程上下文中调用 */ + int (*lldd_abort_task)(struct sas_task *); + int (*lldd_abort_task_set)(struct domain_device *, u8 *lun); + int (*lldd_clear_task_set)(struct domain_device *, u8 *lun); + int (*lldd_I_T_nexus_reset)(struct domain_device *); + int (*lldd_lu_reset)(struct domain_device *, u8 *lun); + int (*lldd_query_task)(struct sas_task *); + +如需更多信息，请参考 T10.org。 + +端口与适配器管理:: + + /* 端口与适配器管理 */ + int (*lldd_clear_nexus_port)(struct sas_port *); + int (*lldd_clear_nexus_ha)(struct sas_ha_struct *); + +SAS LLDD 至少应实现上述函数中的一个。 + +PHY 管理:: + + /* PHY 管理 */ + int (*lldd_control_phy)(struct sas_phy *, enum phy_func); + +lldd_ha + - 应设置为指向驱动的主机适配器（HA）结构体的指针。如果 sas_ha_struct + 被嵌入到更大的结构体中，也可以通过 container_of() 宏来获取。 + +一个示例的初始化与注册函数可以如下所示：（该函数应在 probe() +函数的最后调用）但必须在使能 PHY 执行 OOB 之前调用:: + + static int register_sas_ha(struct my_sas_ha *my_ha) + { + int i; + static struct sas_phy *sas_phys[MAX_PHYS]; + static struct sas_port *sas_ports[MAX_PHYS]; + + my_ha->sas_ha.sas_addr = &my_ha->sas_addr[0]; + + for (i = 0; i < MAX_PHYS; i++) { + sas_phys[i] = &my_ha->phys[i].sas_phy; + sas_ports[i] = &my_ha->sas_ports[i]; + } + + my_ha->sas_ha.sas_phy = sas_phys; + my_ha->sas_ha.sas_port = sas_ports; + my_ha->sas_ha.num_phys = MAX_PHYS; + + my_ha->sas_ha.lldd_port_formed = my_port_formed; + + my_ha->sas_ha.lldd_dev_found = my_dev_found; + my_ha->sas_ha.lldd_dev_gone = my_dev_gone; + + my_ha->sas_ha.lldd_execute_task = my_execute_task; + + my_ha->sas_ha.lldd_abort_task = my_abort_task; + my_ha->sas_ha.lldd_abort_task_set = my_abort_task_set; + my_ha->sas_ha.lldd_clear_task_set = my_clear_task_set; + my_ha->sas_ha.lldd_I_T_nexus_reset= NULL; (2) + my_ha->sas_ha.lldd_lu_reset = my_lu_reset; + my_ha->sas_ha.lldd_query_task = my_query_task; + + my_ha->sas_ha.lldd_clear_nexus_port = my_clear_nexus_port; + my_ha->sas_ha.lldd_clear_nexus_ha = my_clear_nexus_ha; + + my_ha->sas_ha.lldd_control_phy = my_control_phy; + + return sas_register_ha(&my_ha->sas_ha); + } + +(2) SAS 1.1 未定义 I_T Nexus Reset TMF（任务管理功能）。 + +事件 +==== + +事件是 SAS LLDD 唯一的通知 SAS 层发生任何情况的方式。 +LLDD 没有其他方法可以告知 SAS 层其内部或 SAS 域中发生的事件。 + +Phy 事件:: + + PHYE_LOSS_OF_SIGNAL, (C) + PHYE_OOB_DONE, + PHYE_OOB_ERROR, (C) + PHYE_SPINUP_HOLD. + +端口事件，通过 _phy_ 传递:: + + PORTE_BYTES_DMAED, (M) + PORTE_BROADCAST_RCVD, (E) + PORTE_LINK_RESET_ERR, (C) + PORTE_TIMER_EVENT, (C) + PORTE_HARD_RESET. + +主机适配器事件： + HAE_RESET + +SAS LLDD 应能够生成以下事件:: + + - 来自 C 组的至少一个事件（可选）， + - 标记为 M（必需）的事件为必需事件（至少一种）； + - 若希望 SAS 层处理域重新验证（domain revalidation），则 + 应生成标记为 E（扩展器）的事件（仅需一种）； + - 未标记的事件为可选事件。 + +含义 + +HAE_RESET + - 当 HA 发生内部错误并被复位时。 + +PORTE_BYTES_DMAED + - 在接收到 IDENTIFY/FIS 帧时。 + +PORTE_BROADCAST_RCVD + - 在接收到一个原语时。 + +PORTE_LINK_RESET_ERR + - 定时器超时、信号丢失、丢失 DWS 等情况。 [1]_ + +PORTE_TIMER_EVENT + - DWS 复位超时定时器到期时。[1]_ + +PORTE_HARD_RESET + - 收到 Hard Reset 原语。 + +PHYE_LOSS_OF_SIGNAL + - 设备已断开连接。 [1]_ + +PHYE_OOB_DONE + - OOB 过程成功完成，oob_mode 有效。 + +PHYE_OOB_ERROR + - 执行 OOB 过程中出现错误，设备可能已断开。 [1]_ + +PHYE_SPINUP_HOLD + - 检测到 SATA 设备，但未发送 COMWAKE 信号。 + +.. [1] 应设置或清除 phy 中相应的字段，或者从 tasklet 中调用 + 内联函数 sas_phy_disconnected()，该函数只是一个辅助函数。 + +执行命令 SCSI RPC:: + + int (*lldd_execute_task)(struct sas_task *, gfp_t gfp_flags); + +用于将任务排队提交给 SAS LLDD，@task 为要执行的任务，@gfp_mask +为定义调用者上下文的 gfp 掩码。 + +此函数应实现 执行 SCSI RPC 命令。 + +也就是说，当调用 lldd_execute_task() 时，命令应当立即在传输 +层发出。SAS LLDD 中在任何层级上都不应再进行队列排放。 + +返回值:: + + * 返回 -SAS_QUEUE_FULL 或 -ENOMEM 表示未排入队列； + * 返回 0 表示任务已成功排入队列。 + +:: + + struct sas_task { + dev —— 此任务目标设备； + task_proto —— 协议类型，为 enum sas_proto 中的一种； + scatter —— 指向散布/聚集（SG）列表数组的指针； + num_scatter —— SG 列表元素数量； + total_xfer_len —— 预计传输的总字节数； + data_dir —— 数据传输方向(PCI_DMA_*)； + task_done —— 任务执行完成时的回调函数。 + }; + +发现 +==== + +sysfs 树有以下用途:: + + a) 它显示当前时刻 SAS 域的物理布局，即展示当前物理世界中 + 域的实际结构。 + b) 显示某些设备的参数。 _at_discovery_time_. + +下面是一个指向 tree(1) 程序的链接，该工具在查看 SAS 域时非常 +有用： +ftp://mama.indstate.edu/linux/tree/ + +我期望用户空间的应用程序最终能够为此创建一个图形界面。 + +也就是说，sysfs 域树不会显示或保存某些状态变化，例如，如果你更 +改了 READY LED 含义的设置，sysfs 树不会反映这种状态变化；但它 +确实会显示域设备的当前连接状态。 + +维护内部设备状态变化的职责由上层（命令集驱动）和用户空间负责。 + +当某个设备或多个设备从域中拔出时，这一变化会立即反映在 sysfs +树中，并且这些设备会从系统中移除。 + +结构体 domain_device 描述了 SAS 域中的任意设备。它完全由 SAS +层管理。一个任务会指向某个域设备，SAS LLDD 就是通过这种方式知 +道任务应发送到何处。SAS LLDD 只读取 domain_device 结构的内容， +但不会创建或销毁它。 + +用户空间中的扩展器管理 +====================== + +在 sysfs 中的每个扩展器目录下，都有一个名为 "smp_portal" 的 +文件。这是一个二进制的 sysfs 属性文件，它实现了一个 SMP 入口 +（注意：这并不是一个 SMP 端口），用户空间程序可以通过它发送 +SMP 请求并接收 SMP 响应。 + +该功能的实现方式看起来非常简单: + +1. 构建要发送的 SMP 帧。其格式和布局在 SAS 规范中有说明。保持 + CRC 字段为 0。 + +open(2) + +2. 以读写模式打开该扩展器的 SMP portal sysfs 文件。 + +write(2) + +3. 将第 1 步中构建的帧写入文件。 + +read(2) + +4. 读取与所构建帧预期返回长度相同的数据量。如果读取的数据量与 + 预期不符，则表示发生了某种错误。 + +close(2) + +整个过程在 "expander_conf.c" 文件中的函数 do_smp_func() +及其调用者中有详细展示。 + +对应的内核实现位于 "sas_expander.c" 文件中。 + +程序 "expander_conf.c" 实现了上述逻辑。它接收一个参数——扩展器 +SMP portal 的 sysfs 文件名，并输出扩展器的信息，包括路由表内容。 + +SMP portal 赋予了你对扩展器的完全控制权，因此请谨慎操作。 diff --git a/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst b/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst new file mode 100644 index 000000000000..f2ab8fdf4aa8 --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/link_power_management_policy.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/link_power_management_policy.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +================ +链路电源管理策略 +================ + +该参数允许用户设置链路（接口）的电源管理模式。 +共计三类可选项： + +===================== ===================================================== +选项 作用 +===================== ===================================================== +min_power 指示控制器在可能的情况下尽量使链路处于最低功耗。 + 这可能会牺牲一定的性能，因为从低功耗状态恢复时会增加延迟。 + +max_performance 通常，这意味着不进行电源管理。指示 + 控制器优先考虑性能而非电源管理。 + +medium_power 指示控制器在可能的情况下进入较低功耗状态， + 而非最低功耗状态，从而改善min_power模式下的延迟。 +===================== ===================================================== diff --git a/Documentation/translations/zh_CN/scsi/scsi-parameters.rst b/Documentation/translations/zh_CN/scsi/scsi-parameters.rst new file mode 100644 index 000000000000..ace777e070ea --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/scsi-parameters.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/scsi-parameters.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +============ +SCSI内核参数 +============ + +请查阅Documentation/admin-guide/kernel-parameters.rst以获取 +指定模块参数相关的通用信息。 + +当前文档可能不完全是最新和全面的。命令 ``modinfo -p ${modulename}`` +显示了可加载模块的参数列表。可加载模块被加载到内核中后，也会在 +/sys/module/${modulename}/parameters/ 目录下显示其参数。其 +中某些参数可以通过命令 +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}`` +在运行时修改。 + +:: + + advansys= [HW,SCSI] + 请查阅 drivers/scsi/advansys.c 文件头部。 + + aha152x= [HW,SCSI] + 请查阅 Documentation/scsi/aha152x.rst。 + + aha1542= [HW,SCSI] + 格式：[,,[,]] + + aic7xxx= [HW,SCSI] + 请查阅 Documentation/scsi/aic7xxx.rst。 + + aic79xx= [HW,SCSI] + 请查阅 Documentation/scsi/aic79xx.rst。 + + atascsi= [HW,SCSI] + 请查阅 drivers/scsi/atari_scsi.c。 + + BusLogic= [HW,SCSI] + 请查阅 drivers/scsi/BusLogic.c 文件中 + BusLogic_ParseDriverOptions()函数前的注释。 + + gvp11= [HW,SCSI] + + ips= [HW,SCSI] Adaptec / IBM ServeRAID 控制器 + 请查阅 drivers/scsi/ips.c 文件头部。 + + mac5380= [HW,SCSI] + 请查阅 drivers/scsi/mac_scsi.c。 + + scsi_mod.max_luns= + [SCSI] 最大可探测LUN数。 + 取值范围为 1 到 2^32-1。 + + scsi_mod.max_report_luns= + [SCSI] 接收到的最大LUN数。 + 取值范围为 1 到 16384。 + + NCR_D700= [HW,SCSI] + 请查阅 drivers/scsi/NCR_D700.c 文件头部。 + + ncr5380= [HW,SCSI] + 请查阅 Documentation/scsi/g_NCR5380.rst。 + + ncr53c400= [HW,SCSI] + 请查阅 Documentation/scsi/g_NCR5380.rst。 + + ncr53c400a= [HW,SCSI] + 请查阅 Documentation/scsi/g_NCR5380.rst。 + + ncr53c8xx= [HW,SCSI] + + osst= [HW,SCSI] SCSI磁带驱动 + 格式：, + 另请查阅 Documentation/scsi/st.rst。 + + scsi_debug_*= [SCSI] + 请查阅 drivers/scsi/scsi_debug.c。 + + scsi_mod.default_dev_flags= + [SCSI] SCSI默认设备标志 + 格式： + + scsi_mod.dev_flags= + [SCSI] 厂商和型号的黑/白名单条目 + 格式：:: + （flags 为整数值） + + scsi_mod.scsi_logging_level= + [SCSI] 日志级别的位掩码 + 位的定义请查阅 drivers/scsi/scsi_logging.h。 + 此参数也可以通过sysctl对dev.scsi.logging_level + 进行设置（/proc/sys/dev/scsi/logging_level）。 + 此外，S390-tools软件包提供了一个便捷的 + ‘scsi_logging_level’ 脚本，可以从以下地址下载： + https://github.com/ibm-s390-linux/s390-tools/blob/master/scripts/scsi_logging_level + + scsi_mod.scan= [SCSI] sync（默认）在发现SCSI总线过程中 + 同步扫描。async在内核线程中异步扫描，允许系统继续 + 启动流程。none忽略扫描，预期由用户空间完成扫描。 + + sim710= [SCSI,HW] + 请查阅 drivers/scsi/sim710.c 文件头部。 + + st= [HW,SCSI] SCSI磁带参数（缓冲区大小等） + 请查阅 Documentation/scsi/st.rst。 + + wd33c93= [HW,SCSI] + 请查阅 drivers/scsi/wd33c93.c 文件头部。 diff --git a/Documentation/translations/zh_CN/scsi/scsi.rst b/Documentation/translations/zh_CN/scsi/scsi.rst new file mode 100644 index 000000000000..5d6e39c7cbb5 --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/scsi.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/scsi.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +============== +SCSI子系统文档 +============== + +Linux文档项目（LDP）维护了一份描述Linux内核（lk） 2.4中SCSI +子系统的文档。请参考： +https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO 。LDP提供单页和 +多页的HTML版本，以及PostScript与PDF格式的文档。 + +在SCSI子系统中使用模块的注意事项 +================================ +Linux内核中的SCSI支持可以根据终端用户的需求以不同的方式模块 +化。为了理解你的选择，我们首先需要定义一些术语。 + +scsi-core（也被称为“中间层”）包含SCSI支持的核心。没有他你将 +无法使用任何其他SCSI驱动程序。SCSI核心支持可以是一个模块（ +scsi_mod.o），也可以编译进内核。如果SCSI核心是一个模块，那么 +他必须是第一个被加载的SCSI模块，如果你将卸载该模块，那么他必 +须是最后一个被卸载的模块。实际上，modprobe和rmmod命令将确保 +SCSI子系统中模块加载与卸载的正确顺序。 + +一旦SCSI核心存在于内核中（无论是编译进内核还是作为模块加载）， +独立的上层驱动和底层驱动可以按照任意顺序加载。磁盘驱动程序 +（sd_mod.o）、光盘驱动程序（sr_mod.o）、磁带驱动程序 [1]_ +（st.o）以及SCSI通用驱动程序（sg.o）代表了上层驱动，用于控制 +相应的各种设备。例如，你可以加载磁带驱动程序来使用磁带驱动器， +然后在不需要该驱动程序时卸载他（并释放相关内存）。 + +底层驱动程序用于支持您所运行硬件平台支持的不同主机卡。这些不同 +的主机卡通常被称为主机总线适配器（HBAs）。例如，aic7xxx.o驱动 +程序被用于控制Adaptec所属的所有最新的SCSI控制器。几乎所有的底 +层驱动都可以被编译为模块或直接编译进内核。 + +.. [1] 磁带驱动程序有一个变种用于控制OnStream磁带设备。其模块 + 名称为osst.o 。 diff --git a/Documentation/translations/zh_CN/scsi/scsi_eh.rst b/Documentation/translations/zh_CN/scsi/scsi_eh.rst new file mode 100644 index 000000000000..26e0f30f0949 --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/scsi_eh.rst @@ -0,0 +1,482 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/scsi_eh.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + +=================== +SCSI 中间层错误处理 +=================== + +本文档描述了SCSI中间层（mid layer）的错误处理基础架构。 +关于SCSI中间层的更多信息，请参阅： +Documentation/scsi/scsi_mid_low_api.rst。 + +.. 目录 + + [1] SCSI 命令如何通过中间层传递并进入错误处理（EH） + [1-1] scsi_cmnd（SCSI命令）结构体 + [1-2] scmd（SCSI 命令）是如何完成的？ + [1-2-1] 通过scsi_done完成scmd + [1-2-2] 通过超时机制完成scmd + [1-3] 错误处理模块如何接管流程 + [2] SCSI错误处理机制工作原理 + [2-1] 基于细粒度回调的错误处理 + [2-1-1] 概览 + [2-1-2] scmd在错误处理流程中的传递路径 + [2-1-3] 控制流分析 + [2-2] 通过transportt->eh_strategy_handler()实现的错误处理 + [2-2-1] transportt->eh_strategy_handler()调用前的中间层状态 + [2-2-2] transportt->eh_strategy_handler()调用后的中间层状态 + [2-2-3] 注意事项 + + +1. SCSI命令在中间层及错误处理中的传递流程 +========================================= + +1.1 scsi_cmnd结构体 +------------------- + +每个SCSI命令都由struct scsi_cmnd（简称scmd）结构体 +表示。scmd包含两个list_head类型的链表节点：scmd->list +与scmd->eh_entry。其中scmd->list是用于空闲链表或设备 +专属的scmd分配链表，与错误处理讨论关联不大。而 +scmd->eh_entry则是专用于命令完成和错误处理链表，除非 +特别说明，本文讨论中所有scmd的链表操作均通过 +scmd->eh_entry实现。 + + +1.2 scmd是如何完成的？ +---------------------- + +底层设备驱动（LLDD）在获取SCSI命令（scmd）后，存在两种 +完成路径：底层驱动可通过调用hostt->queuecommand()时从 +中间层传递的scsi_done回调函数主动完成命令，或者当命令未 +及时完成时由块层（block layer）触发超时处理机制。 + + +1.2.1 通过scsi_done回调完成SCSI命令 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +对于所有非错误处理（EH）命令，scsi_done()是其完成回调 +函数。它只调用blk_mq_complete_request()来删除块层的 +定时器并触发块设备软中断（BLOCK_SOFTIRQ）。 + +BLOCK_SOFTIRQ会间接调用scsi_complete()，进而调用 +scsi_decide_disposition()来决定如何处理该命令。 +scsi_decide_disposition()会查看scmd->result值和感 +应码数据来决定如何处理命令。 + + - SUCCESS + + 调用scsi_finish_command()来处理该命令。该函数会 + 执行一些维护操作，然后调用scsi_io_completion()来 + 完成I/O操作。scsi_io_completion()会通过调用 + blk_end_request及其相关函数来通知块层该请求已完成， + 如果发生错误，还会判断如何处理剩余的数据。 + + - NEEDS_RETRY + + - ADD_TO_MLQUEUE + + scmd被重新加入到块设备队列中。 + + - otherwise + + 调用scsi_eh_scmd_add(scmd)来处理该命令。 + 关于此函数的详细信息，请参见 [1-3]。 + + +1.2.2 scmd超时完成机制 +^^^^^^^^^^^^^^^^^^^^^^ + +SCSI命令超时处理机制由scsi_timeout()函数实现。 +当发生超时事件时，该函数 + + 1. 首先调用可选的hostt->eh_timed_out()回调函数。 + 返回值可能是以下3种情况之一： + + - ``SCSI_EH_RESET_TIMER`` + 表示需要延长命令执行时间并重启计时器。 + + - ``SCSI_EH_NOT_HANDLED`` + 表示eh_timed_out()未处理该命令。 + 此时将执行第2步的处理流程。 + + - ``SCSI_EH_DONE`` + 表示eh_timed_out()已完成该命令。 + + 2. 若未通过回调函数解决，系统将调用 + scsi_abort_command()发起异步中止操作，该操作最多 + 可执行scmd->allowed + 1次。但存在三种例外情况会跳 + 过异步中止而直接进入第3步处理：当检测到 + SCSI_EH_ABORT_SCHEDULED标志位已置位（表明该命令先 + 前已被中止过一次且当前重试仍失败）、当重试次数已达上 + 限、或当错误处理时限已到期时。在这些情况下，系统将跳 + 过异步中止流程而直接执行第3步处理方案。 + + 3. 最终未解决的命令会通过scsi_eh_scmd_add(scmd)移交给 + 错误处理子系统，具体流程详见[1-4]章节说明。 + +1.3 异步命令中止机制 +-------------------- + +当命令超时触发后，系统会通过scsi_abort_command()调度异 +步中止操作。若中止操作执行成功，则根据重试次数决定后续处 +理：若未达最大重试限制，命令将重新下发执行；若重试次数已 +耗尽，则命令最终以DID_TIME_OUT状态终止。当中止操作失败 +时，系统会调用scsi_eh_scmd_add()将该命令移交错误处理子 +系统，具体处理流程详见[1-4]。 + +1.4 错误处理(EH)接管机制 +------------------------ + +SCSI命令通过scsi_eh_scmd_add()函数进入错误处理流程，该函 +数执行以下操作： + + 1. 将scmd->eh_entry链接到shost->eh_cmd_q + + 2. 在shost->shost_state中设置SHOST_RECOVERY状态位 + + 3. 递增shost->host_failed失败计数器 + + 4. 当检测到shost->host_busy == shost->host_failed + 时（即所有进行中命令均已失败）立即唤醒SCSI错误处理 + 线程。 + +如上所述，当任一scmd被加入到shost->eh_cmd_q队列时，系统 +会立即置位shost_state中的SHOST_RECOVERY状态标志位，该操 +作将阻止块层向对应主机控制器下发任何新的SCSI命令。在此状 +态下，主机控制器上所有正在处理的scmd最终会进入以下三种状 +态之一：正常完成、失败后被移入到eh_cmd_q队列、或因超时被 +添加到shost->eh_cmd_q队列。 + +如果所有的SCSI命令都已经完成或失败，系统中正在执行的命令 +数量与失败命令数量相等（ +即shost->host_busy == shost->host_failed），此时将唤 +醒SCSI错误处理线程。SCSI错误处理线程一旦被唤醒，就可以确 +保所有未完成命令均已标记为失败状态，并且已经被链接到 +shost->eh_cmd_q队列中。 + +需要特别说明的是，这并不意味着底层处理流程完全静止。当底层 +驱动以错误状态完成某个scmd时，底层驱动及其下层组件会立刻遗 +忘该命令的所有关联状态。但对于超时命令，除非 +hostt->eh_timed_out()回调函数已经明确通知底层驱动丢弃该 +命令（当前所有底层驱动均未实现此功能），否则从底层驱动视角 +看该命令仍处于活跃状态，理论上仍可能在某时刻完成。当然，由 +于超时计时器早已触发，所有此类延迟完成都将被系统直接忽略。 + +我们将在后续章节详细讨论关于SCSI错误处理如何执行中止操作（ +即强制底层驱动丢弃已超时SCSI命令）。 + + +2. SCSI错误处理机制详解 +======================= + +SCSI底层驱动可以通过以下两种方式之一来实现SCSI错误处理。 + + - 细粒度的错误处理回调机制 + 底层驱动可选择实现细粒度的错误处理回调函数，由SCSI中间层 + 主导错误恢复流程并自动调用对应的回调函数。此实现模式的详 + 细设计规范在[2-1]节中展开讨论。 + + - eh_strategy_handler()回调函数 + 该回调函数作为统一的错误处理入口，需要完整实现所有的恢复 + 操作。具体而言，它必须涵盖SCSI中间层在常规恢复过程中执行 + 的全部处理流程，相关实现将在[2-2]节中详细描述。 + +当错误恢复流程完成后，SCSI错误处理系统通过调用 +scsi_restart_operations()函数恢复正常运行，该函数按顺序执行 +以下操作： + + 1. 验证是否需要执行驱动器安全门锁定机制 + + 2. 清除shost_state中的SHOST_RECOVERY状态标志位 + + 3. 唤醒所有在shost->host_wait上等待的任务。如果有人调用了 + scsi_block_when_processing_errors()则会发生这种情况。 + （疑问：由于错误处理期间块层队列已被阻塞，为何仍需显式 + 唤醒？） + + 4. 强制激活该主机控制器下所有设备的I/O队列 + + +2.1 基于细粒度回调的错误处理机制 +-------------------------------- + +2.1.1 概述 +^^^^^^^^^^^ + +如果不存在eh_strategy_handler()，SCSI中间层将负责驱动的 +错误处理。错误处理（EH）的目标有两个：一是让底层驱动程序、 +主机和设备不再维护已超时的SCSI命令（scmd）；二是使他们准备 +好接收新命令。当一个SCSI命令（scmd）被底层遗忘且底层已准备 +好再次处理或拒绝该命令时，即可认为该scmd已恢复。 + +为实现这些目标，错误处理（EH）会逐步执行严重性递增的恢复 +操作。部分操作通过下发SCSI命令完成，而其他操作则通过调用 +以下细粒度的错误处理回调函数实现。这些回调函数可以省略， +若被省略则默认始终视为执行失败。 + +:: + + int (* eh_abort_handler)(struct scsi_cmnd *); + int (* eh_device_reset_handler)(struct scsi_cmnd *); + int (* eh_bus_reset_handler)(struct scsi_cmnd *); + int (* eh_host_reset_handler)(struct scsi_cmnd *); + +只有在低级别的错误恢复操作无法恢复部分失败的SCSI命令 +（scmd）时，才会采取更高级别的恢复操作。如果最高级别的错误 +处理失败，就意味着整个错误恢复（EH）过程失败，所有未能恢复 +的设备被强制下线。 + +在恢复过程中，需遵循以下规则： + + - 错误恢复操作针对待处理列表eh_work_q中的失败的scmds执 + 行。如果某个恢复操作成功恢复了一个scmd，那么该scmd会 + 从eh_work_q链表中移除。 + + 需要注意的是，对某个scmd执行的单个恢复操作可能会恢复 + 多个scmd。例如，对某个设备执行复位操作可能会恢复该设 + 备上所有失败的scmd。 + + - 仅当低级别的恢复操作完成且eh_work_q仍然非空时，才会 + 触发更高级别的操作 + + - SCSI错误恢复机制会重用失败的scmd来发送恢复命令。对于 + 超时的scmd，SCSI错误处理机制会确保底层驱动在重用scmd + 前已不再维护该命令。 + +当一个SCSI命令（scmd）被成功恢复后，错误处理逻辑会通过 +scsi_eh_finish_cmd()将其从待处理队列（eh_work_q）移 +至错误处理的本地完成队列（eh_done_q）。当所有scmd均恢 +复完成（即eh_work_q为空时），错误处理逻辑会调用 +scsi_eh_flush_done_q()对这些已恢复的scmd进行处理，即 +重新尝试或错误总终止（向上层通知失败）。 + +SCSI命令仅在满足以下全部条件时才会被重试：对应的SCSI设 +备仍处于在线状态，未设置REQ_FAILFAST标志或递增后的 +scmd->retries值仍小于scmd->allowed。 + +2.1.2 SCSI命令在错误处理过程中的流转路径 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 1. 错误完成/超时 + + :处理: 调用scsi_eh_scmd_add()处理scmd + + - 将scmd添加到shost->eh_cmd_q + - 设置SHOST_RECOVERY标记位 + - shost->host_failed++ + + :锁要求: shost->host_lock + + 2. 启动错误处理（EH） + + :操作: 将所有scmd移动到EH本地eh_work_q队列，并 + 清空 shost->eh_cmd_q。 + + :锁要求: shost->host_lock（非严格必需，仅为保持一致性） + + 3. scmd恢复 + + :操作: 调用scsi_eh_finish_cmd()完成scmd的EH + + - 将scmd从本地eh_work_q队列移至本地eh_done_q队列 + + :锁要求: 无 + + :并发控制: 每个独立的eh_work_q至多一个线程，确保无锁 + 队列的访问 + + 4. EH完成 + + :操作: 调用scsi_eh_flush_done_q()重试scmd或通知上层处理 + 失败。此函数可以被并发调用，但每个独立的eh_work_q队 + 列至多一个线程，以确保无锁队列的访问。 + + - 从eh_done_q队列中移除scmd，清除scmd->eh_entry + - 如果需要重试，调用scsi_queue_insert()重新入队scmd + - 否则，调用scsi_finish_command()完成scmd + - 将shost->host_failed置为零 + + :锁要求: 队列或完成函数会执行适当的加锁操作 + + +2.1.3 控制流 +^^^^^^^^^^^^ + + 通过细粒度回调机制执行的SCSI错误处理（EH）是从 + scsi_unjam_host()函数开始的 + +``scsi_unjam_host`` + + 1. 持有shost->host_lock锁，将shost->eh_cmd_q中的命令移动 + 到本地的eh_work_q队里中，并释放host_lock锁。注意，这一步 + 会清空shost->eh_cmd_q。 + + 2. 调用scsi_eh_get_sense函数。 + + ``scsi_eh_get_sense`` + + 该操作针对没有有效感知数据的错误完成命令。大部分SCSI传输协议 + 或底层驱动在命令失败时会自动获取感知数据（自动感知）。出于性 + 能原因，建议使用自动感知，推荐使用自动感知机制，因为它不仅有 + 助于提升性能，还能避免从发生CHECK CONDITION到执行本操作之间， + 感知信息出现不同步的问题。 + + 注意，如果不支持自动感知，那么在使用scsi_done()以错误状态完成 + scmd 时，scmd->sense_buffer将包含无效感知数据。在这种情况下， + scsi_decide_disposition()总是返回FAILED从而触发SCSI错误处理 + （EH）。当该scmd执行到这里时，会重新获取感知数据，并再次调用 + scsi_decide_disposition()进行处理。 + + 1. 调用scsi_request_sense()发送REQUEST_SENSE命令。如果失败， + 则不采取任何操作。请注意，不采取任何操作会导致对该scmd执行 + 更高级别的恢复操作。 + + 2. 调用scsi_decide_disposition()处理scmd + + - SUCCESS + scmd->retries被设置为scmd->allowed以防止 + scsi_eh_flush_done_q()重试该scmd，并调用 + scsi_eh_finish_cmd()。 + + - NEEDS_RETRY + 调用scsi_eh_finish_cmd() + + - 其他情况 + 无操作。 + + 4. 如果!list_empty(&eh_work_q)，则调用scsi_eh_ready_devs()。 + + ``scsi_eh_ready_devs`` + + 该函数采取四种逐步增强的措施，使失败的设备准备好处理新的命令。 + + 1. 调用scsi_eh_stu() + + ``scsi_eh_stu`` + + 对于每个具有有效感知数据且scsi_check_sense()判断为失败的 + scmd发送START STOP UNIT（STU）命令且将start置1。注意，由 + 于我们明确选择错误完成的scmd，可以确定底层驱动已不再维护该 + scmd，我们可以重用它进行STU。 + + 如果STU操作成功且sdev处于离线或就绪状态，所有在sdev上失败的 + scmd都会通过scsi_eh_finish_cmd()完成。 + + *注意* 如果hostt->eh_abort_handler()未实现或返回失败，可能 + 此时仍有超时的scmd，此时STU不会导致底层驱动不再维护scmd。但 + 是，如果STU执行成功，该函数会通过scsi_eh_finish_cmd()来完成 + sdev上的所有scmd，这会导致底层驱动处于不一致的状态。看来STU + 操作应仅在sdev不包含超时scmd时进行。 + + 2. 如果!list_empty(&eh_work_q)，调用scsi_eh_bus_device_reset()。 + + ``scsi_eh_bus_device_reset`` + + 此操作与scsi_eh_stu()非常相似，区别在于使用 + hostt->eh_device_reset_handler()替代STU命令。此外，由于我们 + 没有发送SCSI命令且重置会清空该sdev上所有的scmd，所以无需筛选错 + 误完成的scmd。 + + 3. 如果!list_empty(&eh_work_q)，调用scsi_eh_bus_reset()。 + + ``scsi_eh_bus_reset`` + + 对于每个包含失败scmd的SCSI通道调用 + hostt->eh_bus_reset_handler()。如果总线重置成功，那么该通道上 + 所有准备就绪或离线状态sdev上的失败scmd都会被处理处理完成。 + + 4. 如果!list_empty(&eh_work_q)，调用scsi_eh_host_reset()。 + + ``scsi_eh_host_reset`` + + 调用hostt->eh_host_reset_handler()是最终的手段。如果SCSI主机 + 重置成功，主机上所有就绪或离线sdev上的失败scmd都会通过错误处理 + 完成。 + + 5. 如果!list_empty(&eh_work_q)，调用scsi_eh_offline_sdevs()。 + + ``scsi_eh_offline_sdevs`` + + 离线所有包含未恢复scmd的所有sdev，并通过 + scsi_eh_finish_cmd()完成这些scmd。 + + 5. 调用scsi_eh_flush_done_q()。 + + ``scsi_eh_flush_done_q`` + + 此时所有的scmd都已经恢复（或放弃），并通过 + scsi_eh_finish_cmd()函数加入eh_done_q队列。该函数通过 + 重试或显示通知上层scmd的失败来刷新eh_done_q。 + + +2.2 基于transportt->eh_strategy_handler()的错误处理机制 +------------------------------------------------------------- + +在该机制中，transportt->eh_strategy_handler()替代 +scsi_unjam_host()的被调用，并负责整个错误恢复过程。该处理 +函数完成后应该确保底层驱动不再维护任何失败的scmd并且将设备 +设置为就绪（准备接收新命令）或离线状态。此外，该函数还应该 +执行SCSI错误处理的维护任务，以维护SCSI中间层的数据完整性。 +换句话说，eh_strategy_handler()必须实现[2-1-2]中除第1步 +外的所有步骤。 + + +2.2.1 transportt->eh_strategy_handler()调用前的SCSI中间层状态 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 进入该处理函数时，以下条件成立。 + + - 每个失败的scmd的eh_flags字段已正确设置。 + + - 每个失败的scmd通过scmd->eh_entry链接到scmd->eh_cmd_q队列。 + + - 已设置SHOST_RECOVERY标志。 + + - `shost->host_failed == shost->host_busy`。 + +2.2.2 transportt->eh_strategy_handler()调用后的SCSI中间层状态 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + 从该处理函数退出时，以下条件成立。 + + - shost->host_failed为零。 + + - shost->eh_cmd_q被清空。 + + - 每个scmd->eh_entry被清空。 + + - 对每个scmd必须调用scsi_queue_insert()或scsi_finish_command()。 + 注意，该处理程序可以使用scmd->retries（剩余重试次数）和 + scmd->allowed（允许重试次数）限制重试次数。 + + +2.2.3 注意事项 +^^^^^^^^^^^^^^ + + - 需明确已超时的scmd在底层仍处于活跃状态，因此在操作这些 + scmd前，必须确保底层已彻底不再维护。 + + - 访问或修改shost数据结构时，必须持有shost->host_lock锁 + 以维持数据一致性。 + + - 错误处理完成后，每个故障设备必须彻底清除所有活跃SCSI命 + 令（scmd）的关联状态。 + + - 错误处理完成后，每个故障设备必须被设置为就绪（准备接收 + 新命令）或离线状态。 + + +Tejun Heo +htejun@gmail.com + +11th September 2005 diff --git a/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst b/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst new file mode 100644 index 000000000000..f701945a1b1c --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/scsi_mid_low_api.rst @@ -0,0 +1,1174 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/scsi_mid_low_api.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +========================= +SCSI中间层 — 底层驱动接口 +========================= + +简介 +==== +本文档概述了Linux SCSI中间层与SCSI底层驱动之间的接口。底层 +驱动（LLD）通常被称为主机总线适配器（HBA）驱动或主机驱动 +（HD）。在该上下文中，“主机”指的是计算机IO总线（例如：PCI总 +线或ISA总线）与SCSI传输层中单个SCSI启动器端口之间的桥梁。 +“启动器”端口（SCSI术语，参考SAM-3：http://www.t10.org）向 +“目标”SCSI端口（例如：磁盘）发送SCSI命令。在一个运行的系统 +中存在多种底层驱动（LLDs），但每种硬件类型仅对应一种底层驱动 +（LLD）。大多数底层驱动可以控制一个或多个SCSI HBA。部分HBA +内部集成多个主机控制器。 + +在某些情况下，SCSI传输层本身是已存在于Linux中的外部总线子系 +统（例如：USB和ieee1394）。在此类场景下，SCSI子系统的底层驱 +动将作为与其他驱动子系统的软件桥接层。典型示例包括 +usb-storage驱动（位于drivers/usb/storage目录）以 +及ieee1394/sbp2驱动（位于 drivers/ieee1394 目录）。 + +例如，aic7xxx底层驱动负责控制基于Adaptec公司7xxx芯片系列的 +SCSI并行接口（SPI）控制器。aic7xxx底层驱动可以内建到内核中 +或作为模块加载。一个Linux系统中只能运行一个aic7xxx底层驱动 +程序，但他可能控制多个主机总线适配器（HBA）。这些HBA可能位于 +PCI扩展卡或内置于主板中（或两者兼有）。某些基于aic7xxx的HBA +采用双控制器设计，因此会呈现为两个SCSI主机适配器。与大多数现 +代HBA相同，每个aic7xxx控制器都拥有其独立的PCI设备地址。[SCSI +主机与PCI设备之间一一对应虽然常见，但并非强制要求（例如ISA适 +配器就不适用此规则）。] + +SCSI中间层将SCSI底层驱动（LLD）与其他层（例如SCSI上层驱动以 +及块层）隔离开来。 + +本文档的版本大致与Linux内核2.6.8相匹配。 + +文档 +==== +内核源码树中设有专用的SCSI文档目录，通常位于 +Documentation/scsi目录下。大多数文档采用 +reStructuredText格式。本文档名为 +scsi_mid_low_api.rst，可在该目录中找到。该文档的最新版本可 +以访问 https://docs.kernel.org/scsi/scsi_mid_low_api.html +查阅。许多底层驱动（LLD）的文档也位于Documentation/scsi目录 +下（例如aic7xxx.rst）。SCSI中间层的简要说明见scsi.rst文件， +该文档包含指向Linux Kernel 2.4系列SCSI子系统的文档链接。此 +外还收录了两份SCSI上层驱动文档：st.rst（SCSI磁带驱动）与 +scsi-generic.rst（用通用SCSI（sg）驱动）。 + +部分底层驱动的文档（或相关URL）可能嵌在C源代码文件或与其 +源码同位于同一目录下。例如，USB大容量存储驱动的文档链接可以在 +目录/usr/src/linux/drivers/usb/storage下找到。 + +驱动程序结构 +============ +传统上，SCSI子系统的底层驱动（LLD）至少包含drivers/scsi +目录下的两个文件。例如，一个名为“xyz”的驱动会包含一个头文件 +xyz.h和一个源文件xyz.c。[实际上所有代码完全可以合并为单个 +文件，头文件并非必需的。] 部分需要跨操作系统移植的底层驱动会 +采用更复杂的文件结构。例如，aic7xxx驱动，就为通用代码与操作 +系统专用代码（如FreeBSD和Linux）分别创建了独立的文件。此类 +驱动通常会在drivers/scsi目录下拥有自己单独的子目录。 + +当需要向Linux内核添加新的底层驱动（LLD）时，必须留意 +drivers/scsi目录下的两个文件：Makefile以及Kconfig。建议参 +考现有底层驱动的代码组织方式。 + +随着Linux内核2.5开发内核逐步演进为2.6系列的生产版本，该接口 +也引入了一些变化。以驱动初始化代码为例，现有两种模型可用。其 +中旧模型与Linux内核2.4的实现相似，他基于在加载HBA驱动时检测 +到的主机，被称为“被动（passive）”初始化模型。而新的模型允许 +在底层驱动（LLD）的生命周期内动态拔插HBA，这种方式被称为“热 +插拔（hotplug）”初始化模型。推荐使用新的模型，因为他既能处理 +传统的永久连接SCSI设备，也能处理现代支持热插拔的类SCSI设备 +（例如通过USB或IEEE 1394连接的数码相机）。这两种初始化模型将 +在后续的章节中分别讨论。 + +SCSI底层驱动（LLD）通过以下3种方式与SCSI子系统进行交互： + + a) 直接调用由SCSI中间层提供的接口函数 + b) 将一组函数指针传递给中间层提供的注册函数，中间层将在 + 后续运行的某个时刻调用这些函数。这些函数由LLD实现。 + c) 直接访问中间层维护的核心数据结构 + +a）组中所涉及的所有函数，均列于下文“中间层提供的函数”章节中。 + +b）组中涉及的所有函数均列于下文名为“接口函数”的章节中。这些 +函数指针位于结构体struct scsi_host_template中，该结构体实 +例会被传递给scsi_host_alloc()。对于LLD未实现的接口函数，应 +对struct scsi_host_template中的对应成员赋NULL。如果在文件 +作用域定义一个struct scsi_host_template的实例，没有显式初 +始化的函数指针成员将自动设置为NULL。 + +c）组中提到的用法在“热插拔”环境中尤其需要谨慎处理。LLD必须 +明确知晓这些与中间层及其他层级共享的数据结构的生命周期。 + +LLD中定义的所有函数以及在文件作用域内定义的所有数据都应声明 +为static。例如，在一个名为“xxx”的LLD中的sdev_init()函数定 +义如下： +``static int xxx_sdev_init(struct scsi_device * sdev) { /* code */ }`` + +热插拔初始化模型 +================ +在该模型中，底层驱动（LLD）控制SCSI主机适配器在子系统中的注 +册与注销时机。主机最早可以在驱动初始化阶段被注册，最晚可以在 +驱动卸载时被移除。通常，驱动会响应来自sysfs probe()的回调， +表示已检测到一个主机总线适配器（HBA）。在确认该新设备是LLD的 +目标设备后，LLD初始化HBA，并将一个新的SCSI主机适配器注册到 +SCSI中间层。 + +在LLD初始化过程中，驱动应当向其期望发现HBA的IO总线（例如PCI +总线）进行注册。该操作通常可以通过sysfs完成。任何驱动参数（ +特别是那些在驱动加载后仍可修改的参数）也可以在此时通过sysfs +注册。当LLD注册其首个HBA时，SCSI中间层首次感受到该LLD的存在。 + +在稍后的某个时间点，当LLD检测到新的HBA时，接下来在LLD与SCSI +中间层之间会发生一系列典型的调用过程。该示例展示了中间层如何 +扫描新引入的HBA，在该过程中发现了3个SCSI设备，其中只有前两个 +设备有响应:: + + HBA探测：假设在扫描中发现2个SCSI设备 + 底层驱动 中间层 底层驱动 + =======---------------======---------------======= + scsi_host_alloc() --> + scsi_add_host() ----> + scsi_scan_host() -------+ + | + sdev_init() + sdev_configure() --> scsi_change_queue_depth() + | + sdev_init() + sdev_configure() + | + sdev_init() *** + sdev_destroy() *** + + + *** 对于SCSI中间层尝试扫描但未响应的SCSI设备，系统调用 + sdev_init()和sdev_destroy()函数对。 + +如果LLD期望调整默认队列设置，可以在其sdev_configure()例程 +中调用scsi_change_queue_depth()。 + +当移除一个HBA时，可能是由于卸载LLD模块相关的有序关闭（例如通 +过rmmod命令），也可能是由于sysfs的remove()回调而触发的“热拔 +插”事件。无论哪种情况，其执行顺序都是相同的:: + + HBA移除：假设连接了2个SCSI设备 + 底层驱动 中间层 底层驱动 + =======---------------------======-----------------======= + scsi_remove_host() ---------+ + | + sdev_destroy() + sdev_destroy() + scsi_host_put() + +LLD用于跟踪struct Scsi_Host的实例可能会非常有用 +（scsi_host_alloc()返回的指针）。这些实例由中间层“拥有”。 +当引用计数为零时，struct Scsi_Host实例会被 +scsi_host_put()释放。 + +HBA的热插拔是一个特殊的场景，特别是当HBA下的磁盘正在处理已挂 +载文件系统上的SCSI命令时。为了应对其中的诸多问题，中间层引入 +了引用计数逻辑。具体内容参考下文关于引用计数的章节。 + +热插拔概念同样适用于SCSI设备。目前，当添加HBA时， +scsi_scan_host() 函数会扫描该HBA所属SCSI传输通道上的设备。在 +新型SCSI传输协议中，HBA可能在扫描完成后才检测到新的SCSI设备。 +LLD可通过以下步骤通知中间层新SCSI设备的存在:: + + SCSI设备热插拔 + 底层驱动 中间层 底层驱动 + =======-------------------======-----------------======= + scsi_add_device() ------+ + | + sdev_init() + sdev_configure() [--> scsi_change_queue_depth()] + +类似的，LLD可能会感知到某个SCSI设备已经被移除（拔出）或与他的连 +接已中断。某些现有的SCSI传输协议（例如SPI）可能直到后续SCSI命令 +执行失败时才会发现设备已经被移除，中间层会将该设备设置为离线状态。 +若LLD检测到SCSI设备已经被移除，可通过以下流程触发上层对该设备的 +移除操作:: + + SCSI设备热拔插 + 底层驱动 中间层 底层驱动 + =======-------------------======-----------------======= + scsi_remove_device() -------+ + | + sdev_destroy() + +对于LLD而言，跟踪struct scsi_device实例可能会非常有用（该结构 +的指针会作为参数传递给sdev_init()和sdev_configure()回调函数）。 +这些实例的所有权归属于中间层（mid-level）。struct scsi_device +实例在sdev_destroy()执行后释放。 + +引用计数 +======== +Scsi_Host结构体已引入引用计数机制。该机制将struct Scsi_Host +实例的所有权分散到使用他的各SCSI层，而此前这类实例完全由中间 +层独占管理。底层驱动（LLD）通常无需直接操作这些引用计数，仅在 +某些特定场景下可能需要介入。 + +与struct Scsi_Host相关的引用计数函数主要有以下3种： + + - scsi_host_alloc(): + 返回指向新实例的指针，该实例的引用计数被设置为1。 + + - scsi_host_get(): + 给定实例的引用计数加1。 + + - scsi_host_put(): + 给定实例的引用计数减1。如果引用计数减少到0，则释放该实例。 + +scsi_device结构体现已引入引用计数机制。该机制将 +struct scsi_device实例的所有权分散到使用他的各SCSI层，而此 +前这类实例完全由中间层独占管理。相关访问函数声明详见 +include/scsi/scsi_device.h文件末尾部分。若LLD需要保留 +scsi_device实例的指针副本，则应调用scsi_device_get()增加其 +引用计数；不再需要该指针时，可通过scsi_device_put()递减引用 +计数（该操作可能会导致该实例被释放）。 + +.. Note:: + + struct Scsi_Host实际上包含两个并行维护的引用计数器，该引 + 用计数由这些函数共同操作。 + +编码规范 +======== + +首先，Linus Torvalds关于C语言编码风格的观点可以在 +Documentation/process/coding-style.rst文件中找到。 + +此外，在相关gcc编译器支持的前提下，鼓励使用大多数C99标准的增强 +特性。因此，在适当的情况下鼓励使用C99风格的结构体和数组初始化 +方式。但不要过度使用，目前对可变长度数组（VLA）的支持还待完善。 +一个例外是 ``//`` 风格的注释；在Linux中倾向于使 +用 ``/*...*/`` 注释格式。 + +对于编写良好、经过充分测试且有完整文档的代码不需要重新格式化 +以符合上述规范。例如，aic7xxx驱动是从FreeBSD和Adaptec代码库 +移植到Linux的。毫无疑问，FreeBSD和Adaptec遵循其原有的编码规 +范。 + + +中间层提供的函数 +================ +这些函数由SCSI中间层提供，供底层驱动（LLD）调用。这些函数的名 +称（即入口点）均已导出，因此作为模块加载的LLD可以访问他们。内 +核会确保在任何LLD初始化之前，SCSI中间层已先行加载并完成初始化。 +下文按字母顺序列出这些函数，其名称均以 ``scsi_`` 开头。 + +摘要： + + - scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例 + - scsi_add_host - 执行sysfs注册并设置传输类 + - scsi_change_queue_depth - 调整SCSI设备队列深度 + - scsi_bios_ptable - 返回块设备分区表的副本 + - scsi_block_requests - 阻止向指定主机提交新命令 + - scsi_host_alloc - 分配引用计数为1的新SCSI主机适配器实例scsi_host + - scsi_host_get - 增加SCSI主机适配器实例的引用计数 + - scsi_host_put - 减少SCSI主机适配器的引用计数（归零时释放） + - scsi_remove_device - 卸载并移除SCSI设备 + - scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备 + - scsi_report_bus_reset - 报告检测到的SCSI总线复位事件 + - scsi_scan_host - 执行SCSI总线扫描 + - scsi_track_queue_full - 跟踪连续出现的队列满事件 + - scsi_unblock_requests - 恢复向指定主机提交命令 + +详细信息:: + + /** + * scsi_add_device - 创建新的SCSI逻辑单元（LU）设备实例 + * @shost: 指向SCSI主机适配器实例的指针 + * @channel: 通道号（通常为0） + * @id: 目标ID号 + * @lun: 逻辑单元号（LUN） + * + * 返回指向新的struct scsi_device实例的指针， + * 如果出现异常（例如在给定地址没有设备响应），则返 + * 回ERR_PTR(-ENODEV) + * + * 是否阻塞：是 + * + * 注意事项：本函数通常在添加HBA的SCSI总线扫描过程 + * 中由系统内部调用（即scsi_scan_host()执行期间）。因此， + * 仅应在以下情况调用：HBA在scsi_scan_host()完成扫描后， + * 又检测到新的SCSI设备（逻辑单元）。若成功执行，本次调用 + * 可能会触发LLD的以下回调函数：sdev_init()以及 + * sdev_configure() + * + * 函数定义：drivers/scsi/scsi_scan.c + **/ + struct scsi_device * scsi_add_device(struct Scsi_Host *shost, + unsigned int channel, + unsigned int id, unsigned int lun) + + + /** + * scsi_add_host - 执行sysfs注册并设置传输类 + * @shost: 指向SCSI主机适配器实例的指针 + * @dev: 指向scsi类设备结构体（struct device）的指针 + * + * 成功返回0，失败返回负的errno（例如：-ENOMEM） + * + * 是否阻塞：否 + * + * 注意事项：仅在“热插拔初始化模型”中需要调用，且必须在 + * scsi_host_alloc()成功执行后调用。该函数不会扫描总线； + * 总线扫描可通过调用scsi_scan_host()或其他传输层特定的 + * 方法完成。在调用该函数之前，LLD必须先设置好传输模板， + * 并且只能在调用该函数之后才能访问传输类 + * （transport class）相关的数据结构。 + * + * 函数定义：drivers/scsi/hosts.c + **/ + int scsi_add_host(struct Scsi_Host *shost, struct device * dev) + + + /** + * scsi_change_queue_depth - 调整SCSI设备队列深度 + * @sdev: 指向要更改队列深度的SCSI设备的指针 + * @tags 如果启用了标记队列，则表示允许的标记数， + * 或者在非标记模式下，LLD可以排队的命令 + * 数（如 cmd_per_lun）。 + * + * 无返回 + * + * 是否阻塞：否 + * + * 注意事项：可以在任何时刻调用该函数，只要该SCSI设备受该LLD控 + * 制。[具体来说，可以在sdev_configure()执行期间或之后，且在 + * sdev_destroy()执行之前调用。] 该函数可安全地在中断上下文中 + * 调用。 + * + * 函数定义：drivers/scsi/scsi.c [更多注释请参考源代码] + **/ + int scsi_change_queue_depth(struct scsi_device *sdev, int tags) + + + /** + * scsi_bios_ptable - 返回块设备分区表的副本 + * @dev: 指向块设备的指针 + * + * 返回指向分区表的指针，失败返回NULL + * + * 是否阻塞：是 + * + * 注意事项：调用方负责释放返回的内存（通过 kfree() 释放） + * + * 函数定义：drivers/scsi/scsicam.c + **/ + unsigned char *scsi_bios_ptable(struct block_device *dev) + + + /** + * scsi_block_requests - 阻止向指定主机提交新命令 + * + * @shost: 指向特定主机的指针，用于阻止命令的发送 + * + * 无返回 + * + * 是否阻塞：否 + * + * 注意事项：没有定时器或其他任何机制可以解除阻塞，唯一的方式 + * 是由LLD调用scsi_unblock_requests()方可恢复。 + * + * 函数定义：drivers/scsi/scsi_lib.c + **/ + void scsi_block_requests(struct Scsi_Host * shost) + + + /** + * scsi_host_alloc - 创建SCSI主机适配器实例并执行基础初始化 + * @sht: 指向SCSI主机模板的指针 + * @privsize: 在hostdata数组中分配的额外字节数（该数组是返 + * 回的Scsi_Host实例的最后一个成员） + * + * 返回指向新的Scsi_Host实例的指针，失败返回NULL + * + * 是否阻塞：是 + * + * 注意事项：当此调用返回给LLD时，该主机适配器上的 + * SCSI总线扫描尚未进行。hostdata数组（默认长度为 + * 零）是LLD专属的每主机私有区域，供LLD独占使用。 + * 两个相关的引用计数都被设置为1。完整的注册（位于 + * sysfs）与总线扫描由scsi_add_host()和 + * scsi_scan_host()稍后执行。 + * 函数定义：drivers/scsi/hosts.c + **/ + struct Scsi_Host * scsi_host_alloc(const struct scsi_host_template * sht, + int privsize) + + + /** + * scsi_host_get - 增加SCSI主机适配器实例的引用计数 + * @shost: 指向Scsi_Host实例的指针 + * + * 无返回 + * + * 是否阻塞：目前可能会阻塞，但可能迭代为不阻塞 + * + * 注意事项：会同时增加struct Scsi_Host中两个子对 + * 象的引用计数 + * + * 函数定义：drivers/scsi/hosts.c + **/ + void scsi_host_get(struct Scsi_Host *shost) + + + /** + * scsi_host_put - 减少SCSI主机适配器实例的引用计数 + * （归零时释放） + * @shost: 指向Scsi_Host实例的指针 + * + * 无返回 + * + * 是否阻塞：当前可能会阻塞，但可能会改为不阻塞 + * + * 注意事项：实际会递减两个子对象中的计数。当后一个引用 + * 计数归零时系统会自动释放Scsi_Host实例。 + * LLD 无需关注Scsi_Host实例的具体释放时机，只要在平衡 + * 引用计数使用后不再访问该实例即可。 + * 函数定义：drivers/scsi/hosts.c + **/ + void scsi_host_put(struct Scsi_Host *shost) + + + /** + * scsi_remove_device - 卸载并移除SCSI设备 + * @sdev: 指向SCSI设备实例的指针 + * + * 返回值：成功返回0，若设备未连接，则返回-EINVAL + * + * 是否阻塞：是 + * + * 如果LLD发现某个SCSI设备（逻辑单元，lu）已经被移除， + * 但其主机适配器实例依旧存在，则可以请求移除该SCSI设备。 + * 如果该调用成功将触发sdev_destroy()回调函数的执行。调 + * 用完成后，sdev将变成一个无效的指针。 + * + * 函数定义：drivers/scsi/scsi_sysfs.c + **/ + int scsi_remove_device(struct scsi_device *sdev) + + + /** + * scsi_remove_host - 卸载并移除主机控制器下的所有SCSI设备 + * @shost: 指向SCSI主机适配器实例的指针 + * + * 返回值：成功返回0，失败返回1（例如：LLD正忙？？） + * + * 是否阻塞：是 + * + * 注意事项：仅在使用“热插拔初始化模型”时调用。应在调用 + * scsi_host_put()前调用。 + * + * 函数定义：drivers/scsi/hosts.c + **/ + int scsi_remove_host(struct Scsi_Host *shost) + + + /** + * scsi_report_bus_reset - 报告检测到的SCSI总线复位事件 + * @shost: 指向关联的SCSI主机适配器的指针 + * @channel: 发生SCSI总线复位的通道号 + * + * 返回值：无 + * + * 是否阻塞：否 + * + * 注意事项：仅当复位来自未知来源时才需调用此函数。 + * 由SCSI中间层发起的复位无需调用，但调用也不会导 + * 致副作用。此函数的主要作用是确保系统能正确处理 + * CHECK_CONDITION状态。 + * + * 函数定义：drivers/scsi/scsi_error.c + **/ + void scsi_report_bus_reset(struct Scsi_Host * shost, int channel) + + + /** + * scsi_scan_host - 执行SCSI总线扫描 + * @shost: 指向SCSI主机适配器实例的指针 + * + * 是否阻塞：是 + * + * 注意事项：应在调用scsi_add_host()后调用 + * + * 函数定义：drivers/scsi/scsi_scan.c + **/ + void scsi_scan_host(struct Scsi_Host *shost) + + + /** + * scsi_track_queue_full - 跟踪指定设备上连续的QUEUE_FULL + * 事件，以判断是否需要及何时调整 + * 该设备的队列深度。 + * @sdev: 指向SCSI设备实例的指针 + * @depth: 当前该设备上未完成的SCSI命令数量（不包括返回 + * QUEUE_FULL的命令） + * + * 返回值：0 - 当前队列深度无需调整 + * >0 - 需要将队列深度调整为此返回值指定的新深度 + * -1 - 需要回退到非标记操作模式，并使用 + * host->cmd_per_lun作为非标记命令队列的 + * 深度限制 + * + * 是否阻塞：否 + * + * 注意事项：LLD可以在任意时刻调用该函数。系统将自动执行“正确 + * 的处理流程”；该函数支持在中断上下文中安全地调用 + * + * 函数定义：drivers/scsi/scsi.c + **/ + int scsi_track_queue_full(struct scsi_device *sdev, int depth) + + + /** + * scsi_unblock_requests - 恢复向指定主机适配器提交命令 + * + * @shost: 指向要解除阻塞的主机适配器的指针 + * + * 返回值：无 + * + * 是否阻塞：否 + * + * 函数定义：drivers/scsi/scsi_lib.c + **/ + void scsi_unblock_requests(struct Scsi_Host * shost) + + + +接口函数 +======== +接口函数由底层驱动（LLD）定义实现，其函数指针保存在 +struct scsi_host_template实例中，并将该实例传递给 +scsi_host_alloc()。 +部分接口函数为必选实现项。所有 +接口函数都应声明为static，约定俗成的命名规则如下， +驱动“xyz”应将其sdev_configure()函数声明为:: + + static int xyz_sdev_configure(struct scsi_device * sdev); + +其余接口函数的命名规范均依此类推。 + +需将该函数指针赋值给“struct scsi_host_template”实例 +的‘sdev_configure’成员变量中，并将该结构体实例指针传 +递到中间层的scsi_host_alloc()函数。 + +各个接口函数的详细说明可参考include/scsi/scsi_host.h +文件，具体描述位于“struct scsi_host_template”结构体 +各个成员的上方。在某些情况下，scsi_host.h头文件中的描 +述比本文提供的更为详尽。 + +以下按字母顺序列出所有接口函数及其说明。 + +摘要： + + - bios_param - 获取磁盘的磁头/扇区/柱面参数 + - eh_timed_out - SCSI命令超时回调 + - eh_abort_handler - 中止指定的SCSI命令 + - eh_bus_reset_handler - 触发SCSI总线复位 + - eh_device_reset_handler - 执行SCSI设备复位 + - eh_host_reset_handler - 复位主机（主机总线适配器） + - info - 提供指定主机适配器的相关信息 + - ioctl - 驱动可响应ioctl控制命令 + - proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作 + - queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用‘done’回调 + - sdev_init - 在向新设备发送SCSI命令前的初始化 + - sdev_configure - 设备挂载后的精细化微调 + - sdev_destroy - 设备即将被移除前的清理 + + +详细信息:: + + /** + * bios_param - 获取磁盘的磁头/扇区/柱面参数 + * @sdev: 指向SCSI设备实例的指针（定义于 + * include/scsi/scsi_device.h中） + * @bdev: 指向块设备实例的指针（定义于fs.h中） + * @capacity: 设备容量（以512字节扇区为单位） + * @params: 三元数组用于保存输出结果： + * params[0]：磁头数量（最大255） + * params[1]：扇区数量（最大63） + * params[2]：柱面数量 + * + * 返回值：被忽略 + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 进程上下文（sd） + * + * 注意事项: 若未提供此函数，系统将基于READ CAPACITY + * 使用默认几何参数。params数组已预初始化伪值，防止函 + * 数无输出。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int bios_param(struct scsi_device * sdev, struct block_device *bdev, + sector_t capacity, int params[3]) + + + /** + * eh_timed_out - SCSI命令超时回调 + * @scp: 标识超时的命令 + * + * 返回值: + * + * EH_HANDLED: 我已修复该错误，请继续完成该命令 + * EH_RESET_TIMER: 我需要更多时间，请重置定时器并重新开始计时 + * EH_NOT_HANDLED 开始正常的错误恢复流程 + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 中断上下文 + * + * 注意事项: 该回调函数为LLD提供一个机会进行本地 + * 错误恢复处理。此处的恢复仅限于判断该未完成的命 + * 令是否还有可能完成。此回调中不允许中止或重新启 + * 动该命令。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int eh_timed_out(struct scsi_cmnd * scp) + + + /** + * eh_abort_handler - 中止指定的SCSI命令 + * @scp: 标识要中止的命令 + * + * 返回值：如果命令成功中止，则返回SUCCESS，否则返回FAILED + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 内核线程 + * + * 注意事项: 该函数仅在命令超时时才被调用。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int eh_abort_handler(struct scsi_cmnd * scp) + + + /** + * eh_bus_reset_handler - 发起SCSI总线复位 + * @scp: 包含该设备的SCSI总线应进行重置 + * + * 返回值：重置成功返回SUCCESS；否则返回FAILED + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 内核线程 + * + * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。 + * 在错误处理期间，当前主机适配器的所有IO请求均 + * 被阻塞。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int eh_bus_reset_handler(struct scsi_cmnd * scp) + + + /** + * eh_device_reset_handler - 发起SCSI设备复位 + * @scp: 指定将被重置的SCSI设备 + * + * 返回值：如果命令成功中止返回SUCCESS，否则返回FAILED + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 内核线程 + * + * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。 + * 在错误处理期间，当前主机适配器的所有IO请求均 + * 被阻塞。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int eh_device_reset_handler(struct scsi_cmnd * scp) + + + /** + * eh_host_reset_handler - 复位主机（主机总线适配器） + * @scp: 管理该设备的SCSI主机适配器应该被重置 + * + * 返回值：如果命令成功中止返回SUCCESS，否则返回FAILED + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 内核线程 + * + * 注意事项: 由SCSI错误处理线程（scsi_eh）调用。 + * 在错误处理期间，当前主机适配器的所有IO请求均 + * 被阻塞。当使用默认的eh_strategy策略时，如果 + * _abort_、_device_reset_、_bus_reset_和该处 + * 理函数均未定义（或全部返回FAILED），系统强制 + * 该故障设备处于离线状态 + * + * 可选实现说明：由LLD选择性定义 + **/ + int eh_host_reset_handler(struct scsi_cmnd * scp) + + + /** + * info - 提供给定主机适配器的详细信息：驱动程序名称 + * 以及用于区分不同主机适配器的数据结构 + * @shp: 指向目标主机的struct Scsi_Host实例 + * + * 返回值：返回以NULL结尾的ASCII字符串。[驱动 + * 负责管理返回的字符串所在内存并确保其在整个 + * 主机适配器生命周期内有效。] + * + * 并发安全声明: 无锁 + * + * 调用上下文说明: 进程上下文 + * + * 注意事项: 通常提供诸如I/O地址或中断号 + * 等PCI或ISA信息。如果未实现该函数，则 + * 默认使用struct Scsi_Host::name 字段。 + * 返回的字符串应为单行（即不包含换行符）。 + * 通过SCSI_IOCTL_PROBE_HOST ioctl可获 + * 取该函数返回的字符串，如果该函数不可用， + * 则ioctl返回struct Scsi_Host::name中 + * 的字符串。 + + * + * 可选实现说明：由LLD选择性定义 + **/ + const char * info(struct Scsi_Host * shp) + + + /** + * ioctl - 驱动可响应ioctl控制命令 + * @sdp: ioctl操作针对的SCSI设备 + * @cmd: ioctl命令号 + * @arg: 指向用户空间读写数据的指针。由于他指向用 + * 户空间，必须使用适当的内核函数 + * （如 copy_from_user()）。按照Unix的风 + * 格，该参数也可以视为unsigned long 类型。 + * + * 返回值：如果出错则返回负的“errno”值。返回0或正值表 + * 示成功，并将返回值传递给用户空间。 + * + * 并发安全声明：无锁 + * + * 调用上下文说明：进程上下文 + * + * 注意事项：SCSI子系统使用“逐层下传 + * （trickle down）”的ioctl模型。 + * 用户层会对上层驱动设备节点 + * （例如/dev/sdc）发起ioctl()调用， + * 如果上层驱动无法识别该命令，则将其 + * 传递给SCSI中间层，若中间层也无法识 + * 别，则再传递给控制该设备的LLD。 + * 根据最新的Unix标准，对于不支持的 + * ioctl()命令，应返回-ENOTTY。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int ioctl(struct scsi_device *sdp, int cmd, void *arg) + + + /** + * proc_info - 支持/proc/scsi/{驱动名}/{主机号}文件节点的读写操作 + * @buffer: 输入或出的缓冲区锚点（writeto1_read0==0表示向buffer写 + * 入，writeto1_read0==1表示由buffer读取） + * @start: 当writeto1_read0==0时，用于指定驱动实际填充的起始位置； + * 当writeto1_read0==1时被忽略。 + * @offset: 当writeto1_read0==0时，表示用户关注的数据在缓冲区中的 + * 偏移。当writeto1_read0==1时忽略。 + * @length: 缓冲区的最大（或实际使用）长度 + * @host_no: 目标SCSI Host的编号（struct Scsi_Host::host_no） + * @writeto1_read0: 1 -> 表示数据从用户空间写入驱动 + * （例如，“echo some_string > /proc/scsi/xyz/2”） + * 0 -> 表示用户从驱动读取数据 + * （例如，“cat /proc/scsi/xyz/2”） + * + * 返回值：当writeto1_read0==1时返回写入长度。否则， + * 返回从offset偏移开始输出到buffer的字符数。 + * + * 并发安全声明：无锁 + * + * 调用上下文说明：进程上下文 + * + * 注意事项：该函数由scsi_proc.c驱动，与proc_fs交互。 + * 当前SCSI子系统可移除对proc_fs的支持，相关配置选。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int proc_info(char * buffer, char ** start, off_t offset, + int length, int host_no, int writeto1_read0) + + + /** + * queuecommand - 将SCSI命令提交到主机控制器，命令执行完成后调用scp->scsi_done回调函数 + * @shost: 指向目标SCSI主机控制器 + * @scp: 指向待处理的SCSI命令 + * + * 返回值：成功返回0。 + * + * 如果发生错误，则返回： + * + * SCSI_MLQUEUE_DEVICE_BUSY表示设备队列满， + * SCSI_MLQUEUE_HOST_BUSY表示整个主机队列满 + * + * 在这两种情况下，中间层将自动重新提交该I/O请求 + * + * - 若返回SCSI_MLQUEUE_DEVICE_BUSY，则仅暂停该 + * 特定设备的命令处理，当该设备的某个命令完成返回 + * 时（或在短暂延迟后如果没有其他未完成命令）将恢 + * 复其处理。其他设备的命令仍正常继续处理。 + * + * - 若返回SCSI_MLQUEUE_HOST_BUSY，将暂停该主机 + * 的所有I/O操作，当任意命令从该主机返回时（或在 + * 短暂延迟后如果没有其他未完成命令）将恢复处理。 + * + * 为了与早期的queuecommand兼容，任何其他返回值 + * 都被视作SCSI_MLQUEUE_HOST_BUSY。 + * + * 对于其他可立即检测到的错误，可通过以下流程处 + * 理：设置scp->result为适当错误值，调用scp->scsi_done + * 回调函数，然后该函数返回0。若该命令未立即执行（LLD + * 正在启动或将要启动该命令），则应将scp->result置0并 + * 返回0。 + * + * 命令所有权说明：若驱动返回0，则表示驱动获得该命令的 + * 所有权， + * 并必须确保最终执行scp->scsi_done回调函数。注意：驱动 + * 可以在返回0之前调用scp->scsi_done，但一旦调用该回 + * 调函数后，就只能返回0。若驱动返回非零值，则禁止在任何时 + * 刻执行该命令的scsi_done回调函数。 + * + * 并发安全声明：在2.6.36及更早的内核版本中，调用该函数时持有 + * struct Scsi_Host::host_lock锁（通过“irqsave”获取中断安全的自旋锁）， + * 并且返回时仍需保持该锁；从Linux 2.6.37开始，queuecommand + * 将在无锁状态下被调用。 + * + * 调用上下文说明：在中断（软中断）或进程上下文中 + * + * 注意事项：该函数执行应当非常快速，通常不会等待I/O + * 完成。因此scp->scsi_done回调函数通常会在该函数返 + * 回后的某个时刻被调用（经常直接从中断服务例程中调用）。 + * 某些情况下（如模拟SCSI INQUIRY响应的伪适配器驱动）， + * scp->scsi_done回调可能在该函数返回前就被调用。 + * 若scp->scsi_done回调函数未在指定时限内被调用，SCSI中 + * 间层将启动错误处理流程。当调用scp->scsi_done回调函数 + * 时，若“result”字段被设置为CHECK CONDITION， + * 则LLD应执行自动感知并填充 + * struct scsi_cmnd::sense_buffer数组。在中间层将 + * 命令加入LLD队列之前前，scsi_cmnd::sense_buffer数组 + * 会被清零。 + * + * 可选实现说明：LLD必须实现 + **/ + int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp) + + + /** + * sdev_init - 在向新设备发送任何SCSI命令前（即开始扫描 + * 之前）调用该函数 + * @sdp: 指向即将被扫描的新设备的指针 + * + * 返回值：返回0表示正常。返回其他值表示出错， + * 该设备将被忽略。 + * + * 并发安全声明：无锁 + * + * 调用上下文说明：进程上下文 + * + * 注意事项：该函数允许LLD在设备首次扫描前分配所需的资源。 + * 对应的SCSI设备可能尚未真正存在，但SCSI中间层即将对其进 + * 行扫描（例如发送INQUIRY命令等）。如果设备存在，将调用 + * sdev_configure()进行配置；如果设备不存在，则调用 + * sdev_destroy()销毁。更多细节请参考 + * include/scsi/scsi_host.h文件。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int sdev_init(struct scsi_device *sdp) + + + /** + * sdev_configure - 在设备首次完成扫描（即已成功响应INQUIRY + * 命令）之后，LDD可调用该函数对设备进行进一步配置 + * @sdp: 已连接的设备 + * + * 返回值：返回0表示成功。任何其他返回值都被视为错误，此时 + * 设备将被标记为离线。[被标记离线的设备不会调用sdev_destroy()， + * 因此需要LLD主动清理资源。] + * + * 并发安全声明：无锁 + * + * 调用上下文说明：进程上下文 + * + * 注意事项：该接口允许LLD查看设备扫描代码所发出的初始INQUIRY + * 命令的响应，并采取对应操作。具体实现细节请参阅 + * include/scsi/scsi_host.h文件。 + * + * 可选实现说明：由LLD选择性定义 + **/ + int sdev_configure(struct scsi_device *sdp) + + + /** + * sdev_destroy - 当指定设备即将被关闭时调用。此时该设备 + * 上的所有I/O活动均已停止。 + * @sdp: 即将关闭的设备 + * + * 返回值：无 + * + * 并发安全声明：无锁 + * + * 调用上下文说明：进程上下文 + * + * 注意事项：该设备的中间层数据结构仍然存在 + * 但即将被销毁。驱动程序此时应当释放为该设 + * 备分配的所有专属资源。系统将不再向此sdp + * 实例发送任何命令。[但该设备可能在未来被 + * 重新连接，届时将通过新的struct scsi_device + * 实例，并触发后续的sdev_init()和 + * sdev_configure()调用过程。] + * + * 可选实现说明：由LLD选择性定义 + **/ + void sdev_destroy(struct scsi_device *sdp) + + + +数据结构 +======== +struct scsi_host_template +------------------------- +每个LLD对应一个“struct scsi_host_template” +实例 [#]_。该结构体通常被初始化为驱动头文件中的静 +态全局变量，此方式可确保未显式初始化的成员自动置零 +（0或NULL）。关键成员变量说明如下： + + name + - 驱动程序的名称（可以包含空格，请限制在80个字符以内） + + proc_name + - 在“/proc/scsi//” + 和sysfs的“drivers”目录中使用的名称。因此 + “proc_name”应仅包含Unix文件名中可接受 + 的字符。 + + ``(*queuecommand)()`` + - 中间层使用的主要回调函数，用于将SCSI命令 + 提交到LLD。 + + vendor_id + - 该字段是一个唯一标识值，用于确认提供 + Scsi_Host LLD的供应商，最常用于 + 验证供应商特定的消息请求。该值由标识符类型 + 和供应商特定值组成，有效格式描述请参阅 + scsi_netlink.h头文件。 + +该结构体的完整定义及详细注释请参阅 ``include/scsi/scsi_host.h``。 + +.. [#] 在极端情况下，单个驱动需要控制多种不同类型的硬件时，驱动可 + 能包含多个实例，（例如某个LLD驱动同时处理ISA和PCI两种类型 + 的适配卡，并为每种硬件类型维护独立的 + struct scsi_host_template实例）。 + +struct Scsi_Host +---------------- +每个由LLD控制的主机适配器对应一个struct Scsi_Host实例。 +该结构体与struct scsi_host_template具有多个相同成员。 +当创建struct Scsi_Host实例时（通过hosts.c中的 +scsi_host_alloc()函数），这些通用成员会从LLD的 +struct scsi_host_template实例初始化而来。关键成员说明 +如下： + + host_no + - 系统范围内唯一的主机标识号，按升序从0开始分配 + can_queue + - 必须大于0，表示适配器可处理的最大并发命令数，禁 + 止向适配器发送超过此数值的命令数 + this_id + - 主机适配器的SCSI ID（SCSI启动器标识），若未知则 + 设置为-1 + sg_tablesize + - 主机适配器支持的最大散列表（scatter-gather）元素 + 数。设置为SG_ALL或更小的值可避免使用链式SG列表， + 且最小值必须为1 + max_sectors + - 单个SCSI命令中允许的最大扇区数（通常为512字节/ + 扇区）。默认值为0，此时会使用 + SCSI_DEFAULT_MAX_SECTORS（在scsi_host.h中定义）， + 当前该值为1024。因此，如果未定义max_sectors，则磁盘的 + 最大传输大小为512KB。注意：这个大小可能不足以支持 + 磁盘固件上传。 + cmd_per_lun + - 主机适配器的设备上，每个LUN可排队的最大命令数。 + 此值可通过LLD调用scsi_change_queue_depth()进行 + 调整。 + hostt + - 指向LLD struct scsi_host_template实例的指针， + 当前struct Scsi_Host实例正是由此模板生成。 + hostt->proc_name + - LLD的名称，sysfs使用的驱动名。 + transportt + - 指向LLD struct scsi_transport_template实例的指 + 针（如果存在）。当前支持FC与SPI传输协议。 + hostdata[0] + - 为LLD在struct Scsi_Host结构体末尾预留的区域，大小由 + scsi_host_alloc()的第二个参数(privsize)决定。 + +scsi_host结构体的完整定义详见include/scsi/scsi_host.h。 + +struct scsi_device +------------------ +通常而言，每个SCSI逻辑单元（Logical Unit）对应一个该结构 +的实例。连接到主机适配器的SCSI设备通过三个要素唯一标识：通 +道号（Channel Number）、目标ID（Target ID）和逻辑单元号 +（LUN）。 +该结构体完整定义于include/scsi/scsi_device.h。 + +struct scsi_cmnd +---------------- +该结构体实例用于在LLD与SCSI中间层之间传递SCSI命令 +及其响应。SCSI中间层会确保：提交到LLD的命令数不超过 +scsi_change_queue_depth()（或struct Scsi_Host::cmd_per_lun） +设定的上限，且每个SCSI设备至少分配一个struct scsi_cmnd实例。 +关键成员说明如下： + + cmnd + - 包含SCSI命令的数组 + cmd_len + - SCSI命令的长度（字节为单位） + sc_data_direction + - 数据的传输方向。请参考 + include/linux/dma-mapping.h中的 + “enum dma_data_direction”。 + result + - LLD在调用“done”之前设置该值。值为0表示命令成功 + 完成（并且所有数据（如果有）已成功在主机与SCSI + 目标设备之间完成传输）。“result”是一个32位无符 + 号整数，可以视为2个相关字节。SCSI状态值位于最 + 低有效位。请参考include/scsi/scsi.h中的 + status_byte()与host_byte()宏以及其相关常量。 + sense_buffer + - 这是一个数组（最大长度为SCSI_SENSE_BUFFERSIZE + 字节），当SCSI状态（“result”的最低有效位）设为 + CHECK_CONDITION（2）时，该数组由LLD填写。若 + CHECK_CONDITION被置位，且sense_buffer[0]的高 + 半字节值为7，则中间层会认为sense_buffer数组 + 包含有效的SCSI感知数据；否则，中间层会发送 + REQUEST_SENSE SCSI命令来获取感知数据。由于命令 + 排队的存在，后一种方式容易出错，因此建议LLD始终 + 支持“自动感知”。 + device + - 指向与该命令关联的scsi_device对象的指针。 + resid_len (通过调用scsi_set_resid() / scsi_get_resid()访问) + - LLD应将此无符号整数设置为请求的传输长度（即 + “request_bufflen”）减去实际传输的字节数。“resid_len” + 默认设置为0，因此如果LLD无法检测到数据欠载（不能报告溢出）， + 则可以忽略它。LLD应在调用“done”之前设置 + “resid_len”。 + underflow + - 如果实际传输的字节数小于该字段值，LLD应将 + DID_ERROR << 16赋值给“result”。并非所有 + LLD都实现此项检查，部分LLD仅将错误信息输出 + 到日志，而未真正报告DID_ERROR。更推荐 + 的做法是由LLD实现“resid_len”的支持。 + +建议LLD在从SCSI目标设备进行数据传输时设置“resid_len”字段 +（例如READ操作）。当这些数据传输的感知码是MEDIUM ERROR或 +HARDWARE ERROR（有时也包括RECOVERED ERROR）时设置 +resid_len尤为重要。在这种情况下，如果LLD无法确定接收了多 +少数据，那么最安全的做法是表示没有接收到任何数据。例如： +为了表明没有接收到任何有效数据，LLD可以使用如下辅助函数:: + + scsi_set_resid(SCpnt, scsi_bufflen(SCpnt)); + +其中SCpnt是一个指向scsi_cmnd对象的指针。如果表示仅接收到 +三个512字节的数据块，可以这样设置resid_len:: + + scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512)); + +scsi_cmnd结构体定义在 include/scsi/scsi_cmnd.h文件中。 + + +锁 +=== +每个struct Scsi_Host实例都有一个名为default_lock +的自旋锁（spin_lock），它在scsi_host_alloc()函数 +中初始化（该函数定义在hosts.c文件中）。在同一个函数 +中，struct Scsi_Host::host_lock指针会被初始化为指 +向default_lock。此后，SCSI中间层执行的加 +锁和解锁操作都会使用host_lock指针。过去，驱动程序可 +以重写host_lock指针，但现在不再允许这样做。 + + +自动感知 +======== +自动感知（Autosense或auto-sense）在SAM-2规范中被定 +义为：当SCSI命令完成状态为CHECK CONDITION时，“自动 +将感知数据（sense data）返回给应用程序客户端”。底层 +驱动（LLD）应当执行自动感知。当LLD检测到 +CHECK CONDITION状态时，可通过以下任一方式完成： + + a) 要求SCSI协议（例如SCSI并行接口（SPI））在此 + 类响应中执行一次额外的数据传输 + + b) 或由LLD主动发起REQUEST SENSE命令获取感知数据 + +无论采用哪种方式，当检测到CHECK CONDITION状态时，中 +间层通过检查结构体scsi_cmnd::sense_buffer[0]的值来 +判断LLD是否已执行自动感知。若该字节的高半字节为7 +（或 0xf），则认为已执行自动感知；若该字节为其他值 +（且此字节在每条命令执行前会被初始化为0），则中间层将 +主动发起REQUEST SENSE命令。 + +在存在命令队列的场景下，保存失败命令感知数据的“nexus” +可能会在等待REQUEST SENSE命令期间变得不同步。因此， +最佳实践是由LLD执行自动感知。 + + +自Linux内核2.4以来的变更 +======================== +io_request_lock已被多个细粒度锁替代。与底层驱动 +（LLD）相关的锁是struct Scsi_Host::host_lock，且每 +个SCSI主机都独立拥有一个该锁。 + +旧的错误处理机制已经被移除。这意味着LLD的接口函数 +abort()与reset()已经被删除。 +struct scsi_host_template::use_new_eh_code标志 +也已经被移除。 + +在Linux内核2.4中，SCSI子系统的配置描述与其他Linux子系 +统的配置描述集中存放在Documentation/Configure.help +文件中。在Linux内核2.6中，SCSI子系统拥有独立的配置文 +件drivers/scsi/Kconfig（体积更小），同时包含配置信息 +与帮助信息。 + +struct SHT已重命名为struct scsi_host_template。 + +新增“热插拔初始化模型”以及许多用于支持该功能的额外函数。 + + +致谢 +==== +以下人员对本文档做出了贡献： + + - Mike Anderson + - James Bottomley + - Patrick Mansfield + - Christoph Hellwig + - Doug Ledford + - Andries Brouwer + - Randy Dunlap + - Alan Stern + + +Douglas Gilbert +dgilbert at interlog dot com + +2004年9月21日 diff --git a/Documentation/translations/zh_CN/scsi/sd-parameters.rst b/Documentation/translations/zh_CN/scsi/sd-parameters.rst new file mode 100644 index 000000000000..b3d0445dc9f3 --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/sd-parameters.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/sd-parameters.rst + +:翻译: + + 郝栋栋 doubled + +:校译: + + + +============================ +Linux SCSI磁盘驱动（sd）参数 +============================ + +缓存类型（读/写） +------------------ +启用/禁用驱动器读写缓存。 + +=========================== ===== ===== ======= ======= + 缓存类型字符串 WCE RCD 写缓存 读缓存 +=========================== ===== ===== ======= ======= + write through 0 0 关闭 开启 + none 0 1 关闭 关闭 + write back 1 0 开启 开启 + write back, no read (daft) 1 1 开启 关闭 +=========================== ===== ===== ======= ======= + +将缓存类型设置为“write back”并将该设置保存到驱动器:: + + # echo "write back" > cache_type + +如果要修改缓存模式但不使更改持久化，可在缓存类型字符串前 +添加“temporary ”。例如:: + + # echo "temporary write back" > cache_type diff --git a/Documentation/translations/zh_CN/scsi/wd719x.rst b/Documentation/translations/zh_CN/scsi/wd719x.rst new file mode 100644 index 000000000000..79757c42032b --- /dev/null +++ b/Documentation/translations/zh_CN/scsi/wd719x.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scsi/libsas.rst + +:翻译: + + 张钰杰 Yujie Zhang + +:校译: + +==================================================== +Western Digital WD7193, WD7197 和 WD7296 SCSI 卡驱动 +==================================================== + +这些卡需要加载固件。固件可从 WD 提供下载的 Windows NT 驱动程 +序中提取。地址如下： + +http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en + +该文件或网页上都未包含任何许可声明，因此该固件可能无法被收录到 +linux-firmware 项目中。 + +提供的脚本可用于下载并提取固件，生成 wd719x-risc.bin 和 +wd719x-wcs.bin 文件。请将它们放置在 /lib/firmware/ 目录下。 +脚本内容如下： + + #!/bin/sh + wget http://support.wdc.com/download/archive/pciscsi.exe + lha xi pciscsi.exe pci-scsi.exe + lha xi pci-scsi.exe nt/wd7296a.sys + rm pci-scsi.exe + dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336 + dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514 + rm wd7296a.sys diff --git a/Documentation/translations/zh_CN/security/SCTP.rst b/Documentation/translations/zh_CN/security/SCTP.rst new file mode 100644 index 000000000000..f2774b0d66b5 --- /dev/null +++ b/Documentation/translations/zh_CN/security/SCTP.rst @@ -0,0 +1,317 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/SCTP.rst + +:翻译: + 赵硕 Shuo Zhao + +==== +SCTP +==== + +SCTP的LSM支持 +============= + +安全钩子 +-------- + +对于安全模块支持，已经实现了三个特定于SCTP的钩子:: + + security_sctp_assoc_request() + security_sctp_bind_connect() + security_sctp_sk_clone() + security_sctp_assoc_established() + +这些钩子的用法在下面的 `SCTP的SELinux支持`_ 一章中描述SELinux的实现。 + + +security_sctp_assoc_request() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +将关联INIT数据包的 ``@asoc`` 和 ``@chunk->skb`` 传递给安全模块。 +成功时返回 0，失败时返回错误。 +:: + + @asoc - 指向sctp关联结构的指针。 + @skb - 指向包含关联数据包skbuff的指针。 + + +security_sctp_bind_connect() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +将一个或多个IPv4/IPv6地址传递给安全模块进行基于 ``@optname`` 的验证， +这将导致是绑定还是连接服务，如下面的权限检查表所示。成功时返回 0，失败 +时返回错误。 +:: + + @sk - 指向sock结构的指针。 + @optname - 需要验证的选项名称。 + @address - 一个或多个IPv4 / IPv6地址。 + @addrlen - 地址的总长度。使用sizeof(struct sockaddr_in)或 + sizeof(struct sockaddr_in6)来计算每个ipv4或ipv6地址。 + + ------------------------------------------------------------------ + | BIND 类型检查 | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_BINDX_ADD | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_PRIMARY_ADDR | 单个 ipv4 or ipv6 地址 | + | SCTP_SET_PEER_PRIMARY_ADDR | 单个 ipv4 or ipv6 地址 | + ------------------------------------------------------------------ + + ------------------------------------------------------------------ + | CONNECT 类型检查 | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_CONNECTX | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_PARAM_ADD_IP | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_SENDMSG_CONNECT | 单个 ipv4 or ipv6 地址 | + | SCTP_PARAM_SET_PRIMARY | 单个 ipv4 or ipv6 地址 | + ------------------------------------------------------------------ + +条目 ``@optname`` 的摘要如下:: + + SCTP_SOCKOPT_BINDX_ADD - 允许在（可选地）调用 bind(3) 后，关联额外 + 的绑定地址。 + sctp_bindx(3) 用于在套接字上添加一组绑定地址。 + + SCTP_SOCKOPT_CONNECTX - 允许分配多个地址以连接到对端（多宿主）。 + sctp_connectx(3) 使用多个目标地址在SCTP + 套接字上发起连接。 + + SCTP_SENDMSG_CONNECT - 通过sendmsg(2)或sctp_sendmsg(3)在新关联上 + 发起连接。 + + SCTP_PRIMARY_ADDR - 设置本地主地址。 + + SCTP_SET_PEER_PRIMARY_ADDR - 请求远程对端将某个地址设置为其主地址。 + + SCTP_PARAM_ADD_IP - 在启用动态地址重配置时使用。 + SCTP_PARAM_SET_PRIMARY - 如下所述，启用重新配置功能。 + + +为了支持动态地址重新配置，必须在两个端点上启用以下 +参数（或使用适当的 **setsockopt**\(2)）:: + + /proc/sys/net/sctp/addip_enable + /proc/sys/net/sctp/addip_noauth_enable + +当相应的 ``@optname`` 存在时，以下的 *_PARAM_* 参数会 +通过ASCONF块发送到对端:: + + @optname ASCONF Parameter + ---------- ------------------ + SCTP_SOCKOPT_BINDX_ADD -> SCTP_PARAM_ADD_IP + SCTP_SET_PEER_PRIMARY_ADDR -> SCTP_PARAM_SET_PRIMARY + + +security_sctp_sk_clone() +~~~~~~~~~~~~~~~~~~~~~~~~ +每当通过 **accept**\(2)创建一个新的套接字（即TCP类型的套接字），或者当 +一个套接字被‘剥离’时如用户空间调用 **sctp_peeloff**\(3)，会调用此函数。 +:: + + @asoc - 指向当前sctp关联结构的指针。 + @sk - 指向当前套接字结构的指针。 + @newsk - 指向新的套接字结构的指针。 + + +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +当收到COOKIE ACK时调用，对于客户端，对端的secid将被保存 +到 ``@asoc->peer_secid`` 中:: + + @asoc - 指向sctp关联结构的指针。 + @skb - 指向COOKIE ACK数据包的skbuff指针。 + + +用于关联建立的安全钩子 +---------------------- + +下图展示了在建立关联时 ``security_sctp_bind_connect()``、 ``security_sctp_assoc_request()`` +和 ``security_sctp_assoc_established()`` 的使用。 +:: + + SCTP 端点 "A" SCTP 端点 "Z" + ============= ============= + sctp_sf_do_prm_asoc() + 关联的设置可以通过connect(2), + sctp_connectx(3),sendmsg(2) + or sctp_sendmsg(3)来发起。 + 这将导致调用security_sctp_bind_connect() + 发起与SCTP对端端点"Z"的关联。 + INIT ---------------------------------------------> + sctp_sf_do_5_1B_init() + 响应一个INIT数据块。 + SCTP对端端点"A"正在请求一个临时关联。 + 如果是首次关联，调用security_sctp_assoc_request() + 来设置对等方标签。 + 如果不是首次关联，检查是否被允许。 + 如果允许，则发送: + <----------------------------------------------- INIT ACK + | + | 否则，生成审计事件并默默丢弃该数据包。 + | + COOKIE ECHO ------------------------------------------> + sctp_sf_do_5_1D_ce() + 响应一个COOKIE ECHO数据块。 + 确认该cookie并创建一个永久关联。 + 调用security_sctp_assoc_request() + 执行与INIT数据块响应相同的操作。 + <------------------------------------------- COOKIE ACK + | | + sctp_sf_do_5_1E_ca | + 调用security_sctp_assoc_established() | + 来设置对方标签 | + | | + | 如果是SCTP_SOCKET_TCP或是剥离的套接 + | 字，会调用 security_sctp_sk_clone() + | 来克隆新的套接字。 + | | + 建立 建立 + | | + ------------------------------------------------------------------ + | 关联建立 | + ------------------------------------------------------------------ + + +SCTP的SELinux支持 +================= + +安全钩子 +-------- + +上面的 `SCTP的LSM支持`_ 章节描述了以下SCTP安全钩子，SELinux的细节 +说明如下:: + + security_sctp_assoc_request() + security_sctp_bind_connect() + security_sctp_sk_clone() + security_sctp_assoc_established() + + +security_sctp_assoc_request() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +将关联INIT数据包的 ``@asoc`` 和 ``@chunk->skb`` 传递给安全模块。 +成功时返回 0，失败时返回错误。 +:: + + @asoc - 指向sctp关联结构的指针。 + @skb - 指向关联数据包skbuff的指针。 + +安全模块执行以下操作: + 如果这是 ``@asoc->base.sk`` 上的首次关联，则将对端的sid设置 + 为 ``@skb`` 中的值。这将确保只有一个对端sid分配给可能支持多个 + 关联的 ``@asoc->base.sk``。 + + 否则验证 ``@asoc->base.sk peer sid`` 是否与 ``@skb peer sid`` + 匹配，以确定该关联是否应被允许或拒绝。 + + 将sctp的 ``@asoc sid`` 设置为套接字的sid（来自 ``asoc->base.sk``） + 并从 ``@skb peer sid`` 中提取MLS部分。这将在SCTP的TCP类型套接字及 + 剥离连接中使用，因为它们会导致生成一个新的套接字。 + + 如果配置了IP安全选项（CIPSO/CALIPSO），则会在套接字上设置IP选项。 + + +security_sctp_bind_connect() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +根据 ``@optname`` 检查ipv4/ipv6地址所需的权限，具体如下:: + + ------------------------------------------------------------------ + | BIND 权限检查 | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_BINDX_ADD | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_PRIMARY_ADDR | 单个 ipv4 or ipv6 地址 | + | SCTP_SET_PEER_PRIMARY_ADDR | 单个 ipv4 or ipv6 地址 | + ------------------------------------------------------------------ + + ------------------------------------------------------------------ + | CONNECT 权限检查 | + | @optname | @address contains | + |----------------------------|-----------------------------------| + | SCTP_SOCKOPT_CONNECTX | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_PARAM_ADD_IP | 一个或多个 ipv4 / ipv6 地址 | + | SCTP_SENDMSG_CONNECT | 单个 ipv4 or ipv6 地址 | + | SCTP_PARAM_SET_PRIMARY | 单个 ipv4 or ipv6 地址 | + ------------------------------------------------------------------ + + +`SCTP的LSM支持`_ 提供了 ``@optname`` 摘要，并且还描述了当启用动态地址重新 +配置时，ASCONF块的处理过程。 + + +security_sctp_sk_clone() +~~~~~~~~~~~~~~~~~~~~~~~~ +每当通过 **accept**\(2)（即TCP类型的套接字）创建一个新的套接字，或者 +当一个套接字被“剥离”如用户空间调用 **sctp_peeloff**\(3)时， +``security_sctp_sk_clone()`` 将会分别将新套接字的sid和对端sid设置为 +``@asoc sid`` 和 ``@asoc peer sid`` 中包含的值。 +:: + + @asoc - 指向当前sctp关联结构的指针。 + @sk - 指向当前sock结构的指针。 + @newsk - 指向新sock结构的指针。 + + +security_sctp_assoc_established() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +当接收到COOKIE ACK时调用，它将连接的对端sid设置为 ``@skb`` 中的值:: + + @asoc - 指向sctp关联结构的指针。 + @skb - 指向COOKIE ACK包skbuff的指针。 + + +策略声明 +-------- +以下支持SCTP的类和权限在内核中是可用的:: + + class sctp_socket inherits socket { node_bind } + +当启用以下策略功能时:: + + policycap extended_socket_class; + +SELinux对SCTP的支持添加了用于连接特定端口类型 ``name_connect`` 权限 +以及在下面的章节中进行解释的 ``association`` 权限。 + +如果用户空间工具已更新，SCTP将支持如下所示的 ``portcon`` 声明:: + + portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0 + + +SCTP对端标签 +------------ +每个SCTP套接字仅分配一个对端标签。这个标签将在建立第一个关联时分配。 +任何后续在该套接字上的关联都会将它们的数据包对端标签与套接字的对端标 +签进行比较，只有在它们不同的情况下 ``association`` 权限才会被验证。 +这是通过检查套接字的对端sid与接收到的数据包中的对端sid来验证的，以决 +定是否允许或拒绝该关联。 + +注: + 1) 如果对端标签未启用，则对端上下文将始终是 ``SECINITSID_UNLABELED`` + （在策略声明中为 ``unlabeled_t`` ）。 + + 2) 由于SCTP可以在单个套接字上支持每个端点（多宿主）的多个传输地址，因此 + 可以配置策略和NetLabel为每个端点提供不同的对端标签。由于套接字的对端 + 标签是由第一个关联的传输地址决定的，因此建议所有的对端标签保持一致。 + + 3) 用户空间可以使用 **getpeercon**\(3) 来检索套接字的对端上下文。 + + 4) 虽然这不是SCTP特有的，但在使用NetLabel时要注意，如果标签分配给特定的接 + 口，而该接口‘goes down’，则NetLabel服务会移除该条目。因此，请确保网络启 + 动脚本调用 **netlabelctl**\(8) 来设置所需的标签（详细信息， + 请参阅 **netlabel-config**\(8) 辅助脚本）。 + + 5) NetLabel SCTP对端标签规则应用如下所述标签为“netlabel”的一组帖子： + https://www.paul-moore.com/blog/t. + + 6) CIPSO仅支持IPv4地址： ``socket(AF_INET, ...)`` + CALIPSO仅支持IPv6地址： ``socket(AF_INET6, ...)`` + + 测试CIPSO/CALIPSO时请注意以下事项： + a) 如果SCTP数据包由于无效标签无法送达，CIPSO会发送一个ICMP包。 + b) CALIPSO不会发送ICMP包，只会默默丢弃数据包。 + + 7) RFC 3554不支持IPSEC —— SCTP/IPSEC支持尚未在用户空间实现(**racoon**\(8) + 或 **ipsec_pluto**\(8))，尽管内核支持 SCTP/IPSEC。 diff --git a/Documentation/translations/zh_CN/security/index.rst b/Documentation/translations/zh_CN/security/index.rst index 78d9d4b36dca..d33b107405c7 100644 --- a/Documentation/translations/zh_CN/security/index.rst +++ b/Documentation/translations/zh_CN/security/index.rst @@ -18,7 +18,9 @@ credentials snp-tdx-threat-model lsm + lsm-development sak + SCTP self-protection siphash tpm/index @@ -28,7 +30,5 @@ TODOLIST: * IMA-templates * keys/index -* lsm-development -* SCTP * secrets/index * ipe diff --git a/Documentation/translations/zh_CN/security/ipe.rst b/Documentation/translations/zh_CN/security/ipe.rst new file mode 100644 index 000000000000..55968f0c7ae3 --- /dev/null +++ b/Documentation/translations/zh_CN/security/ipe.rst @@ -0,0 +1,398 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/sak.rst + +:翻译: + 赵硕 Shuo Zhao + +完整性策略执行（IPE）-内核文档 +============================== + +.. NOTE:: + + 这是针对开发人员而不是管理员的文档。如果您正在 + 寻找有关IPE使用的文档，请参阅 :doc:`IPE admin + guide `。 + +历史背景 +-------- + +最初促使IPE实施的原因，是需要创建一个锁定式系统。该系统将 +从一开始就具备安全性，并且在可执行代码和系统功能关键的特定 +数据文件上，提供强有力的完整性保障。只有当这些特定数据文件 +符合完整性策略时，它们才可以被读取。系统中还将存在强制访问 +控制机制，因此扩展属性（xattrs）也必须受到保护。这就引出了 +需要选择能够提供完整性保证的机制。当时，有两种主要机制被考 +虑，用以在满足这些要求的前提下保证系统完整性： + + 1. IMA + EVM Signatures + 2. DM-Verity + +这两个选项都经过了仔细考虑，然而在原始的IPE使用场景 +中，最终选择DM-Verity而非IMA+EVM作为完整性机制，主 +要有三个原因： + + 1. 防护额外的攻击途径 + + * 使用IMA+EVM时，如果没有加密解决方案，系统很容易受到 + 离线攻击，特别是针对上述特定数据文件的攻击。 + + 与可执行文件不同，读取操作（如对受保护数据文件的读 + 取操作）无法强制性进行全局完整性验证。这意味着必须 + 有一种选择机制来决定是否应对某个读取操作实施完整性 + 策略。 + + 在当时，这是通过强制访问控制标签来实现的，IMA策略会 + 指定哪些标签需要进行完整性验证，这带来了一个问题： + EVM虽然可以保护标签，但如果攻击者离线修改文件系统， + 那么攻击者就可以清除所有的扩展属性（xattrs）——包括 + 用于确定文件是否应受完整性策略约束的SELinux标签。 + + 使用DM-Verity，由于xattrs被保存为Merkel树的一部分， + 如果对由dm-verity保护的文件系统进行了离线挂载，校验 + 和将不在匹配，文件将无法读取。 + + * 由于用户空间的二进制文件在Linux中是分页加载的，dm- + verity同样提供了对抗恶意块设备的额外保护。在这样的 + 攻击中，块设备最初报告适当的内容以供IMA哈希计算，通 + 过所需的完整性检查。然后，在访问真实数据时发生的页面 + 错误将报告攻击者的有效载荷。由于dm-verity会在页面错 + 误发生时检查数据（以及磁盘访问），因此这种攻击得到了 + 缓解。 + + 2. 性能: + + * dm-verity在块被读取时按需提供完整性验证，而不需要将整 + 个文件读入内存进行验证。 + + 3. 签名的简化性: + + * 不需要两个签名（IMA 然后是 EVM）：一个签名可以覆盖整个 + 块设备。 + * 签名可以存储在文件系统元数据之外。 + * 该签名支持基于 x.509 的签名基础设施。 + +下一步是选择一个策略来执行完整性验证机制，该策略的最低 +要求是： + + 1. 策略本身必须经过完整性验证（防止针对它的简单攻击）。 + 2. 策略本身必须抵抗回滚攻击。 + 3. 策略执行必须具有类似宽松模式的功能。 + 4. 策略必须能够在不重启的情况下，完整地进行更新。 + 5. 策略更新必须是原子性的。 + 6. 策略必须支持撤销先前创建的组件。 + 7. 策略必须在任何时间点都能进行审计。 + +当时，IMA作为唯一的完整性策略机制，被用来与这些要求进行对比， +但未能满足所有最低要求。尽管考虑过扩展IMA以涵盖这些要求，但 +最终因两个原因被放弃： + + 1. 回归风险；这其中许多变更将导致对已经存在于内核的IMA进行 + 重大代码更改，因此可能会影响用户。 + + 2. IMA在该系统中用于测量和证明；将测量策略与本地完整性策略 + 的执行分离被认为是有利的。 + +由于这些原因，决定创建一个新的LSM，其职责是仅限于本地完整性 +策略的执行。 + +职责和范围 +---------- + +IPE顾名思义，本质上是一种完整性策略执行解决方案；IPE并不强制规定 +如何提供完整性保障，而是将这一决策权留给系统管理员，管理员根据自身 +需求，选择符合的机制来设定安全标准。存在几种不同的完整性解决方案， +它们提供了不同程度的安全保障；而IPE允许系统管理员理论上为所有这些 +解决方案制定策略。 + +IPE自身没有内置确保完整性的固有机制。相反，在构建具备完整性保障能力 +的系统时，存在更高效的分层方案可供使用。需要重点注意的是，用于证明完 +整性的机制，与用于执行完整性声明的策略是相互独立的。 + +因此，IPE依据以下方面进行设计： + + 1. 便于与完整性提供机制集成。 + 2. 便于平台管理员/系统管理员使用。 + +设计理由: +--------- + +IPE是在评估其他操作系统和环境中的现有完整性策略解决方案后设计的。 +在对其他实现的调查中，发现了一些缺陷： + + 1. 策略不易为人们读取，通常需要二进制中间格式。 + 2. 默认情况下会隐式采取单一的、不可定制的操作。 + 3. 调试策略需要手动来确定违反了哪个规则。 + 4. 编写策略需要对更大系统或操作系统有深入的了解。 + +IPE尝试避免所有这些缺陷。 + +策略 +~~~~ + +纯文本 +^^^^^^ + +IPE的策略是纯文本格式的。相较于其他Linux安全模块（LSM）， +策略文件体积略大，但能解决其他平台上部分完整性策略方案存在 +的两个核心问题。 + +第一个问题是代码维护和冗余的问题。为了编写策略，策略必须是 +以某种形式的字符串形式呈现（无论是 XML、JSON、YAML 等结构化 +格式，还是其他形式），以便策略编写者能够理解所写内容。在假设 +的二进制策略设计中，需要一个序列化器将策略将可读的形式转换为 +二进制形式，同时还需要一个反序列化器来将二进制形式转换为内核 +中的数据结构。 + +最终，还需要另一个反序列化器将是必要的，用于将二进制形式转换 +为人类可读的形式，并尽可能保存所有信息，这是因为使用此访问控 +制系统的用户必须维护一个校验表和原始文件，才能理解哪些策略已 +经部署在该系统上，哪些没有。对于单个用户来说，这可能没问题， +因为旧的策略可以在更新生效后很快被丢弃。但对于管理成千上万、 +甚至数十万台计算机的用户，且这些计算机有不同的操作系统和不同 +的操作需求，这很快就成了一个问题，因为数年前的过时策略可能仍然 +存在，从而导致需要快速恢复策略或投资大量基础设施来跟踪每个策略 +的内容。 + +有了这三个独立的序列化器/反序列化器，维护成本非常昂贵。如果策略 +避免使用二进制格式，则只需要一个序列化器；将人类可读的形式转换 +为内核中的数据结构。从而节省了代码维护成本，并保持了可操作性。 + +第二个关于二进制格式的问题是透明性，由于IPE根据系统资源的可信度 +来控制访问，因此其策略也必须可信，以便可以被更改。这是通过签名来 +完成的，这就需要签名过程。签名过程通常具有很高的安全标准，因为 +任何被签名的内容都可以被用来攻击完整性执行系统。签署时，签署者 +必须知道他们在签署什么，二进制策略可能会导致这一点的模糊化；签署 +者看到的只是一个不透明的二进制数据块。另一方面，对于纯文本策略中， +签署者看到的则是实际提交的策略。 + +启动策略 +~~~~~~~~ + +如果配置得当，IPE能够在内核启动并进入用户模式时立即执行策略。 +这意味着需要在用户模式开始的那一刻就存储一定的策略。通常，这种 +存储可以通过一下三种方式之一来处理： + + 1. 策略文件存储在磁盘上，内核在进入可能需要做出执行决策的代码 + 路径之前，先加载该策略。 + 2. 策略文件由引导加载程序传递给内核，内核解析这些策略。 + 3. 将一个策略文件编译到内核中，内核在初始化过程中对其进行解析并 + 执行。 + +第一种方式存在问题：内核从用户空间读取文件通常是不推荐的，并且在 +内核中极为罕见。 + +第二种选项同样存在问题：Linux在其整个生态系统中支持多种引导加载程序， +所有引导加载程序都必须支持这种新方法，或者需要有一个独立的来源，这 +可能会导致内核启动过程发生不必要的重大变化。 + +第三种选项是最佳选择，但需要注意的是，编译进内核的策略会占用磁盘空间。 +重要的是要使这一策略足够通用，以便用户空间能够加载新的、更复杂的策略， +同时也要足够严格，以防止过度授权并避免引发安全问题。 + +initramfs提供了一种建立此启动路径的方法。内核启动时以最小化的策略启动， +该策略仅信任initramfs。在initramfs内，当真实的根文件系统已挂载且尚未 +切换时，它会部署并激活一个信任新根文件系统的策略。这种方法防止了在任何 +步骤中出现过度授权，并保持内核策略的最小化。 + +启动 +^^^^ + +然而，并不是每个系统都以initramfs启动，因此编译进内核的启动策略需要具备 +一定的灵活性，以明确如何为启动的下一个阶段建立信任。为此，如果我们将编译 +进内核的策略设计为一个完整的IPE策略，这样系统构建者便能合理定义第一阶段启 +动的需求。 + +可更新、无需重启的策略 +~~~~~~~~~~~~~~~~~~~~~~ + +随着时间的推移，系统需求发生变化（例如，之前信任的应用程序中发现漏洞、秘钥 +轮换等）。更新内核以满足这些安全目标并非始终是一个合适的选择，因为内核更新并 +非完全无风险的，而搁置安全更新会使系统处于脆弱状态。这意味着IPE需要一个可以 +完全更新的策略（允许撤销现有的策略），并且这个更新来源必须是内核外部的（允许 +再不更新内核的情况下更新策略）。 + +此外，由于内核在调用之间是无状态的，并且从内核空间读取磁盘上的策略文件不是一 +个好主意，因此策略更新必须能够在不重启的情况下完成。 + +为了允许从外部来源进行更新，考虑到外部来源可能是恶意的，因此该策略需要具备可被 +识别为可信的机制。这一机制通过签名链实现：策略的签名需与内核中的某个信任源相 +关联。通常，这个信任源是 ``SYSTEM_TRUSTED_KEYRING`` ，这是一个在内核编译时就被 +初始化填充的密钥环，因为这符合上述编译进来策略的制作者与能够部署策略更新的实体 +相同的预期。 + +防回滚 / 防重放 +~~~~~~~~~~~~~~~ + +随着时间的推移，系统可能会发现漏洞，曾经受信任的资源可能不再可信，IPE的 +策略也不例外。可能会出现的情况是，策略制作者误部署了一个不安全的策略， +随后再用一个安全的策略进行修正。 + +假设一旦不安全的策略被部署，攻击者获取了这个不安全的策略，IPE需要有一种 +方式来防止从安全的策略更新回滚到不安全的策略。 + +最初，IPE的策略可以包含一个policy_version字段，声明系统上所有可激活策略 +所需的最低版本号。这将在系统运行期间防止回滚。 + +.. WARNING:: + + 然而，由于内核每次启动都是无状态的，因此该策略版本将在下次 + 启动时被重置为0.0.0。系统构建者需要意识到这一点，并确保在启 + 动后尽快部署新的安全策略，以确保攻击者部署不安全的策略的几 + 率最小化。 + +隐式操作: +~~~~~~~~~ + +隐式操作的问题只有在考虑系统中多个操作具有不同级别时才会显现出来。 +例如，考虑一个系统，该系统对可执行代码和系统中对其功能至关重要的 +特定数据提供强大的完整性保障。在这个系统中，可能存在三种类型的 +策略： + + 1. 一种策略，在这种策略中，如果操作未能匹配到任何规则，则该操 + 作将被拒绝。 + 2. 一种策略，在这种策略中，如果操作未能匹配到任何规则，则该操 + 作将被允许。 + 3. 一种策略，在这种策略中，如果操作未能匹配到任何规则，则执行 + 操作由策略作者指定。 + +第一种类型的策略示例如下:: + + op=EXECUTE integrity_verified=YES action=ALLOW + +在示例系统中，这对于可执行文件来说效果很好，因为所有可执行文件 +都应该拥有完整性保障。但问题出现在第二个要求上，即关于特定数据 +文件的要求。这将导致如下策略（假设策略按行依次执行）:: + + op=EXECUTE integrity_verified=YES action=ALLOW + + op=READ integrity_verified=NO label=critical_t action=DENY + op=READ action=ALLOW + +若阅读过文档，了解策略按顺序执行且默认动作是拒绝，那么这个策略的 +逻辑还算清晰；但最后一行规则实际上将读取操作的默认动作改成了允许。 +这种设计是必要的，因为在实际系统中，存在一些无需验证的读取操作（例 +如向日志文件追加内容时的读取操作）。 + +第二种策略类型（未匹配任何规则时默认允许）在管控特定数据文件时逻辑 +更清晰，其策略可简化为:: + + op=READ integrity_verified=NO label=critical_t action=DENY + +但与第一种策略类似，这种默认允许的策略在管控执行操作时会存在缺陷， +因此仍需显式覆盖默认动作:: + + op=EXECUTE integrity_verified=YES action=ALLOW + op=EXECUTE action=DENY + + op=READ integrity_verified=NO label=critical_t action=DENY + +这就引出了第三种策略类型（自定义默认动作）。该类型无需让用户绞尽脑汁 +通过空规则覆盖默认动作，而是强制用户根据自身场景思考合适的默认动作是 +什么，并显式声明:: + + DEFAULT op=EXECUTE action=DENY + op=EXECUTE integrity_verified=YES action=ALLOW + + DEFAULT op=READ action=ALLOW + op=READ integrity_verified=NO label=critical_t action=DENY + +策略调试: +~~~~~~~~~ + +在开发策略时，知道策略违反了哪一行有助于减少调试成本；可以 +将调查的范围缩小到导致该行为的确切行。有些完整性策略系统并 +不提供这一信息，而是提供评估过程中使用的信息。这随后需要将 +这些信息和策略进行关联，以分析哪里了问题。 + +相反，IPE只会输出匹配到的规则。这将调查范围限制到确切到策略行 +（在特定规则的情况下）或部分（在DEFAULT规则的情况下）。当在 +评估策略时观察到策略失败时，这可以减少迭代和调查的时间。 + +IPE的策略引擎还被设计成让人类容易理解如何调查策略失败。每一 +行都会按编写顺序进行评估，因此算法非常简单，便于人类重现步 +骤并找出可能导致失败的原因。而在调查其他的系统中，加载策略 +时会进行优化（例如对规则排序）。在这些系统中，调试需要多个 +步骤，而且没有先阅读代码的情况下，终端用户可能无法完全理解 +该算法的原理。 + +简化策略: +~~~~~~~~~ + +最后，IPE的策略是为系统管理员设计的，而不是内核开发人员。 +IPE不涉及单独的LSM钩子（或系统调用），而是涵盖操作。这 +意味着，系统管理员不需要知道像 ``mmap`` 、 ``mprotect`` 、 +``execve`` 和 ``uselib`` 这些系统调用必须有规则进行保护， +而只需要知道他们想要限制代码执行。这减少了由于缺乏对底层 +系统的了解而可能导致的绕过情况；而IPE的维护者作为内核开发 +人员，可以做出正确的选择，确定某些操作是否与这些操作匹配， +以及在什么条件下匹配。 + +实现说明 +-------- + +匿名内存 +~~~~~~~~ + +在IPE中，匿名内存的处理方式与其他任何类型的访问没有区别。当匿 +名内存使用 ``+X`` 映射时，它仍然会进入 ``file_mmp`` 或 +``file_mprotect`` 钩子，但此时会带有一个 ``NULL`` 文件对象 +这会像其他文件一样提交进行评估。然而，所有当前的信任属性都会 +评估为假，因为它们都是基于文件的，而此次操作并不与任何文件相关联。 + +.. WARNING:: + + 这也适用于 ``kernel_load_data`` 钩子，当内核从一个没有文件 + 支持的用户空间缓冲区加载数据时。在这种情况下，所有当前的信任 + 属性也将评估为false。 + +Securityfs接口 +~~~~~~~~~~~~~~ + +每个策略的对应的securityfs树是有些独特的。例如，对于一个标准的 +securityfs策略树:: + + MyPolicy + |- active + |- delete + |- name + |- pkcs7 + |- policy + |- update + |- version + +策略存储在MyPolicy对应节点的 ``->i_private`` 数据中。 + +测试 +---- + +IPE为策略解析器提供了KUnit测试。推荐kunitconfig:: + + CONFIG_KUNIT=y + CONFIG_SECURITY=y + CONFIG_SECURITYFS=y + CONFIG_PKCS7_MESSAGE_PARSER=y + CONFIG_SYSTEM_DATA_VERIFICATION=y + CONFIG_FS_VERITY=y + CONFIG_FS_VERITY_BUILTIN_SIGNATURES=y + CONFIG_BLOCK=y + CONFIG_MD=y + CONFIG_BLK_DEV_DM=y + CONFIG_DM_VERITY=y + CONFIG_DM_VERITY_VERIFY_ROOTHASH_SIG=y + CONFIG_NET=y + CONFIG_AUDIT=y + CONFIG_AUDITSYSCALL=y + CONFIG_BLK_DEV_INITRD=y + + CONFIG_SECURITY_IPE=y + CONFIG_IPE_PROP_DM_VERITY=y + CONFIG_IPE_PROP_DM_VERITY_SIGNATURE=y + CONFIG_IPE_PROP_FS_VERITY=y + CONFIG_IPE_PROP_FS_VERITY_BUILTIN_SIG=y + CONFIG_SECURITY_IPE_KUNIT_TEST=y + +此外，IPE 具有一个基于 Python 的集成 +`测试套件 `_ +可以测试用户界面和强制执行功能。 diff --git a/Documentation/translations/zh_CN/security/lsm-development.rst b/Documentation/translations/zh_CN/security/lsm-development.rst new file mode 100644 index 000000000000..7ed3719a9d07 --- /dev/null +++ b/Documentation/translations/zh_CN/security/lsm-development.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/security/lsm-development.rst + +:翻译: + 赵硕 Shuo Zhao + +================= +Linux安全模块开发 +================= + +基于https://lore.kernel.org/r/20071026073721.618b4778@laptopd505.fenrus.org， +当一种新的LSM的意图（它试图防范什么，以及在哪些情况下人们会期望使用它）在 +``Documentation/admin-guide/LSM/`` 中适当记录下来后，就会被接受进入内核。 +这使得LSM的代码可以很轻松的与其目标进行对比，从而让最终用户和发行版可以更 +明智地决定那些LSM适合他们的需求。 + +有关可用的 LSM 钩子接口的详细文档，请参阅 ``security/security.c`` 及相关结构。 diff --git a/Documentation/translations/zh_CN/security/secrets/coco.rst b/Documentation/translations/zh_CN/security/secrets/coco.rst new file mode 100644 index 000000000000..a27bc1acdb7c --- /dev/null +++ b/Documentation/translations/zh_CN/security/secrets/coco.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/security/secrets/coco.rst + +:翻译: + + 赵硕 Shuo Zhao + +============ +机密计算密钥 +============ + +本文档介绍了在EFI驱动程序和efi_secret内核模块中，机密计算密钥从固件 +到操作系统的注入处理流程。 + +简介 +==== + +机密计算硬件（如AMD SEV，Secure Encrypted Virtualization）允许虚拟机 +所有者将密钥注入虚拟机（VM）内存，且主机/虚拟机监控程序无法读取这些密 +钥。在SEV中，密钥注入需在虚拟机启动流程的早期阶段（客户机开始运行前） +执行。 + +efi_secret内核模块允许用户空间应用程序通过securityfs（安全文件系统）访 +问这些密钥。 + +密钥数据流 +========== + +客户机固件可能会为密钥注入预留一块指定的内存区域，并将该区域的位置（基准 +客户机物理地址GPA和长度）在EFI配置表中，通过 ``LINUX_EFI_COCO_SECRET_AREA_GUID`` +条目（对应的GUID值为 ``adf956ad-e98c-484c-ae11-b51c7d336447`` ）的形式发布。 +固件应将此内存区域标记为 ``EFI_RESERVED_TYPE`` ，因此内核不应将其用于自身用途。 + +虚拟机启动过程中，虚拟机管理器可向该区域注入密钥。在AMD SEV和SEV-ES中，此 +操作通过 ``KVM_SEV_LAUNCH_SECRET`` 命令执行（参见 [sev_CN]_ ）。注入的“客户机 +所有者密钥数据”应采用带GUID的密钥值表结构，其二进制格式在 ``drivers/virt/ +coco/efi_secret/efi_secret.c`` 文件的EFI密钥区域结构部分中有详细描述。 + +内核启动时，内核的EFI驱动程序将保存密钥区域位置（来自EFI配置表）到 ``efi.coco_secret`` +字段。随后，它会检查密钥区域是否已填充：映射该区域并检查其内容是否以 +``EFI_SECRET_TABLE_HEADER_GUID`` （对应的GUID为 ``1e74f542-71dd-4d66-963e-ef4287ff173b`` ） +开头。如果密钥区域已填充，EFI驱动程序将自动加载efi_secret内核模块，并通过securityfs将密钥 +暴露给用户空间应用程序。efi_secret文件系统接口的详细信息请参考 [secrets-coco-abi_CN]_ 。 + + +应用使用示例 +============ + +假设客户机需要对加密文件进行计算处理。客户机所有者通过密钥注入机制提供解密密钥 +（即密钥）。客户机应用程序从efi_secret文件系统读取该密钥，然后将文件解密到内存中， +接着对内容进行需要的计算。 + +在此示例中，主机无法从磁盘镜像中读取文件，因为文件是加密的；主机无法读取解密密钥， +因为它是通过密钥注入机制（即安全通道）传递的；主机也无法读取内存中的解密内容，因为 +这是一个机密型（内存加密）客户机。 + +以下是一个简单的示例，展示了在客户机中使用efi_secret模块的过程，在启动时注入了 +一个包含4个密钥的EFI密钥区域:: + + # ls -la /sys/kernel/security/secrets/coco + total 0 + drwxr-xr-x 2 root root 0 Jun 28 11:54 . + drwxr-xr-x 3 root root 0 Jun 28 11:54 .. + -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b + -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6 + -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2 + -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910 + + # hd /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910 + 00000000 74 68 65 73 65 2d 61 72 65 2d 74 68 65 2d 6b 61 |these-are-the-ka| + 00000010 74 61 2d 73 65 63 72 65 74 73 00 01 02 03 04 05 |ta-secrets......| + 00000020 06 07 |..| + 00000022 + + # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910 + + # ls -la /sys/kernel/security/secrets/coco + total 0 + drwxr-xr-x 2 root root 0 Jun 28 11:55 . + drwxr-xr-x 3 root root 0 Jun 28 11:54 .. + -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b + -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6 + -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2 + + +参考文献 +======== + +请参见 [sev-api-spec_CN]_ 以获取有关SEV ``LAUNCH_SECRET`` 操作的更多信息。 + +.. [sev_CN] Documentation/virt/kvm/x86/amd-memory-encryption.rst +.. [secrets-coco-abi_CN] Documentation/ABI/testing/securityfs-secrets-coco +.. [sev-api-spec_CN] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf + diff --git a/Documentation/translations/zh_CN/security/secrets/index.rst b/Documentation/translations/zh_CN/security/secrets/index.rst index 5ea78713f10e..38464dcb2c3c 100644 --- a/Documentation/translations/zh_CN/security/secrets/index.rst +++ b/Documentation/translations/zh_CN/security/secrets/index.rst @@ -5,13 +5,10 @@ :翻译: -===================== +======== 密钥文档 -===================== +======== .. toctree:: - -TODOLIST: - -* coco + coco diff --git a/Documentation/translations/zh_CN/subsystem-apis.rst b/Documentation/translations/zh_CN/subsystem-apis.rst index 8b646c1010be..830217140fb6 100644 --- a/Documentation/translations/zh_CN/subsystem-apis.rst +++ b/Documentation/translations/zh_CN/subsystem-apis.rst @@ -71,12 +71,11 @@ TODOList: :maxdepth: 1 filesystems/index + scsi/index TODOList: -* block/index * cdrom/index -* scsi/index * target/index **Fixme**: 这里还需要更多的分类组织工作。 diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst index 0b038074d9d1..c8b7ccfaa656 100644 --- a/Documentation/translations/zh_TW/admin-guide/README.rst +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -291,5 +291,5 @@ Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 更多用GDB調試內核的信息，請參閱： Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst -和 Documentation/dev-tools/kgdb.rst 。 +和 Documentation/process/debugging/kgdb.rst 。 diff --git a/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst index b595af59ba78..4fd1757c3036 100644 --- a/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst @@ -2,7 +2,7 @@ .. include:: ../disclaimer-zh_TW.rst -:Original: Documentation/dev-tools/gdb-kernel-debugging.rst +:Original: Documentation/process/debugging/gdb-kernel-debugging.rst :Translator: 高超 gao chao 通過gdb調試內核和模塊 diff --git a/Documentation/userspace-api/media/cec/cec-header.rst b/Documentation/userspace-api/media/cec/cec-header.rst index f67003bb8740..648498bc7d6f 100644 --- a/Documentation/userspace-api/media/cec/cec-header.rst +++ b/Documentation/userspace-api/media/cec/cec-header.rst @@ -2,10 +2,12 @@ .. _cec_header: -*************** -CEC Header File -*************** +**************** +CEC uAPI Symbols +**************** .. kernel-include:: include/uapi/linux/cec.h :generate-cross-refs: :exception-file: cec.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/cec/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec/cec.h.rst.exceptions index 15fa1752d4ef..65e8be062bdb 100644 --- a/Documentation/userspace-api/media/cec/cec.h.rst.exceptions +++ b/Documentation/userspace-api/media/cec/cec.h.rst.exceptions @@ -1,5 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 +# All symbols belong to CEC namespace +namespace CEC + # Ignore header name ignore define _CEC_UAPI_H diff --git a/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions index afc14d384b83..2c219388d123 100644 --- a/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions @@ -1,34 +1,36 @@ # SPDX-License-Identifier: GPL-2.0 +# All symbols belone to this namespace +namespace DTV.dmx + # Ignore header name ignore define _UAPI_DVBDMX_H_ # Ignore limit constants ignore define DMX_FILTER_SIZE -# dmx_pes_type_t enum symbols -replace enum dmx_ts_pes :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_OTHER :c:type:`dmx_pes_type` +# dmx_ts_pes_type_t enum symbols +replace symbol DMX_PES_AUDIO0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_OTHER :c:type:`DTV.dmx.dmx_ts_pes` # Ignore obsolete symbols ignore define DMX_PES_AUDIO @@ -38,29 +40,23 @@ ignore define DMX_PES_SUBTITLE ignore define DMX_PES_PCR # dmx_input_t symbols -replace enum dmx_input :c:type:`dmx_input` -replace symbol DMX_IN_FRONTEND :c:type:`dmx_input` -replace symbol DMX_IN_DVR :c:type:`dmx_input` +replace symbol DMX_IN_FRONTEND :c:enum:`DTV.dmx.dmx_input` +replace symbol DMX_IN_DVR :c:enum:`DTV.dmx.dmx_input` # Flags for struct dmx_sct_filter_params -replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params` -replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params` -replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params` +replace define DMX_CHECK_CRC :c:type:`DTV.dmx.dmx_sct_filter_params` +replace define DMX_ONESHOT :c:type:`DTV.dmx.dmx_sct_filter_params` +replace define DMX_IMMEDIATE_START :c:type:`DTV.dmx.dmx_sct_filter_params` -# some typedefs should point to struct/enums -replace typedef dmx_filter_t :c:type:`dmx_filter` -replace typedef dmx_pes_type_t :c:type:`dmx_pes_type` -replace typedef dmx_input_t :c:type:`dmx_input` +replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_TEI :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`DTV.dmx.dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags` - -replace symbol DMX_OUT_DECODER :c:type:`dmx_output` -replace symbol DMX_OUT_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output` +replace symbol DMX_OUT_DECODER :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TAP :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TS_TAP :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`DTV.dmx.dmx_output` replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/userspace-api/media/dvb/dmx_types.rst b/Documentation/userspace-api/media/dvb/dmx_types.rst index 33458fbb84ab..dd76010696c8 100644 --- a/Documentation/userspace-api/media/dvb/dmx_types.rst +++ b/Documentation/userspace-api/media/dvb/dmx_types.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx .. _dmx_types: diff --git a/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions index dcaf5740de7e..cecd4087d4be 100644 --- a/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions +++ b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions @@ -28,13 +28,14 @@ ignore define MAX_DTV_STATS ignore define DTV_IOCTL_MAX_MSGS # the same reference is used for both get and set ioctls -replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY` +replace ioctl FE_SET_PROPERTY :ref:`FE_GET_PROPERTY` +replace ioctl FE_GET_PROPERTY :ref:`FE_GET_PROPERTY` # Typedefs that use the enum reference replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage` # Replaces for flag constants -replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE` +replace define FE_TUNE_MODE_ONESHOT :ref:`FE_SET_FRONTEND_TUNE_MODE` replace define LNA_AUTO dtv-lna replace define NO_STREAM_ID_FILTER dtv-stream-id diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst index c75f64cf21d5..6d69622bf1e0 100644 --- a/Documentation/userspace-api/media/dvb/headers.rst +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -1,25 +1,46 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later -**************************** -Digital TV uAPI header files -**************************** - -Digital TV uAPI headers *********************** +Digital TV uAPI symbols +*********************** + +.. contents:: Table of Contents + :depth: 2 + :local: + +Frontend +======== .. kernel-include:: include/uapi/linux/dvb/frontend.h :generate-cross-refs: :exception-file: frontend.h.rst.exceptions + :toc: + :warn-broken: + +Demux +===== .. kernel-include:: include/uapi/linux/dvb/dmx.h :generate-cross-refs: :exception-file: dmx.h.rst.exceptions + :toc: + :warn-broken: + +Conditional Access +================== .. kernel-include:: include/uapi/linux/dvb/ca.h :generate-cross-refs: :exception-file: ca.h.rst.exceptions + :toc: + :warn-broken: + +Network +======= .. kernel-include:: include/uapi/linux/dvb/net.h :generate-cross-refs: :exception-file: net.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/mediactl/media-header.rst b/Documentation/userspace-api/media/mediactl/media-header.rst index d561d2845f3d..a47ac5b2e99b 100644 --- a/Documentation/userspace-api/media/mediactl/media-header.rst +++ b/Documentation/userspace-api/media/mediactl/media-header.rst @@ -2,10 +2,12 @@ .. _media_header: -**************************** -Media Controller Header File -**************************** +***************************** +Media controller uAPI symbols +***************************** .. kernel-include:: include/uapi/linux/media.h :generate-cross-refs: :exception-file: media.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions b/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions index 9b4c26502d95..09aaec2b4718 100644 --- a/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions +++ b/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions @@ -1,5 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 +# All symbols are mapped inside MC C domain namespace +namespace MC + # Ignore header name ignore define __LINUX_MEDIA_H diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index a53328327847..ba4992625684 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -2,11 +2,19 @@ .. _lirc_header: -**************** -LIRC Header File -**************** +***************** +LIRC uAPI symbols +***************** + +.. contents:: Table of Contents + :depth: 2 + :local: + + .. kernel-include:: include/uapi/linux/lirc.h :generate-cross-refs: :exception-file: lirc.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/v4l/app-pri.rst b/Documentation/userspace-api/media/v4l/app-pri.rst index 626a42f2e138..47d96cd64525 100644 --- a/Documentation/userspace-api/media/v4l/app-pri.rst +++ b/Documentation/userspace-api/media/v4l/app-pri.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _app-pri: diff --git a/Documentation/userspace-api/media/v4l/audio.rst b/Documentation/userspace-api/media/v4l/audio.rst index 17f0b1c89908..3b424440e478 100644 --- a/Documentation/userspace-api/media/v4l/audio.rst +++ b/Documentation/userspace-api/media/v4l/audio.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _audio: diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 856acf6a890c..9721247e66ef 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ********** References diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 856874341882..94dc2719e907 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -667,6 +667,8 @@ Buffer Flags exposure of the frame has begun. This is only valid for the ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. +.. c:enum:: v4l2_memory + .. raw:: latex \normalsize diff --git a/Documentation/userspace-api/media/v4l/capture-example.rst b/Documentation/userspace-api/media/v4l/capture-example.rst index 25891320b7ad..f018a654f59c 100644 --- a/Documentation/userspace-api/media/v4l/capture-example.rst +++ b/Documentation/userspace-api/media/v4l/capture-example.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _capture-example: diff --git a/Documentation/userspace-api/media/v4l/capture.c.rst b/Documentation/userspace-api/media/v4l/capture.c.rst index 349541b1dac0..aae17e1e844a 100644 --- a/Documentation/userspace-api/media/v4l/capture.c.rst +++ b/Documentation/userspace-api/media/v4l/capture.c.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L file: media/v4l/capture.c ========================= diff --git a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst index fe9f8aa8ab9d..0b40e735f3bf 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-defs.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L **************************** Defining Colorspaces in V4L2 diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst index 26a4ace42ca5..f29b0e3978bc 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces-details.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ******************************** Detailed Colorspace Descriptions diff --git a/Documentation/userspace-api/media/v4l/colorspaces.rst b/Documentation/userspace-api/media/v4l/colorspaces.rst index 2aa0dda4fd01..11954d7cf999 100644 --- a/Documentation/userspace-api/media/v4l/colorspaces.rst +++ b/Documentation/userspace-api/media/v4l/colorspaces.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _colorspaces: diff --git a/Documentation/userspace-api/media/v4l/common-defs.rst b/Documentation/userspace-api/media/v4l/common-defs.rst index 6ae42ac7ddb7..329ba6ec760b 100644 --- a/Documentation/userspace-api/media/v4l/common-defs.rst +++ b/Documentation/userspace-api/media/v4l/common-defs.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _common-defs: diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst index ea0435182e44..507c35fec8ce 100644 --- a/Documentation/userspace-api/media/v4l/common.rst +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _common: diff --git a/Documentation/userspace-api/media/v4l/compat.rst b/Documentation/userspace-api/media/v4l/compat.rst index b63b8392dec6..f766ea89f9ff 100644 --- a/Documentation/userspace-api/media/v4l/compat.rst +++ b/Documentation/userspace-api/media/v4l/compat.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _compat: diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst index 9253cc946f02..19372bb32c4b 100644 --- a/Documentation/userspace-api/media/v4l/control.rst +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _control: diff --git a/Documentation/userspace-api/media/v4l/crop.rst b/Documentation/userspace-api/media/v4l/crop.rst index 3fe185e25ccf..c5f389aca275 100644 --- a/Documentation/userspace-api/media/v4l/crop.rst +++ b/Documentation/userspace-api/media/v4l/crop.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _crop: diff --git a/Documentation/userspace-api/media/v4l/depth-formats.rst b/Documentation/userspace-api/media/v4l/depth-formats.rst index b4f3fc229c85..bd61064d51d3 100644 --- a/Documentation/userspace-api/media/v4l/depth-formats.rst +++ b/Documentation/userspace-api/media/v4l/depth-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _depth-formats: diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst b/Documentation/userspace-api/media/v4l/dev-decoder.rst index ef8e8cf31f90..eb662ced0ab4 100644 --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _decoder: diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst index 6c523c69bdce..cdad276d00bc 100644 --- a/Documentation/userspace-api/media/v4l/dev-encoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _encoder: diff --git a/Documentation/userspace-api/media/v4l/dev-event.rst b/Documentation/userspace-api/media/v4l/dev-event.rst index f34f9cf6ce6c..f61d774f0153 100644 --- a/Documentation/userspace-api/media/v4l/dev-event.rst +++ b/Documentation/userspace-api/media/v4l/dev-event.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _event: diff --git a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst index 7041bb3d5b8d..6058eeaefca4 100644 --- a/Documentation/userspace-api/media/v4l/dev-mem2mem.rst +++ b/Documentation/userspace-api/media/v4l/dev-mem2mem.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _mem2mem: diff --git a/Documentation/userspace-api/media/v4l/dev-meta.rst b/Documentation/userspace-api/media/v4l/dev-meta.rst index 5eee9ab60395..da706d01b808 100644 --- a/Documentation/userspace-api/media/v4l/dev-meta.rst +++ b/Documentation/userspace-api/media/v4l/dev-meta.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _metadata: diff --git a/Documentation/userspace-api/media/v4l/dev-osd.rst b/Documentation/userspace-api/media/v4l/dev-osd.rst index 8e4be9129e75..f37450b1b631 100644 --- a/Documentation/userspace-api/media/v4l/dev-osd.rst +++ b/Documentation/userspace-api/media/v4l/dev-osd.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _osd: diff --git a/Documentation/userspace-api/media/v4l/dev-overlay.rst b/Documentation/userspace-api/media/v4l/dev-overlay.rst index d52977120b41..b7f4302eee6e 100644 --- a/Documentation/userspace-api/media/v4l/dev-overlay.rst +++ b/Documentation/userspace-api/media/v4l/dev-overlay.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _overlay: diff --git a/Documentation/userspace-api/media/v4l/dev-radio.rst b/Documentation/userspace-api/media/v4l/dev-radio.rst index 284ce96a1637..843a2151f470 100644 --- a/Documentation/userspace-api/media/v4l/dev-radio.rst +++ b/Documentation/userspace-api/media/v4l/dev-radio.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _radio: diff --git a/Documentation/userspace-api/media/v4l/dev-sdr.rst b/Documentation/userspace-api/media/v4l/dev-sdr.rst index dfdeddbca41f..99907adc0628 100644 --- a/Documentation/userspace-api/media/v4l/dev-sdr.rst +++ b/Documentation/userspace-api/media/v4l/dev-sdr.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _sdr: diff --git a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst index 35ed05f2695e..e311f0c13272 100644 --- a/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _stateless_decoder: diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst index 225a45fef994..2530170a56ae 100644 --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _subdev: diff --git a/Documentation/userspace-api/media/v4l/dev-touch.rst b/Documentation/userspace-api/media/v4l/dev-touch.rst index a71b9def5d58..808957cd9afc 100644 --- a/Documentation/userspace-api/media/v4l/dev-touch.rst +++ b/Documentation/userspace-api/media/v4l/dev-touch.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _touch: diff --git a/Documentation/userspace-api/media/v4l/devices.rst b/Documentation/userspace-api/media/v4l/devices.rst index 8bfbad65a9d4..d4790b9ef81a 100644 --- a/Documentation/userspace-api/media/v4l/devices.rst +++ b/Documentation/userspace-api/media/v4l/devices.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _devices: diff --git a/Documentation/userspace-api/media/v4l/dv-timings.rst b/Documentation/userspace-api/media/v4l/dv-timings.rst index 4b19bcb4bd80..9f117c82df1b 100644 --- a/Documentation/userspace-api/media/v4l/dv-timings.rst +++ b/Documentation/userspace-api/media/v4l/dv-timings.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _dv-timings: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst index cdc515c60468..b4daa7e28dc0 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _camera-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index 0da635691fdc..497ae74379f6 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _codec-stateless-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst index 4a379bd9e3fb..c8890cb5e00a 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _codec-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst index 1e7265155715..38a4136d7220 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _colorimetry-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst index 312c4fa94dc3..ee2b7e37c1d9 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _detect-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst index d2794e03ac6d..5918dde83efb 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _dv-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst index d22c5efb806a..bd024ab461a4 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _flash-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst index ccd439e9e0e3..b7284768f7ea 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _fm-rx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst index cb40cf4cc3ec..7143a4c08f78 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _fm-tx-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst index 27803dca8d3e..6d516f041ca2 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _image-process-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst index 71f23f131f97..f9c0b7ad3b4e 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _image-source-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 522095c08469..b114650bca5b 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _jpeg-controls: diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst index 8a6f9f0373ff..f50802a1c4d4 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _rf-tuner-controls: diff --git a/Documentation/userspace-api/media/v4l/extended-controls.rst b/Documentation/userspace-api/media/v4l/extended-controls.rst index 44fcd67f20bf..5fe71da6afc0 100644 --- a/Documentation/userspace-api/media/v4l/extended-controls.rst +++ b/Documentation/userspace-api/media/v4l/extended-controls.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _extended-controls: diff --git a/Documentation/userspace-api/media/v4l/field-order.rst b/Documentation/userspace-api/media/v4l/field-order.rst index 9a0ed8fc550f..2a01852513b3 100644 --- a/Documentation/userspace-api/media/v4l/field-order.rst +++ b/Documentation/userspace-api/media/v4l/field-order.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _field-order: diff --git a/Documentation/userspace-api/media/v4l/fourcc.rst b/Documentation/userspace-api/media/v4l/fourcc.rst index d3482c40da62..5cea7008814f 100644 --- a/Documentation/userspace-api/media/v4l/fourcc.rst +++ b/Documentation/userspace-api/media/v4l/fourcc.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L Guidelines for Video4Linux pixel format 4CCs ============================================ diff --git a/Documentation/userspace-api/media/v4l/hsv-formats.rst b/Documentation/userspace-api/media/v4l/hsv-formats.rst index d810c914b673..f0731de6f038 100644 --- a/Documentation/userspace-api/media/v4l/hsv-formats.rst +++ b/Documentation/userspace-api/media/v4l/hsv-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _hsv-formats: diff --git a/Documentation/userspace-api/media/v4l/libv4l.rst b/Documentation/userspace-api/media/v4l/libv4l.rst index f446dd2d01ac..ce7a0400891c 100644 --- a/Documentation/userspace-api/media/v4l/libv4l.rst +++ b/Documentation/userspace-api/media/v4l/libv4l.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _libv4l: diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index 0de80328c36b..d9868ee88a07 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _meta-formats: diff --git a/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst b/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst index 449b45c2ec24..24359601ae25 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-c3-isp.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: (GPL-2.0-only OR MIT) +.. c:namespace:: V4L .. _v4l2-meta-fmt-c3isp-stats: .. _v4l2-meta-fmt-c3isp-params: diff --git a/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst index 0686413b16b2..d716170bb795 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-d4xx.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-d4xx: diff --git a/Documentation/userspace-api/media/v4l/metafmt-generic.rst b/Documentation/userspace-api/media/v4l/metafmt-generic.rst index 39d529c910a8..23f69e1a1afa 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-generic.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-generic.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ******************************************************************************************************************************************************************************************************************************************************************************** V4L2_META_FMT_GENERIC_8 ('MET8'), V4L2_META_FMT_GENERIC_CSI2_10 ('MC1A'), V4L2_META_FMT_GENERIC_CSI2_12 ('MC1C'), V4L2_META_FMT_GENERIC_CSI2_14 ('MC1E'), V4L2_META_FMT_GENERIC_CSI2_16 ('MC1G'), V4L2_META_FMT_GENERIC_CSI2_20 ('MC1K'), V4L2_META_FMT_GENERIC_CSI2_24 ('MC1O') diff --git a/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst index 84d81dd7a7b5..c11d17e5a286 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-intel-ipu3.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-params: .. _v4l2-meta-fmt-stat-3a: diff --git a/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst b/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst index 3281fe366c86..e230177910f4 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-pisp-be.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _v4l2-meta-fmt-rpi-be-cfg: diff --git a/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst b/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst index fddeada83e4a..a2aa5c4c2920 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-pisp-fe.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _v4l2-meta-fmt-rpi-fe-cfg: diff --git a/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst index 959f6bde8695..d3c899b0150b 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-rkisp1.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. c:namespace:: V4L .. _v4l2-meta-fmt-rk-isp1-stat-3a: diff --git a/Documentation/userspace-api/media/v4l/metafmt-uvc.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst index 4c05e9e54683..c4ae2f13e7f7 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-uvc.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-uvc: diff --git a/Documentation/userspace-api/media/v4l/metafmt-vivid.rst b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst index 7173e2c3e245..94f28736dc80 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-vivid.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vivid.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-vivid: diff --git a/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst index 8d886feb180c..70357899a5f0 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgo.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-vsp1-hgo: diff --git a/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst index d8830ff605de..4a1575a9e728 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-vsp1-hgt.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-meta-fmt-vsp1-hgt: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst index b5ca501842b0..8b4e413177f5 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _pixfmt-bayer: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst b/Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst index 8f469290c304..4e3e9c5f4387 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst @@ -1,4 +1,5 @@ .. -*- coding: utf-8; mode: rst -*- +.. c:namespace:: V4L .. _V4L2-PIX-FMT-CNF4: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 806ed73ac474..c7efb0465db6 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ****************** Compressed Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst index 5bd4a47c5854..08d698ebdd64 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-indexed.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _pixfmt-indexed: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst index 14239ee826bf..00c1b7b0e907 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-intro.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-intro.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ********************** Standard Image Formats diff --git a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst index 3115c8f6a842..0af3a303a7f0 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-inzi.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-INZI: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst index c01a949e7c11..f44a6c5eaddf 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-M420: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst index dd89860f50e0..d1cab3c632f1 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _packed-hsv: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst index 9f111ed594d2..ae7d88ae1c3d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _packed-yuv: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst index ac52485252d9..1cf6c59f4bc4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _pixfmt-reserved: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index 5ed4d62df909..cf6760bb6109 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _pixfmt-rgb: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst index bd6ee6111de4..b2dda90409d9 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-sdr-fmt-cs8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst index ea21b288d357..df8b4b22ebce 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-CS14LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst index 45fce09d85ff..86accef8f9f4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-sdr-fmt-cu8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst index 7f4242f8da6f..13d8c86e9b1d 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-CU16LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst index a4d4b70ece63..9c4908d57a25 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-PCU16BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst index 3db690bd683a..56c3f2aee0a4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-PCU18BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst index 485343cdf150..1992ee5dd2bc 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-PCU20BE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst index 2ad4706bfc7a..3b2a94e64bcd 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-SDR-FMT-RU12LE: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst index 3322b0600f1d..de4720dba48a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-pix-fmt-ipu3-sbggr10: .. _v4l2-pix-fmt-ipu3-sgbrg10: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst index a66414ab4291..6b4950ad54e0 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB10: .. _v4l2-pix-fmt-sbggr10: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst index a5ae1f099e68..42176c437ebe 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SBGGR10ALAW8: .. _v4l2-pix-fmt-sgbrg10alaw8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst index f0544c6f4580..dac580181562 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SBGGR10DPCM8: .. _v4l2-pix-fmt-sgbrg10dpcm8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst index fd5feb415531..af91f12c24e8 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB10P: .. _v4l2-pix-fmt-sbggr10p: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst index 15c34e1e4835..2b3212ef732f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB12: .. _v4l2-pix-fmt-sbggr12: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index 8c03aedcc00e..cffb3dfc338a 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB12P: .. _v4l2-pix-fmt-sbggr12p: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst index 4f5120a6c678..7a3552c045a3 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB14: .. _v4l2-pix-fmt-sbggr14: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index f4f53d7dbdeb..330197aded11 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB14P: .. _v4l2-pix-fmt-sbggr14p: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst index 2f2f1ef430d9..dab222f49522 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB16: .. _v4l2-pix-fmt-sbggr16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst index 5a82a15559d6..7a55a3c7c9f6 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8-pisp-comp.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-pix-fmt-pisp-comp1-rggb: .. _v4l2-pix-fmt-pisp-comp1-grbg: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst index 02061c5a9778..4cb263a6ea26 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-SRGGB8: .. _v4l2-pix-fmt-sbggr8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst index ec89f43c60ec..37b03da07cf4 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-TCH-FMT-DELTA-TD08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst index 7b59a6424243..66d3d7041550 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-TCH-FMT-DELTA-TD16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst index 63c5264b8668..b10bb7bad025 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-TCH-FMT-TU08: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst index ade618a037a8..889298d010a1 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-TCH-FMT-TU16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst index ff1d73ef5dba..8fa97b57ad75 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-uv8.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-UV8: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index ad4da988c3a3..7069b2a6b0b1 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ****************************** Multi-planar format structures diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst index 9c423ffe02f9..995267741a26 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ****************************** Single-planar format structure diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst index d9b539381d74..b4223ce3506c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y12i.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-Y12I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst index 74ba9e910a38..51f216f24e41 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y16i.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-Y16I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst index 770ed4749c14..c5a3648d37e5 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-y8i.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-Y8I: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 74df19be91f6..99bcc6d385b7 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _yuv-luma-only: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst index 6e4f399f1f88..0631919bd667 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. planar-yuv: diff --git a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst index 54a8cd723d1a..3ab8844d2e6f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-z16.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-z16.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _V4L2-PIX-FMT-Z16: diff --git a/Documentation/userspace-api/media/v4l/pixfmt.rst b/Documentation/userspace-api/media/v4l/pixfmt.rst index 11dab4a90630..71b29267488f 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _pixfmt: diff --git a/Documentation/userspace-api/media/v4l/planar-apis.rst b/Documentation/userspace-api/media/v4l/planar-apis.rst index 9207ce4283df..075754f0e423 100644 --- a/Documentation/userspace-api/media/v4l/planar-apis.rst +++ b/Documentation/userspace-api/media/v4l/planar-apis.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _planar-apis: diff --git a/Documentation/userspace-api/media/v4l/querycap.rst b/Documentation/userspace-api/media/v4l/querycap.rst index 15a90271af45..c96f7654c870 100644 --- a/Documentation/userspace-api/media/v4l/querycap.rst +++ b/Documentation/userspace-api/media/v4l/querycap.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _querycap: diff --git a/Documentation/userspace-api/media/v4l/sdr-formats.rst b/Documentation/userspace-api/media/v4l/sdr-formats.rst index d8bdfdb56911..df76b7d2aaf2 100644 --- a/Documentation/userspace-api/media/v4l/sdr-formats.rst +++ b/Documentation/userspace-api/media/v4l/sdr-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _sdr-formats: diff --git a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst index fee49bf1a1c0..978c401f4252 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-configuration.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-configuration.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ************* Configuration diff --git a/Documentation/userspace-api/media/v4l/selection-api-examples.rst b/Documentation/userspace-api/media/v4l/selection-api-examples.rst index 5f8e8a1f59d7..3cf7c067f20f 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-examples.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-examples.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ******** Examples diff --git a/Documentation/userspace-api/media/v4l/selection-api-intro.rst b/Documentation/userspace-api/media/v4l/selection-api-intro.rst index 6534854ae9f7..817e660ce016 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-intro.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-intro.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ************ Introduction diff --git a/Documentation/userspace-api/media/v4l/selection-api-targets.rst b/Documentation/userspace-api/media/v4l/selection-api-targets.rst index 50fdadd5b307..e1aaaa3a7123 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-targets.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-targets.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L ***************** Selection targets diff --git a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst index f57b9180012c..0c0d66a0cfe6 100644 --- a/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _selection-vs-crop: diff --git a/Documentation/userspace-api/media/v4l/selection-api.rst b/Documentation/userspace-api/media/v4l/selection-api.rst index 0360743746dc..1320eb632272 100644 --- a/Documentation/userspace-api/media/v4l/selection-api.rst +++ b/Documentation/userspace-api/media/v4l/selection-api.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _selection-api: diff --git a/Documentation/userspace-api/media/v4l/selections-common.rst b/Documentation/userspace-api/media/v4l/selections-common.rst index 322b39cf0eba..e08da7a9b599 100644 --- a/Documentation/userspace-api/media/v4l/selections-common.rst +++ b/Documentation/userspace-api/media/v4l/selections-common.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-selections-common: diff --git a/Documentation/userspace-api/media/v4l/standard.rst b/Documentation/userspace-api/media/v4l/standard.rst index 1f6678325da9..53818e37db5f 100644 --- a/Documentation/userspace-api/media/v4l/standard.rst +++ b/Documentation/userspace-api/media/v4l/standard.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _standard: diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 2a94371448dc..1904390df830 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-mbus-format: diff --git a/Documentation/userspace-api/media/v4l/tch-formats.rst b/Documentation/userspace-api/media/v4l/tch-formats.rst index 8c941ff9e200..a382d1c20eb3 100644 --- a/Documentation/userspace-api/media/v4l/tch-formats.rst +++ b/Documentation/userspace-api/media/v4l/tch-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _tch-formats: diff --git a/Documentation/userspace-api/media/v4l/tuner.rst b/Documentation/userspace-api/media/v4l/tuner.rst index e2c53c3abdc6..c82f68d2f900 100644 --- a/Documentation/userspace-api/media/v4l/tuner.rst +++ b/Documentation/userspace-api/media/v4l/tuner.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _tuner: diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst index 6f661138801c..5fc95c792408 100644 --- a/Documentation/userspace-api/media/v4l/user-func.rst +++ b/Documentation/userspace-api/media/v4l/user-func.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _user-func: diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst index 1cb1531c1e52..6aa00b613148 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-selection-flags: diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst index b46bae984f35..e9fd4b4bad42 100644 --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2-selection-targets: diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst index 64fb264fb6c4..be07b717ebe0 100644 --- a/Documentation/userspace-api/media/v4l/v4l2.rst +++ b/Documentation/userspace-api/media/v4l/v4l2.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. include:: .. _v4l2spec: diff --git a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst index b323be42c580..b2472d4b0e3f 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab-example.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab-example.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _v4l2grab-example: diff --git a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst index 1a55e3617ea8..c958db1e0211 100644 --- a/Documentation/userspace-api/media/v4l/v4l2grab.c.rst +++ b/Documentation/userspace-api/media/v4l/v4l2grab.c.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L file: media/v4l/v4l2grab.c ========================== diff --git a/Documentation/userspace-api/media/v4l/video.rst b/Documentation/userspace-api/media/v4l/video.rst index f8f69a57602c..25cb854c1101 100644 --- a/Documentation/userspace-api/media/v4l/video.rst +++ b/Documentation/userspace-api/media/v4l/video.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _video: diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documentation/userspace-api/media/v4l/videodev.rst index cde485bc9a5f..0b71a60928fb 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -1,11 +1,14 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _videodev: -******************************* -Video For Linux Two Header File -******************************* +*************************************** +Video For Linux Two Header uAPI Symbols +*************************************** .. kernel-include:: include/uapi/linux/videodev2.h :generate-cross-refs: :exception-file: videodev2.h.rst.exceptions + :toc: + :warn-broken: diff --git a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions index 35d3456cc812..c41693115db6 100644 --- a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions @@ -1,5 +1,8 @@ # SPDX-License-Identifier: GPL-2.0 +# All symbols are mapped inside V4L C domain namespace +namespace V4L + # Ignore header name ignore define _UAPI__LINUX_VIDEODEV2_H @@ -15,157 +18,158 @@ ignore define _UAPI__LINUX_VIDEODEV2_H ignore symbol V4L2_BUF_TYPE_PRIVATE ignore symbol V4L2_TUNER_DIGITAL_TV ignore symbol V4L2_COLORSPACE_BT878 +ignore struct __kernel_v4l2_timeval # Documented enum v4l2_field -replace symbol V4L2_FIELD_ALTERNATE :c:type:`v4l2_field` -replace symbol V4L2_FIELD_ANY :c:type:`v4l2_field` -replace symbol V4L2_FIELD_BOTTOM :c:type:`v4l2_field` -replace symbol V4L2_FIELD_INTERLACED :c:type:`v4l2_field` -replace symbol V4L2_FIELD_INTERLACED_BT :c:type:`v4l2_field` -replace symbol V4L2_FIELD_INTERLACED_TB :c:type:`v4l2_field` -replace symbol V4L2_FIELD_NONE :c:type:`v4l2_field` -replace symbol V4L2_FIELD_SEQ_BT :c:type:`v4l2_field` -replace symbol V4L2_FIELD_SEQ_TB :c:type:`v4l2_field` -replace symbol V4L2_FIELD_TOP :c:type:`v4l2_field` +replace symbol V4L2_FIELD_ALTERNATE :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_ANY :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_BOTTOM :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_INTERLACED :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_INTERLACED_BT :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_INTERLACED_TB :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_NONE :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_SEQ_BT :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_SEQ_TB :c:type:`V4L.v4l2_field` +replace symbol V4L2_FIELD_TOP :c:type:`V4L.v4l2_field` # Documented enum v4l2_buf_type -replace symbol V4L2_BUF_TYPE_META_CAPTURE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_META_OUTPUT :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_SDR_CAPTURE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_SDR_OUTPUT :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_SLICED_VBI_OUTPUT :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VBI_CAPTURE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VBI_OUTPUT :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY :c:type:`v4l2_buf_type` -replace symbol V4L2_BUF_TYPE_VIDEO_OVERLAY :c:type:`v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_META_CAPTURE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_META_OUTPUT :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_SDR_CAPTURE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_SDR_OUTPUT :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_SLICED_VBI_OUTPUT :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VBI_CAPTURE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VBI_OUTPUT :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY :c:type:`V4L.v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_VIDEO_OVERLAY :c:type:`V4L.v4l2_buf_type` # Documented enum v4l2_tuner_type -replace symbol V4L2_TUNER_ANALOG_TV :c:type:`v4l2_tuner_type` -replace symbol V4L2_TUNER_RADIO :c:type:`v4l2_tuner_type` -replace symbol V4L2_TUNER_RF :c:type:`v4l2_tuner_type` -replace symbol V4L2_TUNER_SDR :c:type:`v4l2_tuner_type` +replace symbol V4L2_TUNER_ANALOG_TV :c:type:`V4L.v4l2_tuner_type` +replace symbol V4L2_TUNER_RADIO :c:type:`V4L.v4l2_tuner_type` +replace symbol V4L2_TUNER_RF :c:type:`V4L.v4l2_tuner_type` +replace symbol V4L2_TUNER_SDR :c:type:`V4L.v4l2_tuner_type` # Documented enum v4l2_memory -replace symbol V4L2_MEMORY_DMABUF :c:type:`v4l2_memory` -replace symbol V4L2_MEMORY_MMAP :c:type:`v4l2_memory` -replace symbol V4L2_MEMORY_OVERLAY :c:type:`v4l2_memory` -replace symbol V4L2_MEMORY_USERPTR :c:type:`v4l2_memory` +replace symbol V4L2_MEMORY_DMABUF :c:type:`V4L.v4l2_memory` +replace symbol V4L2_MEMORY_MMAP :c:type:`V4L.v4l2_memory` +replace symbol V4L2_MEMORY_OVERLAY :c:type:`V4L.v4l2_memory` +replace symbol V4L2_MEMORY_USERPTR :c:type:`V4L.v4l2_memory` # Documented enum v4l2_colorspace -replace symbol V4L2_COLORSPACE_470_SYSTEM_BG :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_470_SYSTEM_M :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_OPRGB :c:type:`v4l2_colorspace` -replace define V4L2_COLORSPACE_ADOBERGB :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_BT2020 :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_DCI_P3 :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_DEFAULT :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_JPEG :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_RAW :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_REC709 :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_SMPTE170M :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_SMPTE240M :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_SRGB :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_LAST :c:type:`v4l2_colorspace` +replace symbol V4L2_COLORSPACE_470_SYSTEM_BG :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_470_SYSTEM_M :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_OPRGB :c:type:`V4L.v4l2_colorspace` +replace define V4L2_COLORSPACE_ADOBERGB :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_BT2020 :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_DCI_P3 :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_DEFAULT :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_JPEG :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_RAW :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_REC709 :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_SMPTE170M :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_SMPTE240M :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_SRGB :c:type:`V4L.v4l2_colorspace` +replace symbol V4L2_COLORSPACE_LAST :c:type:`V4L.v4l2_colorspace` # Documented enum v4l2_xfer_func -replace symbol V4L2_XFER_FUNC_709 :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_OPRGB :c:type:`v4l2_xfer_func` -replace define V4L2_XFER_FUNC_ADOBERGB :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_DCI_P3 :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_DEFAULT :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_NONE :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_SMPTE2084 :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_SMPTE240M :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_SRGB :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_LAST :c:type:`v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_709 :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_OPRGB :c:type:`V4L.v4l2_xfer_func` +replace define V4L2_XFER_FUNC_ADOBERGB :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_DCI_P3 :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_DEFAULT :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_NONE :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_SMPTE2084 :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_SMPTE240M :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_SRGB :c:type:`V4L.v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_LAST :c:type:`V4L.v4l2_xfer_func` # Documented enum v4l2_ycbcr_encoding -replace symbol V4L2_YCBCR_ENC_601 :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_709 :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_BT2020 :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_BT2020_CONST_LUM :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_DEFAULT :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_SYCC :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_XV601 :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_XV709 :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_SMPTE240M :c:type:`v4l2_ycbcr_encoding` -replace symbol V4L2_YCBCR_ENC_LAST :c:type:`v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_601 :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_709 :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_BT2020 :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_BT2020_CONST_LUM :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_DEFAULT :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_SYCC :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_XV601 :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_XV709 :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_SMPTE240M :c:type:`V4L.v4l2_ycbcr_encoding` +replace symbol V4L2_YCBCR_ENC_LAST :c:type:`V4L.v4l2_ycbcr_encoding` # Documented enum v4l2_hsv_encoding -replace symbol V4L2_HSV_ENC_180 :c:type:`v4l2_hsv_encoding` -replace symbol V4L2_HSV_ENC_256 :c:type:`v4l2_hsv_encoding` +replace symbol V4L2_HSV_ENC_180 :c:type:`V4L.v4l2_hsv_encoding` +replace symbol V4L2_HSV_ENC_256 :c:type:`V4L.v4l2_hsv_encoding` # Documented enum v4l2_quantization -replace symbol V4L2_QUANTIZATION_DEFAULT :c:type:`v4l2_quantization` -replace symbol V4L2_QUANTIZATION_FULL_RANGE :c:type:`v4l2_quantization` -replace symbol V4L2_QUANTIZATION_LIM_RANGE :c:type:`v4l2_quantization` +replace symbol V4L2_QUANTIZATION_DEFAULT :c:type:`V4L.v4l2_quantization` +replace symbol V4L2_QUANTIZATION_FULL_RANGE :c:type:`V4L.v4l2_quantization` +replace symbol V4L2_QUANTIZATION_LIM_RANGE :c:type:`V4L.v4l2_quantization` # Documented enum v4l2_priority -replace symbol V4L2_PRIORITY_BACKGROUND :c:type:`v4l2_priority` -replace symbol V4L2_PRIORITY_DEFAULT :c:type:`v4l2_priority` -replace symbol V4L2_PRIORITY_INTERACTIVE :c:type:`v4l2_priority` -replace symbol V4L2_PRIORITY_RECORD :c:type:`v4l2_priority` -replace symbol V4L2_PRIORITY_UNSET :c:type:`v4l2_priority` +replace symbol V4L2_PRIORITY_BACKGROUND :c:type:`V4L.v4l2_priority` +replace symbol V4L2_PRIORITY_DEFAULT :c:type:`V4L.v4l2_priority` +replace symbol V4L2_PRIORITY_INTERACTIVE :c:type:`V4L.v4l2_priority` +replace symbol V4L2_PRIORITY_RECORD :c:type:`V4L.v4l2_priority` +replace symbol V4L2_PRIORITY_UNSET :c:type:`V4L.v4l2_priority` # Documented enum v4l2_frmsizetypes -replace symbol V4L2_FRMSIZE_TYPE_CONTINUOUS :c:type:`v4l2_frmsizetypes` -replace symbol V4L2_FRMSIZE_TYPE_DISCRETE :c:type:`v4l2_frmsizetypes` -replace symbol V4L2_FRMSIZE_TYPE_STEPWISE :c:type:`v4l2_frmsizetypes` +replace symbol V4L2_FRMSIZE_TYPE_CONTINUOUS :c:type:`V4L.v4l2_frmsizetypes` +replace symbol V4L2_FRMSIZE_TYPE_DISCRETE :c:type:`V4L.v4l2_frmsizetypes` +replace symbol V4L2_FRMSIZE_TYPE_STEPWISE :c:type:`V4L.v4l2_frmsizetypes` # Documented enum frmivaltypes -replace symbol V4L2_FRMIVAL_TYPE_CONTINUOUS :c:type:`v4l2_frmivaltypes` -replace symbol V4L2_FRMIVAL_TYPE_DISCRETE :c:type:`v4l2_frmivaltypes` -replace symbol V4L2_FRMIVAL_TYPE_STEPWISE :c:type:`v4l2_frmivaltypes` +replace symbol V4L2_FRMIVAL_TYPE_CONTINUOUS :c:type:`V4L.v4l2_frmivaltypes` +replace symbol V4L2_FRMIVAL_TYPE_DISCRETE :c:type:`V4L.v4l2_frmivaltypes` +replace symbol V4L2_FRMIVAL_TYPE_STEPWISE :c:type:`V4L.v4l2_frmivaltypes` -# Documented enum :c:type:`v4l2_ctrl_type` +# Documented enum :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_COMPOUND_TYPES vidioc_queryctrl -replace symbol V4L2_CTRL_TYPE_BITMASK :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_BOOLEAN :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_BUTTON :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_CTRL_CLASS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_INTEGER :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_INTEGER64 :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_INTEGER_MENU :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MENU :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_STRING :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_U16 :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MPEG2_SEQUENCE :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_PRED_WEIGHTS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_AREA :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_RECT :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_VP9_FRAME :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_AV1_SEQUENCE :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_AV1_FRAME :c:type:`v4l2_ctrl_type` -replace symbol V4L2_CTRL_TYPE_AV1_FILM_GRAIN :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_BITMASK :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_BOOLEAN :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_BUTTON :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_CTRL_CLASS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_INTEGER :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_INTEGER64 :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_INTEGER_MENU :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MENU :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_STRING :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_U16 :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_U32 :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_U8 :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_SEQUENCE :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PRED_WEIGHTS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AREA :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_RECT :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_FWHT_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP8_FRAME :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_VP9_FRAME :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_CLL_INFO :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_SEQUENCE :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FRAME :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_AV1_FILM_GRAIN :c:type:`V4L.v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities @@ -201,10 +205,10 @@ replace define V4L2_CAP_IO_MC device-capabilities replace define V4L2_CAP_EDID device-capabilities # V4L2 pix flags -replace define V4L2_PIX_FMT_PRIV_MAGIC :c:type:`v4l2_pix_format` +replace define V4L2_PIX_FMT_PRIV_MAGIC :c:type:`V4L.v4l2_pix_format` replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA format-flags -replace define V4L2_PIX_FMT_HM12 :c:type:`v4l2_pix_format` -replace define V4L2_PIX_FMT_SUNXI_TILED_NV12 :c:type:`v4l2_pix_format` +replace define V4L2_PIX_FMT_HM12 :c:type:`V4L.v4l2_pix_format` +replace define V4L2_PIX_FMT_SUNXI_TILED_NV12 :c:type:`V4L.v4l2_pix_format` # V4L2 format flags replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags @@ -263,7 +267,7 @@ replace define V4L2_FBUF_FLAG_SRC_CHROMAKEY framebuffer-flags # Used on VIDIOC_G_PARM replace define V4L2_MODE_HIGHQUALITY parm-flags -replace define V4L2_CAP_TIMEPERFRAME :c:type:`v4l2_captureparm` +replace define V4L2_CAP_TIMEPERFRAME :c:type:`V4L.v4l2_captureparm` # The V4L2_STD_foo are all defined at v4l2_std_id table @@ -316,11 +320,11 @@ replace define V4L2_STD_ALL v4l2-std-id # V4L2 DT BT timings definitions -replace define V4L2_DV_PROGRESSIVE :c:type:`v4l2_bt_timings` -replace define V4L2_DV_INTERLACED :c:type:`v4l2_bt_timings` +replace define V4L2_DV_PROGRESSIVE :c:type:`V4L.v4l2_bt_timings` +replace define V4L2_DV_INTERLACED :c:type:`V4L.v4l2_bt_timings` -replace define V4L2_DV_VSYNC_POS_POL :c:type:`v4l2_bt_timings` -replace define V4L2_DV_HSYNC_POS_POL :c:type:`v4l2_bt_timings` +replace define V4L2_DV_VSYNC_POS_POL :c:type:`V4L.v4l2_bt_timings` +replace define V4L2_DV_HSYNC_POS_POL :c:type:`V4L.v4l2_bt_timings` replace define V4L2_DV_BT_STD_CEA861 dv-bt-standards replace define V4L2_DV_BT_STD_DMT dv-bt-standards @@ -456,11 +460,11 @@ replace define V4L2_AUDMODE_AVL audio-mode # MPEG -replace define V4L2_ENC_IDX_FRAME_I :c:type:`v4l2_enc_idx` -replace define V4L2_ENC_IDX_FRAME_P :c:type:`v4l2_enc_idx` -replace define V4L2_ENC_IDX_FRAME_B :c:type:`v4l2_enc_idx` -replace define V4L2_ENC_IDX_FRAME_MASK :c:type:`v4l2_enc_idx` -replace define V4L2_ENC_IDX_ENTRIES :c:type:`v4l2_enc_idx` +replace define V4L2_ENC_IDX_FRAME_I :c:type:`V4L.v4l2_enc_idx` +replace define V4L2_ENC_IDX_FRAME_P :c:type:`V4L.v4l2_enc_idx` +replace define V4L2_ENC_IDX_FRAME_B :c:type:`V4L.v4l2_enc_idx` +replace define V4L2_ENC_IDX_FRAME_MASK :c:type:`V4L.v4l2_enc_idx` +replace define V4L2_ENC_IDX_ENTRIES :c:type:`V4L.v4l2_enc_idx` replace define V4L2_ENC_CMD_START encoder-cmds replace define V4L2_ENC_CMD_STOP encoder-cmds @@ -488,10 +492,10 @@ replace define V4L2_DEC_START_FMT_GOP decoder-cmds replace define V4L2_VBI_UNSYNC vbifmt-flags replace define V4L2_VBI_INTERLACED vbifmt-flags -replace define V4L2_VBI_ITU_525_F1_START :c:type:`v4l2_vbi_format` -replace define V4L2_VBI_ITU_525_F2_START :c:type:`v4l2_vbi_format` -replace define V4L2_VBI_ITU_625_F1_START :c:type:`v4l2_vbi_format` -replace define V4L2_VBI_ITU_625_F2_START :c:type:`v4l2_vbi_format` +replace define V4L2_VBI_ITU_525_F1_START :c:type:`V4L.v4l2_vbi_format` +replace define V4L2_VBI_ITU_525_F2_START :c:type:`V4L.v4l2_vbi_format` +replace define V4L2_VBI_ITU_625_F1_START :c:type:`V4L.v4l2_vbi_format` +replace define V4L2_VBI_ITU_625_F2_START :c:type:`V4L.v4l2_vbi_format` replace define V4L2_SLICED_TELETEXT_B vbi-services @@ -527,7 +531,7 @@ replace define V4L2_EVENT_CTRL_CH_DIMENSIONS ctrl-changes-flags replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags -replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` +replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`V4L.v4l2_event_motion_det` replace define V4L2_EVENT_SUB_FL_SEND_INITIAL event-flags replace define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK event-flags diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 3549417c7feb..c8baa9430c14 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -15,6 +15,8 @@ VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls Synopsis ======== +.. c:macro:: VIDIOC_QUERY_CTRL + ``int ioctl(int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp)`` .. c:macro:: VIDIOC_QUERY_EXT_CTRL @@ -98,6 +100,8 @@ See also the examples in :ref:`control`. .. _v4l2-queryctrl: +.. c:struct:: v4l2_queryctrl + .. cssclass:: longtable .. flat-table:: struct v4l2_queryctrl @@ -178,6 +182,8 @@ See also the examples in :ref:`control`. .. cssclass:: longtable +.. c:struct:: v4l2_query_ext_ctrl + .. flat-table:: struct v4l2_query_ext_ctrl :header-rows: 0 :stub-columns: 0 @@ -276,6 +282,8 @@ See also the examples in :ref:`control`. .. _v4l2-querymenu: +.. c:struct:: v4l2_querymenu + .. flat-table:: struct v4l2_querymenu :header-rows: 0 :stub-columns: 0 diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst index 78ee406d7647..c5ef408470a5 100644 --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst @@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L .. _yuv-formats: diff --git a/Documentation/userspace-api/spec_ctrl.rst b/Documentation/userspace-api/spec_ctrl.rst index 5e8ed9eef9aa..ca89151fc0a8 100644 --- a/Documentation/userspace-api/spec_ctrl.rst +++ b/Documentation/userspace-api/spec_ctrl.rst @@ -26,7 +26,8 @@ PR_GET_SPECULATION_CTRL PR_GET_SPECULATION_CTRL returns the state of the speculation misfeature which is selected with arg2 of prctl(2). The return value uses bits 0-3 with -the following meaning: +the following meaning (with the caveat that PR_SPEC_L1D_FLUSH has less obvious +semantics, see documentation for that specific control below): ==== ====================== ================================================== Bit Define Description @@ -110,6 +111,9 @@ Speculation misfeature controls - PR_SPEC_L1D_FLUSH: Flush L1D Cache on context switch out of the task (works only when tasks run on non SMT cores) +For this control, PR_SPEC_ENABLE means that the **mitigation** is enabled (L1D +is flushed), PR_SPEC_DISABLE means it is disabled. + Invocations: * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, 0, 0, 0); * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, PR_SPEC_ENABLE, 0, 0); diff --git a/Documentation/w1/w1-netlink.rst b/Documentation/w1/w1-netlink.rst index be4f7b82dcb4..ff281713e626 100644 --- a/Documentation/w1/w1-netlink.rst +++ b/Documentation/w1/w1-netlink.rst @@ -196,7 +196,7 @@ Additional documentation, source code examples ============================================== 1. Documentation/driver-api/connector.rst -2. http://www.ioremap.net/archive/w1 +2. https://github.com/bioothod/w1 This archive includes userspace application w1d.c which uses read/write/search commands for all master/slave devices found on the bus. diff --git a/MAINTAINERS b/MAINTAINERS index ff0106c3f149..618e23f99dfa 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7418,16 +7418,10 @@ S: Maintained P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next F: Documentation/ -F: scripts/check-variable-fonts.sh -F: scripts/checktransupdate.py -F: scripts/documentation-file-ref-check -F: scripts/get_abi.py F: scripts/kernel-doc* -F: scripts/lib/abi/* -F: scripts/lib/kdoc/* -F: tools/docs/* +F: tools/lib/python/* +F: tools/docs/ F: tools/net/ynl/pyynl/lib/doc_generator.py -F: scripts/sphinx-pre-install X: Documentation/ABI/ X: Documentation/admin-guide/media/ X: Documentation/devicetree/ @@ -7460,9 +7454,10 @@ DOCUMENTATION SCRIPTS M: Mauro Carvalho Chehab L: linux-doc@vger.kernel.org S: Maintained -F: Documentation/sphinx/parse-headers.pl -F: scripts/documentation-file-ref-check -F: scripts/sphinx-pre-install +F: Documentation/sphinx/ +F: scripts/kernel-doc* +F: tools/lib/python/* +F: tools/docs/ DOCUMENTATION/ITALIAN M: Federico Vaga diff --git a/Makefile b/Makefile index 6f0e72ff4d0c..03d9bb851eff 100644 --- a/Makefile +++ b/Makefile @@ -1800,9 +1800,10 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs htmldocs-redirects \ - epubdocs cleandocs linkcheckdocs dochelp refcheckdocs \ - texinfodocs infodocs +DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \ + linkcheckdocs dochelp refcheckdocs texinfodocs infodocs mandocs \ + htmldocs-redirects + PHONY += $(DOC_TARGETS) $(DOC_TARGETS): $(Q)$(MAKE) $(build)=Documentation $@ diff --git a/README b/README index fd903645e6de..a9fc263ccd71 100644 --- a/README +++ b/README @@ -1,18 +1,156 @@ Linux kernel ============ -There are several guides for kernel developers and users. These guides can -be rendered in a number of formats, like HTML and PDF. Please read -Documentation/admin-guide/README.rst first. +The Linux kernel is the core of any Linux operating system. It manages hardware, +system resources, and provides the fundamental services for all other software. -In order to build the documentation, use ``make htmldocs`` or -``make pdfdocs``. The formatted documentation can also be read online at: +Quick Start +----------- - https://www.kernel.org/doc/html/latest/ +* Report a bug: See Documentation/admin-guide/reporting-issues.rst +* Get the latest kernel: https://kernel.org +* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst +* Join the community: https://lore.kernel.org/ -There are various text files in the Documentation/ subdirectory, -several of them using the reStructuredText markup notation. +Essential Documentation +----------------------- -Please read the Documentation/process/changes.rst file, as it contains the -requirements for building and running the kernel, and information about -the problems which may result by upgrading your kernel. +All users should be familiar with: + +* Building requirements: Documentation/process/changes.rst +* Code of Conduct: Documentation/process/code-of-conduct.rst +* License: See COPYING + +Documentation can be built with make htmldocs or viewed online at: +https://www.kernel.org/doc/html/latest/ + + +Who Are You? +============ + +Find your role below: + +* New Kernel Developer - Getting started with kernel development +* Academic Researcher - Studying kernel internals and architecture +* Security Expert - Hardening and vulnerability analysis +* Backport/Maintenance Engineer - Maintaining stable kernels +* System Administrator - Configuring and troubleshooting +* Maintainer - Leading subsystems and reviewing patches +* Hardware Vendor - Writing drivers for new hardware +* Distribution Maintainer - Packaging kernels for distros + + +For Specific Users +================== + +New Kernel Developer +-------------------- + +Welcome! Start your kernel development journey here: + +* Getting Started: Documentation/process/development-process.rst +* Your First Patch: Documentation/process/submitting-patches.rst +* Coding Style: Documentation/process/coding-style.rst +* Build System: Documentation/kbuild/index.rst +* Development Tools: Documentation/dev-tools/index.rst +* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst +* Core APIs: Documentation/core-api/index.rst + +Academic Researcher +------------------- + +Explore the kernel's architecture and internals: + +* Researcher Guidelines: Documentation/process/researcher-guidelines.rst +* Memory Management: Documentation/mm/index.rst +* Scheduler: Documentation/scheduler/index.rst +* Networking Stack: Documentation/networking/index.rst +* Filesystems: Documentation/filesystems/index.rst +* RCU (Read-Copy Update): Documentation/RCU/index.rst +* Locking Primitives: Documentation/locking/index.rst +* Power Management: Documentation/power/index.rst + +Security Expert +--------------- + +Security documentation and hardening guides: + +* Security Documentation: Documentation/security/index.rst +* LSM Development: Documentation/security/lsm-development.rst +* Self Protection: Documentation/security/self-protection.rst +* Reporting Vulnerabilities: Documentation/process/security-bugs.rst +* CVE Procedures: Documentation/process/cve.rst +* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst +* Security Features: Documentation/userspace-api/seccomp_filter.rst + +Backport/Maintenance Engineer +----------------------------- + +Maintain and stabilize kernel versions: + +* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst +* Backporting Guide: Documentation/process/backporting.rst +* Applying Patches: Documentation/process/applying-patches.rst +* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst +* Git for Maintainers: Documentation/maintainer/configure-git.rst + +System Administrator +-------------------- + +Configure, tune, and troubleshoot Linux systems: + +* Admin Guide: Documentation/admin-guide/index.rst +* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst +* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst +* Tracing/Debugging: Documentation/trace/index.rst +* Performance Security: Documentation/admin-guide/perf-security.rst +* Hardware Monitoring: Documentation/hwmon/index.rst + +Maintainer +---------- + +Lead kernel subsystems and manage contributions: + +* Maintainer Handbook: Documentation/maintainer/index.rst +* Pull Requests: Documentation/maintainer/pull-requests.rst +* Managing Patches: Documentation/maintainer/modifying-patches.rst +* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst +* Development Process: Documentation/process/maintainer-handbooks.rst +* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst +* Git Configuration: Documentation/maintainer/configure-git.rst + +Hardware Vendor +--------------- + +Write drivers and support new hardware: + +* Driver API Guide: Documentation/driver-api/index.rst +* Driver Model: Documentation/driver-api/driver-model/driver.rst +* Device Drivers: Documentation/driver-api/infrastructure.rst +* Bus Types: Documentation/driver-api/driver-model/bus.rst +* Device Tree Bindings: Documentation/devicetree/bindings/ +* Power Management: Documentation/driver-api/pm/index.rst +* DMA API: Documentation/core-api/dma-api.rst + +Distribution Maintainer +----------------------- + +Package and distribute the kernel: + +* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst +* ABI Documentation: Documentation/ABI/README +* Kernel Configuration: Documentation/kbuild/kconfig.rst +* Module Signing: Documentation/admin-guide/module-signing.rst +* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst +* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst + + + +Communication and Support +========================= + +* Mailing Lists: https://lore.kernel.org/ +* IRC: #kernelnewbies on irc.oftc.net +* Bugzilla: https://bugzilla.kernel.org/ +* MAINTAINERS file: Lists subsystem maintainers and mailing lists +* Email Clients: Documentation/process/email-clients.rst diff --git a/scripts/check-variable-fonts.sh b/scripts/check-variable-fonts.sh deleted file mode 100755 index ce63f0acea5f..000000000000 --- a/scripts/check-variable-fonts.sh +++ /dev/null @@ -1,115 +0,0 @@ -#!/bin/sh -# SPDX-License-Identifier: GPL-2.0-only -# Copyright (C) Akira Yokosawa, 2024 -# -# For "make pdfdocs", reports of build errors of translations.pdf started -# arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE -# tumbleweed have started deploying variable-font [3] format of "Noto CJK" -# fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK -# (Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which -# does not (and likely never will) understand variable fonts for historical -# reasons. -# -# The build error happens even when both of variable- and non-variable-format -# fonts are found on the build system. To make matters worse, Fedora enlists -# variable "Noto CJK" fonts in the requirements of langpacks-ja, -ko, -zh_CN, -# -zh_TW, etc. Hence developers who have interest in CJK pages are more -# likely to encounter the build errors. -# -# This script is invoked from the error path of "make pdfdocs" and emits -# suggestions if variable-font files of "Noto CJK" fonts are in the list of -# fonts accessible from XeTeX. -# -# References: -# [1]: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ -# [2]: https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/ -# [3]: https://en.wikipedia.org/wiki/Variable_font -# [4]: https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts -# [5]: https://build.opensuse.org/request/show/1157217 -# -#=========================================================================== -# Workarounds for building translations.pdf -#=========================================================================== -# -# * Denylist "variable font" Noto CJK fonts. -# - Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with -# tweaks if necessary. Remove leading "# ". -# - Path of fontconfig/fonts.conf can be overridden by setting an env -# variable FONTS_CONF_DENY_VF. -# -# * Template: -# ----------------------------------------------------------------- -# -# -# -# -# -# -# -# /usr/share/fonts/google-noto-*-cjk-vf-fonts -# -# /usr/share/fonts/truetype/Noto*CJK*-VF.otf -# -# -# -# ----------------------------------------------------------------- -# -# The denylisting is activated for "make pdfdocs". -# -# * For skipping CJK pages in PDF -# - Uninstall texlive-xecjk. -# Denylisting is not needed in this case. -# -# * For printing CJK pages in PDF -# - Need non-variable "Noto CJK" fonts. -# * Fedora -# - google-noto-sans-cjk-fonts -# - google-noto-serif-cjk-fonts -# * openSUSE tumbleweed -# - Non-variable "Noto CJK" fonts are not available as distro packages -# as of April, 2024. Fetch a set of font files from upstream Noto -# CJK Font released at: -# https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc -# and at: -# https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc -# , then uncompress and deploy them. -# - Remember to update fontconfig cache by running fc-cache. -# -# !!! Caution !!! -# Uninstalling "variable font" packages can be dangerous. -# They might be depended upon by other packages important for your work. -# Denylisting should be less invasive, as it is effective only while -# XeLaTeX runs in "make pdfdocs". - -# Default per-user fontconfig path (overridden by env variable) -: ${FONTS_CONF_DENY_VF:=$HOME/deny-vf} - -export XDG_CONFIG_HOME=${FONTS_CONF_DENY_VF} - -notocjkvffonts=`fc-list : file family variable | \ - grep 'variable=True' | \ - grep -E -e 'Noto (Sans|Sans Mono|Serif) CJK' | \ - sed -e 's/^/ /' -e 's/: Noto S.*$//' | sort | uniq` - -if [ "x$notocjkvffonts" != "x" ] ; then - echo '=============================================================================' - echo 'XeTeX is confused by "variable font" files listed below:' - echo "$notocjkvffonts" - echo - echo 'For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.' - echo 'Or, CJK pages can be skipped by uninstalling texlive-xecjk.' - echo - echo 'For more info on denylisting, other options, and variable font, see header' - echo 'comments of scripts/check-variable-fonts.sh.' - echo '=============================================================================' -fi - -# As this script is invoked from Makefile's error path, always error exit -# regardless of whether any variable font is discovered or not. -exit 1 diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl deleted file mode 100755 index 40fb28c8424e..000000000000 --- a/scripts/get_feat.pl +++ /dev/null @@ -1,641 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 - -use strict; -use Pod::Usage; -use Getopt::Long; -use File::Find; -use Fcntl ':mode'; -use Cwd 'abs_path'; - -my $help; -my $man; -my $debug; -my $arch; -my $feat; -my $enable_fname; - -my $basename = abs_path($0); -$basename =~ s,/[^/]+$,/,; - -my $prefix=$basename . "../Documentation/features"; - -# Used only at for full features output. The script will auto-adjust -# such values for the minimal possible values -my $status_size = 1; -my $description_size = 1; - -GetOptions( - "debug|d+" => \$debug, - "dir=s" => \$prefix, - 'help|?' => \$help, - 'arch=s' => \$arch, - 'feat=s' => \$feat, - 'feature=s' => \$feat, - "enable-fname" => \$enable_fname, - man => \$man -) or pod2usage(2); - -pod2usage(1) if $help; -pod2usage(-exitstatus => 0, -verbose => 2) if $man; - -pod2usage(1) if (scalar @ARGV < 1 || @ARGV > 2); - -my ($cmd, $arg) = @ARGV; - -pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate" - && $cmd ne "ls" && $cmd ne "list"); - -require Data::Dumper if ($debug); - -my %data; -my %archs; - -# -# Displays an error message, printing file name and line -# -sub parse_error($$$$) { - my ($file, $ln, $msg, $data) = @_; - - $data =~ s/\s+$/\n/; - - print STDERR "Warning: file $file#$ln:\n\t$msg"; - - if ($data ne "") { - print STDERR ". Line\n\t\t$data"; - } else { - print STDERR "\n"; - } -} - -# -# Parse a features file, storing its contents at %data -# - -my $h_name = "Feature"; -my $h_kconfig = "Kconfig"; -my $h_description = "Description"; -my $h_subsys = "Subsystem"; -my $h_status = "Status"; -my $h_arch = "Architecture"; - -my $max_size_name = length($h_name); -my $max_size_kconfig = length($h_kconfig); -my $max_size_description = length($h_description); -my $max_size_subsys = length($h_subsys); -my $max_size_status = length($h_status); - -my $max_size_arch = 0; -my $max_size_arch_with_header; -my $max_description_word = 0; - -sub parse_feat { - my $file = $File::Find::name; - - my $mode = (stat($file))[2]; - return if ($mode & S_IFDIR); - return if ($file =~ m,($prefix)/arch-support.txt,); - return if (!($file =~ m,arch-support.txt$,)); - - if ($enable_fname) { - printf ".. FILE %s\n", abs_path($file); - } - - my $subsys = ""; - $subsys = $2 if ( m,.*($prefix)/([^/]+).*,); - - if (length($subsys) > $max_size_subsys) { - $max_size_subsys = length($subsys); - } - - my $name; - my $kconfig; - my $description; - my $comments = ""; - my $last_status; - my $ln; - my %arch_table; - - print STDERR "Opening $file\n" if ($debug > 1); - open IN, $file; - - while() { - $ln++; - - if (m/^\#\s+Feature\s+name:\s*(.*\S)/) { - $name = $1; - if (length($name) > $max_size_name) { - $max_size_name = length($name); - } - next; - } - if (m/^\#\s+Kconfig:\s*(.*\S)/) { - $kconfig = $1; - if (length($kconfig) > $max_size_kconfig) { - $max_size_kconfig = length($kconfig); - } - next; - } - if (m/^\#\s+description:\s*(.*\S)/) { - $description = $1; - if (length($description) > $max_size_description) { - $max_size_description = length($description); - } - - foreach my $word (split /\s+/, $description) { - if (length($word) > $max_description_word) { - $max_description_word = length($word); - } - } - - next; - } - next if (m/^\\s*$/); - next if (m/^\s*\-+\s*$/); - next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/); - - if (m/^\#\s*(.*)/) { - $comments .= "$1\n"; - next; - } - if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) { - my $a = $1; - my $status = $2; - - if (length($status) > $max_size_status) { - $max_size_status = length($status); - } - if (length($a) > $max_size_arch) { - $max_size_arch = length($a); - } - - $status = "---" if ($status =~ m/^\.\.$/); - - $archs{$a} = 1; - $arch_table{$a} = $status; - next; - } - - #Everything else is an error - parse_error($file, $ln, "line is invalid", $_); - } - close IN; - - if (!$name) { - parse_error($file, $ln, "Feature name not found", ""); - return; - } - - parse_error($file, $ln, "Subsystem not found", "") if (!$subsys); - parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig); - parse_error($file, $ln, "Description not found", "") if (!$description); - - if (!%arch_table) { - parse_error($file, $ln, "Architecture table not found", ""); - return; - } - - $data{$name}->{where} = $file; - $data{$name}->{subsys} = $subsys; - $data{$name}->{kconfig} = $kconfig; - $data{$name}->{description} = $description; - $data{$name}->{comments} = $comments; - $data{$name}->{table} = \%arch_table; - - $max_size_arch_with_header = $max_size_arch + length($h_arch); -} - -# -# Output feature(s) for a given architecture -# -sub output_arch_table { - my $title = "Feature status on $arch architecture"; - - print "=" x length($title) . "\n"; - print "$title\n"; - print "=" x length($title) . "\n\n"; - - print "=" x $max_size_subsys; - print " "; - print "=" x $max_size_name; - print " "; - print "=" x $max_size_kconfig; - print " "; - print "=" x $max_size_status; - print " "; - print "=" x $max_size_description; - print "\n"; - printf "%-${max_size_subsys}s ", $h_subsys; - printf "%-${max_size_name}s ", $h_name; - printf "%-${max_size_kconfig}s ", $h_kconfig; - printf "%-${max_size_status}s ", $h_status; - printf "%-${max_size_description}s\n", $h_description; - print "=" x $max_size_subsys; - print " "; - print "=" x $max_size_name; - print " "; - print "=" x $max_size_kconfig; - print " "; - print "=" x $max_size_status; - print " "; - print "=" x $max_size_description; - print "\n"; - - foreach my $name (sort { - ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || - ("\L$a" cmp "\L$b") - } keys %data) { - next if ($feat && $name ne $feat); - - my %arch_table = %{$data{$name}->{table}}; - printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; - printf "%-${max_size_name}s ", $name; - printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; - printf "%-${max_size_status}s ", $arch_table{$arch}; - printf "%-s\n", $data{$name}->{description}; - } - - print "=" x $max_size_subsys; - print " "; - print "=" x $max_size_name; - print " "; - print "=" x $max_size_kconfig; - print " "; - print "=" x $max_size_status; - print " "; - print "=" x $max_size_description; - print "\n"; -} - -# -# list feature(s) for a given architecture -# -sub list_arch_features { - print "#\n# Kernel feature support matrix of the '$arch' architecture:\n#\n"; - - foreach my $name (sort { - ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || - ("\L$a" cmp "\L$b") - } keys %data) { - next if ($feat && $name ne $feat); - - my %arch_table = %{$data{$name}->{table}}; - - my $status = $arch_table{$arch}; - $status = " " x ((4 - length($status)) / 2) . $status; - - printf " %${max_size_subsys}s/ ", $data{$name}->{subsys}; - printf "%-${max_size_name}s: ", $name; - printf "%-5s| ", $status; - printf "%${max_size_kconfig}s # ", $data{$name}->{kconfig}; - printf " %s\n", $data{$name}->{description}; - } -} - -# -# Output a feature on all architectures -# -sub output_feature { - my $title = "Feature $feat"; - - print "=" x length($title) . "\n"; - print "$title\n"; - print "=" x length($title) . "\n\n"; - - print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys}); - print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig}); - - my $desc = $data{$feat}->{description}; - $desc =~ s/^([a-z])/\U$1/; - $desc =~ s/\.?\s*//; - print "\n$desc.\n\n"; - - my $com = $data{$feat}->{comments}; - $com =~ s/^\s+//; - $com =~ s/\s+$//; - if ($com) { - print "Comments\n"; - print "--------\n\n"; - print "$com\n\n"; - } - - print "=" x $max_size_arch_with_header; - print " "; - print "=" x $max_size_status; - print "\n"; - - printf "%-${max_size_arch}s ", $h_arch; - printf "%-${max_size_status}s", $h_status . "\n"; - - print "=" x $max_size_arch_with_header; - print " "; - print "=" x $max_size_status; - print "\n"; - - my %arch_table = %{$data{$feat}->{table}}; - foreach my $arch (sort keys %arch_table) { - printf "%-${max_size_arch}s ", $arch; - printf "%-${max_size_status}s\n", $arch_table{$arch}; - } - - print "=" x $max_size_arch_with_header; - print " "; - print "=" x $max_size_status; - print "\n"; -} - -# -# Output all features for all architectures -# - -sub matrix_lines($$$) { - my $desc_size = shift; - my $status_size = shift; - my $header = shift; - my $fill; - my $ln_marker; - - if ($header) { - $ln_marker = "="; - } else { - $ln_marker = "-"; - } - - $fill = $ln_marker; - - print "+"; - print $fill x $max_size_name; - print "+"; - print $fill x $desc_size; - print "+"; - print $ln_marker x $status_size; - print "+\n"; -} - -sub output_matrix { - my $title = "Feature status on all architectures"; - my $notcompat = "Not compatible"; - - print "=" x length($title) . "\n"; - print "$title\n"; - print "=" x length($title) . "\n\n"; - - my $desc_title = "$h_kconfig / $h_description"; - - my $desc_size = $max_size_kconfig + 4; - if (!$description_size) { - $desc_size = $max_size_description if ($max_size_description > $desc_size); - } else { - $desc_size = $description_size if ($description_size > $desc_size); - } - $desc_size = $max_description_word if ($max_description_word > $desc_size); - - $desc_size = length($desc_title) if (length($desc_title) > $desc_size); - - $max_size_status = length($notcompat) if (length($notcompat) > $max_size_status); - - # Ensure that the status will fit - my $min_status_size = $max_size_status + $max_size_arch + 6; - $status_size = $min_status_size if ($status_size < $min_status_size); - - - my $cur_subsys = ""; - foreach my $name (sort { - ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or - ("\L$a" cmp "\L$b") - } keys %data) { - - if ($cur_subsys ne $data{$name}->{subsys}) { - if ($cur_subsys ne "") { - printf "\n"; - } - - $cur_subsys = $data{$name}->{subsys}; - - my $title = "Subsystem: $cur_subsys"; - print "$title\n"; - print "=" x length($title) . "\n\n"; - - - matrix_lines($desc_size, $status_size, 0); - - printf "|%-${max_size_name}s", $h_name; - printf "|%-${desc_size}s", $desc_title; - - printf "|%-${status_size}s|\n", "Status per architecture"; - matrix_lines($desc_size, $status_size, 1); - } - - my %arch_table = %{$data{$name}->{table}}; - my $cur_status = ""; - - my (@lines, @descs); - my $line = ""; - foreach my $arch (sort { - ($arch_table{$b} cmp $arch_table{$a}) or - ("\L$a" cmp "\L$b") - } keys %arch_table) { - - my $status = $arch_table{$arch}; - - if ($status eq "---") { - $status = $notcompat; - } - - if ($status ne $cur_status) { - if ($line ne "") { - push @lines, $line; - $line = ""; - } - $line = "- **" . $status . "**: " . $arch; - } elsif (length($line) + length ($arch) + 2 < $status_size) { - $line .= ", " . $arch; - } else { - push @lines, $line; - $line = " " . $arch; - } - $cur_status = $status; - } - push @lines, $line if ($line ne ""); - - my $description = $data{$name}->{description}; - while (length($description) > $desc_size) { - my $d = substr $description, 0, $desc_size; - - # Ensure that it will end on a space - # if it can't, it means that the size is too small - # Instead of aborting it, let's print what we have - if (!($d =~ s/^(.*)\s+.*/$1/)) { - $d = substr $d, 0, -1; - push @descs, "$d\\"; - $description =~ s/^\Q$d\E//; - } else { - push @descs, $d; - $description =~ s/^\Q$d\E\s+//; - } - } - push @descs, $description; - - # Ensure that the full description will be printed - push @lines, "" while (scalar(@lines) < 2 + scalar(@descs)); - - my $ln = 0; - for my $line(@lines) { - if (!$ln) { - printf "|%-${max_size_name}s", $name; - printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; - } elsif ($ln >= 2 && scalar(@descs)) { - printf "|%-${max_size_name}s", ""; - printf "|%-${desc_size}s", shift @descs; - } else { - printf "|%-${max_size_name}s", ""; - printf "|%-${desc_size}s", ""; - } - - printf "|%-${status_size}s|\n", $line; - - $ln++; - } - matrix_lines($desc_size, $status_size, 0); - } -} - - -# -# Parses all feature files located at $prefix dir -# -find({wanted =>\&parse_feat, no_chdir => 1}, $prefix); - -print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); - -# -# Handles the command -# -if ($cmd eq "current") { - $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/' | sed 's/s390x/s390/'); - $arch =~s/\s+$//; -} - -if ($cmd eq "ls" or $cmd eq "list") { - if (!$arch) { - $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/' | sed 's/s390x/s390/'); - $arch =~s/\s+$//; - } - - list_arch_features; - - exit; -} - -if ($cmd ne "validate") { - if ($arch) { - output_arch_table; - } elsif ($feat) { - output_feature; - } else { - output_matrix; - } -} - -__END__ - -=head1 NAME - -get_feat.pl - parse the Linux Feature files and produce a ReST book. - -=head1 SYNOPSIS - -B [--debug] [--man] [--help] [--dir=] [--arch=] - [--feature=|--feat=] [] - -Where can be: - -=over 8 - -B - output table in ReST compatible ASCII format - with features for this machine's architecture - -B - output table(s) in ReST compatible ASCII format - with features in ReST markup language. The output - is affected by --arch or --feat/--feature flags. - -B - validate the contents of the files under - Documentation/features. - -B or B - list features for this machine's architecture, - using an easier to parse format. - The output is affected by --arch flag. - -=back - -=head1 OPTIONS - -=over 8 - -=item B<--arch> - -Output features for an specific architecture, optionally filtering for -a single specific feature. - -=item B<--feat> or B<--feature> - -Output features for a single specific feature. - -=item B<--dir> - -Changes the location of the Feature files. By default, it uses -the Documentation/features directory. - -=item B<--enable-fname> - -Prints the file name of the feature files. This can be used in order to -track dependencies during documentation build. - -=item B<--debug> - -Put the script in verbose mode, useful for debugging. Can be called multiple -times, to increase verbosity. - -=item B<--help> - -Prints a brief help message and exits. - -=item B<--man> - -Prints the manual page and exits. - -=back - -=head1 DESCRIPTION - -Parse the Linux feature files from Documentation/features (by default), -optionally producing results at ReST format. - -It supports output data per architecture, per feature or a -feature x arch matrix. - -When used with B command, it will use either one of the tree formats: - -If neither B<--arch> or B<--feature> arguments are used, it will output a -matrix with features per architecture. - -If B<--arch> argument is used, it will output the features availability for -a given architecture. - -If B<--feat> argument is used, it will output the content of the feature -file using ReStructured Text markup. - -=head1 BUGS - -Report bugs to Mauro Carvalho Chehab - -=head1 COPYRIGHT - -Copyright (c) 2019 by Mauro Carvalho Chehab . - -License GPLv2: GNU GPL version 2 . - -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -=cut diff --git a/scripts/jobserver-exec b/scripts/jobserver-exec index 7eca035472d3..758e947a6fb9 100755 --- a/scripts/jobserver-exec +++ b/scripts/jobserver-exec @@ -1,77 +1,35 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: GPL-2.0+ -# -# This determines how many parallel tasks "make" is expecting, as it is -# not exposed via an special variables, reserves them all, runs a subprocess -# with PARALLELISM environment variable set, and releases the jobs back again. -# -# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver -from __future__ import print_function -import os, sys, errno -import subprocess -# Extract and prepare jobserver file descriptors from environment. -claim = 0 -jobs = b"" -try: - # Fetch the make environment options. - flags = os.environ['MAKEFLAGS'] +""" +Determines how many parallel tasks "make" is expecting, as it is +not exposed via any special variables, reserves them all, runs a subprocess +with PARALLELISM environment variable set, and releases the jobs back again. - # Look for "--jobserver=R,W" - # Note that GNU Make has used --jobserver-fds and --jobserver-auth - # so this handles all of them. - opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] +See: + https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver +""" - # Parse out R,W file descriptor numbers and set them nonblocking. - # If the MAKEFLAGS variable contains multiple instances of the - # --jobserver-auth= option, the last one is relevant. - fds = opts[-1].split("=", 1)[1] +import os +import sys - # Starting with GNU Make 4.4, named pipes are used for reader and writer. - # Example argument: --jobserver-auth=fifo:/tmp/GMfifo8134 - _, _, path = fds.partition('fifo:') +LIB_DIR = "../tools/lib/python" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) - if path: - reader = os.open(path, os.O_RDONLY | os.O_NONBLOCK) - writer = os.open(path, os.O_WRONLY) - else: - reader, writer = [int(x) for x in fds.split(",", 1)] - # Open a private copy of reader to avoid setting nonblocking - # on an unexpecting process with the same reader fd. - reader = os.open("/proc/self/fd/%d" % (reader), - os.O_RDONLY | os.O_NONBLOCK) +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) - # Read out as many jobserver slots as possible. - while True: - try: - slot = os.read(reader, 8) - jobs += slot - except (OSError, IOError) as e: - if e.errno == errno.EWOULDBLOCK: - # Stop at the end of the jobserver queue. - break - # If something went wrong, give back the jobs. - if len(jobs): - os.write(writer, jobs) - raise e - # Add a bump for our caller's reserveration, since we're just going - # to sit here blocked on our child. - claim = len(jobs) + 1 -except (KeyError, IndexError, ValueError, OSError, IOError) as e: - # Any missing environment strings or bad fds should result in just - # not being parallel. - pass +from jobserver import JobserverExec # pylint: disable=C0415 -# We can only claim parallelism if there was a jobserver (i.e. a top-level -# "-jN" argument) and there were no other failures. Otherwise leave out the -# environment variable and let the child figure out what is best. -if claim > 0: - os.environ['PARALLELISM'] = '%d' % (claim) -rc = subprocess.call(sys.argv[1:]) +def main(): + """Main program""" + if len(sys.argv) < 2: + name = os.path.basename(__file__) + sys.exit("usage: " + name +" command [args ...]\n" + __doc__) -# Return all the reserved slots. -if len(jobs): - os.write(writer, jobs) + with JobserverExec() as jobserver: + jobserver.run(sys.argv[1:]) -sys.exit(rc) + +if __name__ == "__main__": + main() diff --git a/scripts/kernel-doc.pl b/scripts/kernel-doc.pl deleted file mode 100755 index 5db23cbf4eb2..000000000000 --- a/scripts/kernel-doc.pl +++ /dev/null @@ -1,2439 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# vim: softtabstop=4 - -use warnings; -use strict; - -## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## -## Copyright (C) 2000, 1 Tim Waugh ## -## Copyright (C) 2001 Simon Huggins ## -## Copyright (C) 2005-2012 Randy Dunlap ## -## Copyright (C) 2012 Dan Luedtke ## -## ## -## #define enhancements by Armin Kuster ## -## Copyright (c) 2000 MontaVista Software, Inc. ## -# -# Copyright (C) 2022 Tomasz Warniełło (POD) - -use Pod::Usage qw/pod2usage/; - -=head1 NAME - -kernel-doc - Print formatted kernel documentation to stdout - -=head1 SYNOPSIS - - kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections] - [ -man | - -rst [-enable-lineno] | - -none - ] - [ - -export | - -internal | - [-function NAME] ... | - [-nosymbol NAME] ... - ] - [-no-doc-sections] - [-export-file FILE] ... - FILE ... - -Run `kernel-doc -h` for details. - -=head1 DESCRIPTION - -Read C language source or header FILEs, extract embedded documentation comments, -and print formatted documentation to standard output. - -The documentation comments are identified by the "/**" opening comment mark. - -See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. - -=cut - -# more perldoc at the end of the file - -## init lots of data - -my $errors = 0; -my $warnings = 0; -my $anon_struct_union = 0; - -# match expressions used to find embedded type information -my $type_constant = '\b``([^\`]+)``\b'; -my $type_constant2 = '\%([-_*\w]+)'; -my $type_func = '(\w+)\(\)'; -my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; -my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; -my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params -my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params -my $type_env = '(\$\w+)'; -my $type_enum = '\&(enum\s*([_\w]+))'; -my $type_struct = '\&(struct\s*([_\w]+))'; -my $type_typedef = '\&(typedef\s*([_\w]+))'; -my $type_union = '\&(union\s*([_\w]+))'; -my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; -my $type_fallback = '\&([_\w]+)'; -my $type_member_func = $type_member . '\(\)'; - -# Output conversion substitutions. -# One for each output format - -# these are pretty rough -my @highlights_man = ( - [$type_constant, "\$1"], - [$type_constant2, "\$1"], - [$type_func, "\\\\fB\$1\\\\fP"], - [$type_enum, "\\\\fI\$1\\\\fP"], - [$type_struct, "\\\\fI\$1\\\\fP"], - [$type_typedef, "\\\\fI\$1\\\\fP"], - [$type_union, "\\\\fI\$1\\\\fP"], - [$type_param, "\\\\fI\$1\\\\fP"], - [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], - [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], - [$type_fallback, "\\\\fI\$1\\\\fP"] - ); -my $blankline_man = ""; - -# rst-mode -my @highlights_rst = ( - [$type_constant, "``\$1``"], - [$type_constant2, "``\$1``"], - - # Note: need to escape () to avoid func matching later - [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], - [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], - [$type_fp_param, "**\$1\\\\(\\\\)**"], - [$type_fp_param2, "**\$1\\\\(\\\\)**"], - [$type_func, "\$1()"], - [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], - [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], - [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], - [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], - - # in rst this can refer to any type - [$type_fallback, "\\:c\\:type\\:`\$1`"], - [$type_param_ref, "**\$1\$2**"] - ); -my $blankline_rst = "\n"; - -# read arguments -if ($#ARGV == -1) { - pod2usage( - -message => "No arguments!\n", - -exitval => 1, - -verbose => 99, - -sections => 'SYNOPSIS', - -output => \*STDERR, - ); -} - -my $kernelversion; - -my $dohighlight = ""; - -my $verbose = 0; -my $Werror = 0; -my $Wreturn = 0; -my $Wshort_desc = 0; -my $output_mode = "rst"; -my $output_preformatted = 0; -my $no_doc_sections = 0; -my $enable_lineno = 0; -my @highlights = @highlights_rst; -my $blankline = $blankline_rst; -my $modulename = "Kernel API"; - -use constant { - OUTPUT_ALL => 0, # output all symbols and doc sections - OUTPUT_INCLUDE => 1, # output only specified symbols - OUTPUT_EXPORTED => 2, # output exported symbols - OUTPUT_INTERNAL => 3, # output non-exported symbols -}; -my $output_selection = OUTPUT_ALL; -my $show_not_found = 0; # No longer used - -my @export_file_list; - -my @build_time; -if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && - (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { - @build_time = gmtime($seconds); -} else { - @build_time = localtime; -} - -my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', - 'July', 'August', 'September', 'October', - 'November', 'December')[$build_time[4]] . - " " . ($build_time[5]+1900); - -# Essentially these are globals. -# They probably want to be tidied up, made more localised or something. -# CAVEAT EMPTOR! Some of the others I localised may not want to be, which -# could cause "use of undefined value" or other bugs. -my ($function, %function_table, %parametertypes, $declaration_purpose); -my %nosymbol_table = (); -my $declaration_start_line; -my ($type, $declaration_name, $return_type); -my ($newsection, $newcontents, $prototype, $brcount); - -if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') { - $verbose = 1; -} - -if (defined($ENV{'KCFLAGS'})) { - my $kcflags = "$ENV{'KCFLAGS'}"; - - if ($kcflags =~ /(\s|^)-Werror(\s|$)/) { - $Werror = 1; - } -} - -# reading this variable is for backwards compat just in case -# someone was calling it with the variable from outside the -# kernel's build system -if (defined($ENV{'KDOC_WERROR'})) { - $Werror = "$ENV{'KDOC_WERROR'}"; -} -# other environment variables are converted to command-line -# arguments in cmd_checkdoc in the build system - -# Generated docbook code is inserted in a template at a point where -# docbook v3.1 requires a non-zero sequence of RefEntry's; see: -# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html -# We keep track of number of generated entries and generate a dummy -# if needs be to ensure the expanded template can be postprocessed -# into html. -my $section_counter = 0; - -my $lineprefix=""; - -# Parser states -use constant { - STATE_NORMAL => 0, # normal code - STATE_NAME => 1, # looking for function name - STATE_BODY_MAYBE => 2, # body - or maybe more description - STATE_BODY => 3, # the body of the comment - STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line - STATE_PROTO => 5, # scanning prototype - STATE_DOCBLOCK => 6, # documentation block - STATE_INLINE => 7, # gathering doc outside main block -}; -my $state; -my $leading_space; - -# Inline documentation state -use constant { - STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE) - STATE_INLINE_NAME => 1, # looking for member name (@foo:) - STATE_INLINE_TEXT => 2, # looking for member documentation - STATE_INLINE_END => 3, # done - STATE_INLINE_ERROR => 4, # error - Comment without header was found. - # Spit a warning as it's not - # proper kernel-doc and ignore the rest. -}; -my $inline_doc_state; - -#declaration types: can be -# 'function', 'struct', 'union', 'enum', 'typedef' -my $decl_type; - -# Name of the kernel-doc identifier for non-DOC markups -my $identifier; - -my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. -my $doc_end = '\*/'; -my $doc_com = '\s*\*\s*'; -my $doc_com_body = '\s*\* ?'; -my $doc_decl = $doc_com . '(\w+)'; -# @params and a strictly limited set of supported section names -# Specifically: -# Match @word: -# @...: -# @{section-name}: -# while trying to not match literal block starts like "example::" -# -my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$'; -my $doc_content = $doc_com_body . '(.*)'; -my $doc_block = $doc_com . 'DOC:\s*(.*)?'; -my $doc_inline_start = '^\s*/\*\*\s*$'; -my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)'; -my $doc_inline_end = '^\s*\*/\s*$'; -my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; -my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; -my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*;'; -my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)}; -my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i; - -my %parameterdescs; -my %parameterdesc_start_lines; -my @parameterlist; -my %sections; -my @sectionlist; -my %section_start_lines; -my $sectcheck; -my $struct_actual; - -my $contents = ""; -my $new_start_line = 0; - -# the canonical section names. see also $doc_sect above. -my $section_default = "Description"; # default section -my $section_intro = "Introduction"; -my $section = $section_default; -my $section_context = "Context"; -my $section_return = "Return"; - -my $undescribed = "-- undescribed --"; - -reset_state(); - -while ($ARGV[0] =~ m/^--?(.*)/) { - my $cmd = $1; - shift @ARGV; - if ($cmd eq "man") { - $output_mode = "man"; - @highlights = @highlights_man; - $blankline = $blankline_man; - } elsif ($cmd eq "rst") { - $output_mode = "rst"; - @highlights = @highlights_rst; - $blankline = $blankline_rst; - } elsif ($cmd eq "none") { - $output_mode = "none"; - } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document - $modulename = shift @ARGV; - } elsif ($cmd eq "function") { # to only output specific functions - $output_selection = OUTPUT_INCLUDE; - $function = shift @ARGV; - $function_table{$function} = 1; - } elsif ($cmd eq "nosymbol") { # Exclude specific symbols - my $symbol = shift @ARGV; - $nosymbol_table{$symbol} = 1; - } elsif ($cmd eq "export") { # only exported symbols - $output_selection = OUTPUT_EXPORTED; - %function_table = (); - } elsif ($cmd eq "internal") { # only non-exported symbols - $output_selection = OUTPUT_INTERNAL; - %function_table = (); - } elsif ($cmd eq "export-file") { - my $file = shift @ARGV; - push(@export_file_list, $file); - } elsif ($cmd eq "v") { - $verbose = 1; - } elsif ($cmd eq "Werror") { - $Werror = 1; - } elsif ($cmd eq "Wreturn") { - $Wreturn = 1; - } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") { - $Wshort_desc = 1; - } elsif ($cmd eq "Wall") { - $Wreturn = 1; - $Wshort_desc = 1; - } elsif (($cmd eq "h") || ($cmd eq "help")) { - pod2usage(-exitval => 0, -verbose => 2); - } elsif ($cmd eq 'no-doc-sections') { - $no_doc_sections = 1; - } elsif ($cmd eq 'enable-lineno') { - $enable_lineno = 1; - } elsif ($cmd eq 'show-not-found') { - $show_not_found = 1; # A no-op but don't fail - } else { - # Unknown argument - pod2usage( - -message => "Argument unknown!\n", - -exitval => 1, - -verbose => 99, - -sections => 'SYNOPSIS', - -output => \*STDERR, - ); - } - if ($#ARGV < 0){ - pod2usage( - -message => "FILE argument missing\n", - -exitval => 1, - -verbose => 99, - -sections => 'SYNOPSIS', - -output => \*STDERR, - ); - } -} - -# continue execution near EOF; - -sub findprog($) -{ - foreach(split(/:/, $ENV{PATH})) { - return "$_/$_[0]" if(-x "$_/$_[0]"); - } -} - -# get kernel version from env -sub get_kernel_version() { - my $version = 'unknown kernel version'; - - if (defined($ENV{'KERNELVERSION'})) { - $version = $ENV{'KERNELVERSION'}; - } - return $version; -} - -# -sub print_lineno { - my $lineno = shift; - if ($enable_lineno && defined($lineno)) { - print ".. LINENO " . $lineno . "\n"; - } -} - -sub emit_warning { - my $location = shift; - my $msg = shift; - print STDERR "$location: warning: $msg"; - ++$warnings; -} -## -# dumps section contents to arrays/hashes intended for that purpose. -# -sub dump_section { - my $file = shift; - my $name = shift; - my $contents = join "\n", @_; - - if ($name =~ m/$type_param/) { - $name = $1; - $parameterdescs{$name} = $contents; - $sectcheck = $sectcheck . $name . " "; - $parameterdesc_start_lines{$name} = $new_start_line; - $new_start_line = 0; - } elsif ($name eq "@\.\.\.") { - $name = "..."; - $parameterdescs{$name} = $contents; - $sectcheck = $sectcheck . $name . " "; - $parameterdesc_start_lines{$name} = $new_start_line; - $new_start_line = 0; - } else { - if (defined($sections{$name}) && ($sections{$name} ne "")) { - # Only warn on user specified duplicate section names. - if ($name ne $section_default) { - emit_warning("${file}:$.", "duplicate section name '$name'\n"); - } - $sections{$name} .= $contents; - } else { - $sections{$name} = $contents; - push @sectionlist, $name; - $section_start_lines{$name} = $new_start_line; - $new_start_line = 0; - } - } -} - -## -# dump DOC: section after checking that it should go out -# -sub dump_doc_section { - my $file = shift; - my $name = shift; - my $contents = join "\n", @_; - - if ($no_doc_sections) { - return; - } - - return if (defined($nosymbol_table{$name})); - - if (($output_selection == OUTPUT_ALL) || - (($output_selection == OUTPUT_INCLUDE) && - defined($function_table{$name}))) - { - dump_section($file, $name, $contents); - output_blockhead({'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'module' => $modulename, - 'content-only' => ($output_selection != OUTPUT_ALL), }); - } -} - -## -# output function -# -# parameterdescs, a hash. -# function => "function name" -# parameterlist => @list of parameters -# parameterdescs => %parameter descriptions -# sectionlist => @list of sections -# sections => %section descriptions -# - -sub output_highlight { - my $contents = join "\n",@_; - my $line; - -# DEBUG -# if (!defined $contents) { -# use Carp; -# confess "output_highlight got called with no args?\n"; -# } - -# print STDERR "contents b4:$contents\n"; - eval $dohighlight; - die $@ if $@; -# print STDERR "contents af:$contents\n"; - - foreach $line (split "\n", $contents) { - if (! $output_preformatted) { - $line =~ s/^\s*//; - } - if ($line eq ""){ - if (! $output_preformatted) { - print $lineprefix, $blankline; - } - } else { - if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { - print "\\&$line"; - } else { - print $lineprefix, $line; - } - } - print "\n"; - } -} - -## -# output function in man -sub output_function_man(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - my $func_macro = $args{'func_macro'}; - my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty - - print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; - - print ".SH NAME\n"; - print $args{'function'} . " \\- " . $args{'purpose'} . "\n"; - - print ".SH SYNOPSIS\n"; - if ($args{'functiontype'} ne "") { - print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n"; - } else { - print ".B \"" . $args{'function'} . "\n"; - } - $count = 0; - my $parenth = "("; - my $post = ","; - foreach my $parameter (@{$args{'parameterlist'}}) { - if ($count == $#{$args{'parameterlist'}}) { - $post = ");"; - } - $type = $args{'parametertypes'}{$parameter}; - if ($type =~ m/$function_pointer/) { - # pointer-to-function - print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n"; - } else { - $type =~ s/([^\*])$/$1 /; - print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n"; - } - $count++; - $parenth = ""; - } - - $paramcount = $#{$args{'parameterlist'}}; # -1 is empty - if ($paramcount >= 0) { - print ".SH ARGUMENTS\n"; - } - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - print ".IP \"" . $parameter . "\" 12\n"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - } - foreach $section (@{$args{'sectionlist'}}) { - print ".SH \"", uc $section, "\"\n"; - output_highlight($args{'sections'}{$section}); - } -} - -## -# output enum in man -sub output_enum_man(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - - print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; - - print ".SH NAME\n"; - print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n"; - - print ".SH SYNOPSIS\n"; - print "enum " . $args{'enum'} . " {\n"; - $count = 0; - foreach my $parameter (@{$args{'parameterlist'}}) { - print ".br\n.BI \" $parameter\"\n"; - if ($count == $#{$args{'parameterlist'}}) { - print "\n};\n"; - last; - } else { - print ", \n.br\n"; - } - $count++; - } - - print ".SH Constants\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - print ".IP \"" . $parameter . "\" 12\n"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - } - foreach $section (@{$args{'sectionlist'}}) { - print ".SH \"$section\"\n"; - output_highlight($args{'sections'}{$section}); - } -} - -## -# output struct in man -sub output_struct_man(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - - print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n"; - - print ".SH NAME\n"; - print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n"; - - my $declaration = $args{'definition'}; - $declaration =~ s/\t/ /g; - $declaration =~ s/\n/"\n.br\n.BI \"/g; - print ".SH SYNOPSIS\n"; - print $args{'type'} . " " . $args{'struct'} . " {\n.br\n"; - print ".BI \"$declaration\n};\n.br\n\n"; - - print ".SH Members\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - print ".IP \"" . $parameter . "\" 12\n"; - output_highlight($args{'parameterdescs'}{$parameter_name}); - } - foreach $section (@{$args{'sectionlist'}}) { - print ".SH \"$section\"\n"; - output_highlight($args{'sections'}{$section}); - } -} - -## -# output typedef in man -sub output_typedef_man(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - - print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; - - print ".SH NAME\n"; - print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n"; - - foreach $section (@{$args{'sectionlist'}}) { - print ".SH \"$section\"\n"; - output_highlight($args{'sections'}{$section}); - } -} - -sub output_blockhead_man(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $count; - - print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; - - foreach $section (@{$args{'sectionlist'}}) { - print ".SH \"$section\"\n"; - output_highlight($args{'sections'}{$section}); - } -} - -## -# output in restructured text -# - -# -# This could use some work; it's used to output the DOC: sections, and -# starts by putting out the name of the doc section itself, but that tends -# to duplicate a header already in the template file. -# -sub output_blockhead_rst(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - - foreach $section (@{$args{'sectionlist'}}) { - next if (defined($nosymbol_table{$section})); - - if ($output_selection != OUTPUT_INCLUDE) { - print ".. _$section:\n\n"; - print "**$section**\n\n"; - } - print_lineno($section_start_lines{$section}); - output_highlight_rst($args{'sections'}{$section}); - print "\n"; - } -} - -# -# Apply the RST highlights to a sub-block of text. -# -sub highlight_block($) { - # The dohighlight kludge requires the text be called $contents - my $contents = shift; - eval $dohighlight; - die $@ if $@; - return $contents; -} - -# -# Regexes used only here. -# -my $sphinx_literal = '^[^.].*::$'; -my $sphinx_cblock = '^\.\.\ +code-block::'; - -sub output_highlight_rst { - my $input = join "\n",@_; - my $output = ""; - my $line; - my $in_literal = 0; - my $litprefix; - my $block = ""; - - foreach $line (split "\n",$input) { - # - # If we're in a literal block, see if we should drop out - # of it. Otherwise pass the line straight through unmunged. - # - if ($in_literal) { - if (! ($line =~ /^\s*$/)) { - # - # If this is the first non-blank line in a literal - # block we need to figure out what the proper indent is. - # - if ($litprefix eq "") { - $line =~ /^(\s*)/; - $litprefix = '^' . $1; - $output .= $line . "\n"; - } elsif (! ($line =~ /$litprefix/)) { - $in_literal = 0; - } else { - $output .= $line . "\n"; - } - } else { - $output .= $line . "\n"; - } - } - # - # Not in a literal block (or just dropped out) - # - if (! $in_literal) { - $block .= $line . "\n"; - if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { - $in_literal = 1; - $litprefix = ""; - $output .= highlight_block($block); - $block = "" - } - } - } - - if ($block) { - $output .= highlight_block($block); - } - - $output =~ s/^\n+//g; - $output =~ s/\n+$//g; - - foreach $line (split "\n", $output) { - print $lineprefix . $line . "\n"; - } -} - -sub output_function_rst(%) { - my %args = %{$_[0]}; - my ($parameter, $section); - my $oldprefix = $lineprefix; - - my $signature = ""; - my $func_macro = $args{'func_macro'}; - my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty - - if ($func_macro) { - $signature = $args{'function'}; - } else { - if ($args{'functiontype'}) { - $signature = $args{'functiontype'} . " "; - } - $signature .= $args{'function'} . " ("; - } - - my $count = 0; - foreach my $parameter (@{$args{'parameterlist'}}) { - if ($count ne 0) { - $signature .= ", "; - } - $count++; - $type = $args{'parametertypes'}{$parameter}; - - if ($type =~ m/$function_pointer/) { - # pointer-to-function - $signature .= $1 . $parameter . ") (" . $2 . ")"; - } else { - $signature .= $type; - } - } - - if (!$func_macro) { - $signature .= ")"; - } - - if ($args{'typedef'} || $args{'functiontype'} eq "") { - print ".. c:macro:: ". $args{'function'} . "\n\n"; - - if ($args{'typedef'}) { - print_lineno($declaration_start_line); - print " **Typedef**: "; - $lineprefix = ""; - output_highlight_rst($args{'purpose'}); - print "\n\n**Syntax**\n\n"; - print " ``$signature``\n\n"; - } else { - print "``$signature``\n\n"; - } - } else { - print ".. c:function:: $signature\n\n"; - } - - if (!$args{'typedef'}) { - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; - } - - # - # Put our descriptive text into a container (thus an HTML
) to help - # set the function prototypes apart. - # - $lineprefix = " "; - if ($paramcount >= 0) { - print ".. container:: kernelindent\n\n"; - print $lineprefix . "**Parameters**\n\n"; - } - foreach $parameter (@{$args{'parameterlist'}}) { - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - $type = $args{'parametertypes'}{$parameter}; - - if ($type ne "") { - print $lineprefix . "``$type``\n"; - } else { - print $lineprefix . "``$parameter``\n"; - } - - print_lineno($parameterdesc_start_lines{$parameter_name}); - - $lineprefix = " "; - if (defined($args{'parameterdescs'}{$parameter_name}) && - $args{'parameterdescs'}{$parameter_name} ne $undescribed) { - output_highlight_rst($args{'parameterdescs'}{$parameter_name}); - } else { - print $lineprefix . "*undescribed*\n"; - } - $lineprefix = " "; - print "\n"; - } - - output_section_rst(@_); - $lineprefix = $oldprefix; -} - -sub output_section_rst(%) { - my %args = %{$_[0]}; - my $section; - my $oldprefix = $lineprefix; - - foreach $section (@{$args{'sectionlist'}}) { - print $lineprefix . "**$section**\n\n"; - print_lineno($section_start_lines{$section}); - output_highlight_rst($args{'sections'}{$section}); - print "\n"; - } - print "\n"; -} - -sub output_enum_rst(%) { - my %args = %{$_[0]}; - my ($parameter); - my $oldprefix = $lineprefix; - my $count; - my $outer; - - my $name = $args{'enum'}; - print "\n\n.. c:enum:: " . $name . "\n\n"; - - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; - - print ".. container:: kernelindent\n\n"; - $outer = $lineprefix . " "; - $lineprefix = $outer . " "; - print $outer . "**Constants**\n\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - print $outer . "``$parameter``\n"; - - if ($args{'parameterdescs'}{$parameter} ne $undescribed) { - output_highlight_rst($args{'parameterdescs'}{$parameter}); - } else { - print $lineprefix . "*undescribed*\n"; - } - print "\n"; - } - print "\n"; - $lineprefix = $oldprefix; - output_section_rst(@_); -} - -sub output_typedef_rst(%) { - my %args = %{$_[0]}; - my ($parameter); - my $oldprefix = $lineprefix; - my $name; - - $name = $args{'typedef'}; - - print "\n\n.. c:type:: " . $name . "\n\n"; - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; - - $lineprefix = $oldprefix; - output_section_rst(@_); -} - -sub output_struct_rst(%) { - my %args = %{$_[0]}; - my ($parameter); - my $oldprefix = $lineprefix; - - my $name = $args{'struct'}; - if ($args{'type'} eq 'union') { - print "\n\n.. c:union:: " . $name . "\n\n"; - } else { - print "\n\n.. c:struct:: " . $name . "\n\n"; - } - - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; - - print ".. container:: kernelindent\n\n"; - print $lineprefix . "**Definition**::\n\n"; - my $declaration = $args{'definition'}; - $lineprefix = $lineprefix . " "; - $declaration =~ s/\t/$lineprefix/g; - print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n"; - - $lineprefix = " "; - print $lineprefix . "**Members**\n\n"; - foreach $parameter (@{$args{'parameterlist'}}) { - ($parameter =~ /^#/) && next; - - my $parameter_name = $parameter; - $parameter_name =~ s/\[.*//; - - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; - $type = $args{'parametertypes'}{$parameter}; - print_lineno($parameterdesc_start_lines{$parameter_name}); - print $lineprefix . "``" . $parameter . "``\n"; - $lineprefix = " "; - output_highlight_rst($args{'parameterdescs'}{$parameter_name}); - $lineprefix = " "; - print "\n"; - } - print "\n"; - - $lineprefix = $oldprefix; - output_section_rst(@_); -} - -## none mode output functions - -sub output_function_none(%) { -} - -sub output_enum_none(%) { -} - -sub output_typedef_none(%) { -} - -sub output_struct_none(%) { -} - -sub output_blockhead_none(%) { -} - -## -# generic output function for all types (function, struct/union, typedef, enum); -# calls the generated, variable output_ function name based on -# functype and output_mode -sub output_declaration { - no strict 'refs'; - my $name = shift; - my $functype = shift; - my $func = "output_${functype}_$output_mode"; - - return if (defined($nosymbol_table{$name})); - - if (($output_selection == OUTPUT_ALL) || - (($output_selection == OUTPUT_INCLUDE || - $output_selection == OUTPUT_EXPORTED) && - defined($function_table{$name})) || - ($output_selection == OUTPUT_INTERNAL && - !($functype eq "function" && defined($function_table{$name})))) - { - &$func(@_); - $section_counter++; - } -} - -## -# generic output function - calls the right one based on current output mode. -sub output_blockhead { - no strict 'refs'; - my $func = "output_blockhead_" . $output_mode; - &$func(@_); - $section_counter++; -} - -## -# takes a declaration (struct, union, enum, typedef) and -# invokes the right handler. NOT called for functions. -sub dump_declaration($$) { - no strict 'refs'; - my ($prototype, $file) = @_; - my $func = "dump_" . $decl_type; - &$func(@_); -} - -sub dump_union($$) { - dump_struct(@_); -} - -sub dump_struct($$) { - my $x = shift; - my $file = shift; - my $decl_type; - my $members; - my $type = qr{struct|union}; - # For capturing struct/union definition body, i.e. "{members*}qualifiers*" - my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned}; - my $definition_body = qr{\{(.*)\}\s*$qualifiers*}; - my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;}; - - if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { - $decl_type = $1; - $declaration_name = $2; - $members = $3; - } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) { - $decl_type = $1; - $declaration_name = $3; - $members = $2; - } - - if ($members) { - if ($identifier ne $declaration_name) { - emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n"); - return; - } - - # ignore members marked private: - $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; - $members =~ s/\/\*\s*private:.*//gosi; - # strip comments: - $members =~ s/\/\*.*?\*\///gos; - # strip attributes - $members =~ s/\s*$attribute/ /gi; - $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; - $members =~ s/\s*__counted_by\s*\([^;]*\)/ /gos; - $members =~ s/\s*__counted_by_(le|be)\s*\([^;]*\)/ /gos; - $members =~ s/\s*__packed\s*/ /gos; - $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; - $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; - $members =~ s/\s*____cacheline_aligned/ /gos; - # unwrap struct_group(): - # - first eat non-declaration parameters and rewrite for final match - # - then remove macro, outer parens, and trailing semicolon - $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos; - $members =~ s/\bstruct_group_attr\s*\(([^,]*,){2}/STRUCT_GROUP(/gos; - $members =~ s/\bstruct_group_tagged\s*\(([^,]*),([^,]*),/struct $1 $2; STRUCT_GROUP(/gos; - $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos; - $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos; - - my $args = qr{([^,)]+)}; - # replace DECLARE_BITMAP - $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; - $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos; - $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; - # replace DECLARE_HASHTABLE - $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos; - # replace DECLARE_KFIFO - $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos; - # replace DECLARE_KFIFO_PTR - $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos; - # replace DECLARE_FLEX_ARRAY - $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos; - #replace DEFINE_DMA_UNMAP_ADDR - $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos; - #replace DEFINE_DMA_UNMAP_LEN - $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos; - my $declaration = $members; - - # Split nested struct/union elements as newer ones - while ($members =~ m/$struct_members/) { - my $newmember; - my $maintype = $1; - my $ids = $4; - my $content = $3; - foreach my $id(split /,/, $ids) { - $newmember .= "$maintype $id; "; - - $id =~ s/[:\[].*//; - $id =~ s/^\s*\**(\S+)\s*/$1/; - foreach my $arg (split /;/, $content) { - next if ($arg =~ m/^\s*$/); - if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) { - # pointer-to-function - my $type = $1; - my $name = $2; - my $extra = $3; - next if (!$name); - if ($id =~ m/^\s*$/) { - # anonymous struct/union - $newmember .= "$type$name$extra; "; - } else { - $newmember .= "$type$id.$name$extra; "; - } - } else { - my $type; - my $names; - $arg =~ s/^\s+//; - $arg =~ s/\s+$//; - # Handle bitmaps - $arg =~ s/:\s*\d+\s*//g; - # Handle arrays - $arg =~ s/\[.*\]//g; - # The type may have multiple words, - # and multiple IDs can be defined, like: - # const struct foo, *bar, foobar - # So, we remove spaces when parsing the - # names, in order to match just names - # and commas for the names - $arg =~ s/\s*,\s*/,/g; - if ($arg =~ m/(.*)\s+([\S+,]+)/) { - $type = $1; - $names = $2; - } else { - $newmember .= "$arg; "; - next; - } - foreach my $name (split /,/, $names) { - $name =~ s/^\s*\**(\S+)\s*/$1/; - next if (($name =~ m/^\s*$/)); - if ($id =~ m/^\s*$/) { - # anonymous struct/union - $newmember .= "$type $name; "; - } else { - $newmember .= "$type $id.$name; "; - } - } - } - } - } - $members =~ s/$struct_members/$newmember/; - } - - # Ignore other nested elements, like enums - $members =~ s/(\{[^\{\}]*\})//g; - - create_parameterlist($members, ';', $file, $declaration_name); - check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); - - # Adjust declaration for better display - $declaration =~ s/([\{;])/$1\n/g; - $declaration =~ s/\}\s+;/};/g; - # Better handle inlined enums - do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/); - - my @def_args = split /\n/, $declaration; - my $level = 1; - $declaration = ""; - foreach my $clause (@def_args) { - $clause =~ s/^\s+//; - $clause =~ s/\s+$//; - $clause =~ s/\s+/ /; - next if (!$clause); - $level-- if ($clause =~ m/(\})/ && $level > 1); - if (!($clause =~ m/^\s*#/)) { - $declaration .= "\t" x $level; - } - $declaration .= "\t" . $clause . "\n"; - $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/)); - } - output_declaration($declaration_name, - 'struct', - {'struct' => $declaration_name, - 'module' => $modulename, - 'definition' => $declaration, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'parametertypes' => \%parametertypes, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose, - 'type' => $decl_type - }); - } else { - print STDERR "${file}:$.: error: Cannot parse struct or union!\n"; - ++$errors; - } -} - - -sub show_warnings($$) { - my $functype = shift; - my $name = shift; - - return 0 if (defined($nosymbol_table{$name})); - - return 1 if ($output_selection == OUTPUT_ALL); - - if ($output_selection == OUTPUT_EXPORTED) { - if (defined($function_table{$name})) { - return 1; - } else { - return 0; - } - } - if ($output_selection == OUTPUT_INTERNAL) { - if (!($functype eq "function" && defined($function_table{$name}))) { - return 1; - } else { - return 0; - } - } - if ($output_selection == OUTPUT_INCLUDE) { - if (defined($function_table{$name})) { - return 1; - } else { - return 0; - } - } - die("Please add the new output type at show_warnings()"); -} - -sub dump_enum($$) { - my $x = shift; - my $file = shift; - my $members; - - # ignore members marked private: - $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; - $x =~ s/\/\*\s*private:.*}/}/gosi; - - $x =~ s@/\*.*?\*/@@gos; # strip comments. - # strip #define macros inside enums - $x =~ s@#\s*((define|ifdef|if)\s+|endif)[^;]*;@@gos; - - if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) { - $declaration_name = $2; - $members = $1; - } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { - $declaration_name = $1; - $members = $2; - } - - if ($members) { - if ($identifier ne $declaration_name) { - if ($identifier eq "") { - emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n"); - } else { - emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"); - } - return; - } - $declaration_name = "(anonymous)" if ($declaration_name eq ""); - - my %_members; - - $members =~ s/\s+$//; - $members =~ s/\([^;]*?[\)]//g; - - foreach my $arg (split ',', $members) { - $arg =~ s/^\s*(\w+).*/$1/; - push @parameterlist, $arg; - if (!$parameterdescs{$arg}) { - $parameterdescs{$arg} = $undescribed; - if (show_warnings("enum", $declaration_name)) { - emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n"); - } - } - $_members{$arg} = 1; - } - - while (my ($k, $v) = each %parameterdescs) { - if (!exists($_members{$k})) { - if (show_warnings("enum", $declaration_name)) { - emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n"); - } - } - } - - output_declaration($declaration_name, - 'enum', - {'enum' => $declaration_name, - 'module' => $modulename, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose - }); - } else { - print STDERR "${file}:$.: error: Cannot parse enum!\n"; - ++$errors; - } -} - -my $typedef_type = qr { ((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s* }x; -my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; -my $typedef_args = qr { \s*\((.*)\); }x; - -my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x; -my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x; - -sub dump_typedef($$) { - my $x = shift; - my $file = shift; - - $x =~ s@/\*.*?\*/@@gos; # strip comments. - - # Parse function typedef prototypes - if ($x =~ $typedef1 || $x =~ $typedef2) { - $return_type = $1; - $declaration_name = $2; - my $args = $3; - $return_type =~ s/^\s+//; - - if ($identifier ne $declaration_name) { - emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"); - return; - } - - create_parameterlist($args, ',', $file, $declaration_name); - - output_declaration($declaration_name, - 'function', - {'function' => $declaration_name, - 'typedef' => 1, - 'module' => $modulename, - 'functiontype' => $return_type, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'parametertypes' => \%parametertypes, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose - }); - return; - } - - while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { - $x =~ s/\(*.\)\s*;$/;/; - $x =~ s/\[*.\]\s*;$/;/; - } - - if ($x =~ /typedef.*\s+(\w+)\s*;/) { - $declaration_name = $1; - - if ($identifier ne $declaration_name) { - emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"); - return; - } - - output_declaration($declaration_name, - 'typedef', - {'typedef' => $declaration_name, - 'module' => $modulename, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose - }); - } else { - print STDERR "${file}:$.: error: Cannot parse typedef!\n"; - ++$errors; - } -} - -sub save_struct_actual($) { - my $actual = shift; - - # strip all spaces from the actual param so that it looks like one string item - $actual =~ s/\s*//g; - $struct_actual = $struct_actual . $actual . " "; -} - -sub create_parameterlist($$$$) { - my $args = shift; - my $splitter = shift; - my $file = shift; - my $declaration_name = shift; - my $type; - my $param; - - # temporarily replace commas inside function pointer definition - my $arg_expr = qr{\([^\),]+}; - while ($args =~ /$arg_expr,/) { - $args =~ s/($arg_expr),/$1#/g; - } - - foreach my $arg (split($splitter, $args)) { - # strip comments - $arg =~ s/\/\*.*\*\///; - # ignore argument attributes - $arg =~ s/\sPOS0?\s/ /; - # strip leading/trailing spaces - $arg =~ s/^\s*//; - $arg =~ s/\s*$//; - $arg =~ s/\s+/ /; - - if ($arg =~ /^#/) { - # Treat preprocessor directive as a typeless variable just to fill - # corresponding data structures "correctly". Catch it later in - # output_* subs. - push_parameter($arg, "", "", $file); - } elsif ($arg =~ m/\(.+\)\s*\(/) { - # pointer-to-function - $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/; - $param = $1; - $type = $arg; - $type =~ s/([^\(]+\(\*?)\s*$param/$1/; - save_struct_actual($param); - push_parameter($param, $type, $arg, $file, $declaration_name); - } elsif ($arg =~ m/\(.+\)\s*\[/) { - # array-of-pointers - $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/; - $param = $1; - $type = $arg; - $type =~ s/([^\(]+\(\*?)\s*$param/$1/; - save_struct_actual($param); - push_parameter($param, $type, $arg, $file, $declaration_name); - } elsif ($arg) { - $arg =~ s/\s*:\s*/:/g; - $arg =~ s/\s*\[/\[/g; - - my @args = split('\s*,\s*', $arg); - if ($args[0] =~ m/\*/) { - $args[0] =~ s/(\*+)\s*/ $1/; - } - - my @first_arg; - if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) { - shift @args; - push(@first_arg, split('\s+', $1)); - push(@first_arg, $2); - } else { - @first_arg = split('\s+', shift @args); - } - - unshift(@args, pop @first_arg); - $type = join " ", @first_arg; - - foreach $param (@args) { - if ($param =~ m/^(\*+)\s*(.*)/) { - save_struct_actual($2); - - push_parameter($2, "$type $1", $arg, $file, $declaration_name); - } elsif ($param =~ m/(.*?):(\w+)/) { - if ($type ne "") { # skip unnamed bit-fields - save_struct_actual($1); - push_parameter($1, "$type:$2", $arg, $file, $declaration_name) - } - } else { - save_struct_actual($param); - push_parameter($param, $type, $arg, $file, $declaration_name); - } - } - } - } -} - -sub push_parameter($$$$$) { - my $param = shift; - my $type = shift; - my $org_arg = shift; - my $file = shift; - my $declaration_name = shift; - - if (($anon_struct_union == 1) && ($type eq "") && - ($param eq "}")) { - return; # ignore the ending }; from anon. struct/union - } - - $anon_struct_union = 0; - $param =~ s/[\[\)].*//; - - if ($type eq "" && $param =~ /\.\.\.$/) - { - if (!$param =~ /\w\.\.\.$/) { - # handles unnamed variable parameters - $param = "..."; - } elsif ($param =~ /\w\.\.\.$/) { - # for named variable parameters of the form `x...`, remove the dots - $param =~ s/\.\.\.$//; - } - if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { - $parameterdescs{$param} = "variable arguments"; - } - } - elsif ($type eq "" && ($param eq "" or $param eq "void")) - { - $param="void"; - $parameterdescs{void} = "no arguments"; - } - elsif ($type eq "" && ($param eq "struct" or $param eq "union")) - # handle unnamed (anonymous) union or struct: - { - $type = $param; - $param = "{unnamed_" . $param . "}"; - $parameterdescs{$param} = "anonymous\n"; - $anon_struct_union = 1; - } - elsif ($param =~ "__cacheline_group" ) - # handle cache group enforcing variables: they do not need be described in header files - { - return; # ignore __cacheline_group_begin and __cacheline_group_end - } - - # warn if parameter has no description - # (but ignore ones starting with # as these are not parameters - # but inline preprocessor statements); - # Note: It will also ignore void params and unnamed structs/unions - if (!defined $parameterdescs{$param} && $param !~ /^#/) { - $parameterdescs{$param} = $undescribed; - - if (show_warnings($type, $declaration_name) && $param !~ /\./) { - emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n"); - } - } - - # strip spaces from $param so that it is one continuous string - # on @parameterlist; - # this fixes a problem where check_sections() cannot find - # a parameter like "addr[6 + 2]" because it actually appears - # as "addr[6", "+", "2]" on the parameter list; - # but it's better to maintain the param string unchanged for output, - # so just weaken the string compare in check_sections() to ignore - # "[blah" in a parameter string; - ###$param =~ s/\s*//g; - push @parameterlist, $param; - $org_arg =~ s/\s\s+/ /g; - $parametertypes{$param} = $org_arg; -} - -sub check_sections($$$$$) { - my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_; - my @sects = split ' ', $sectcheck; - my @prms = split ' ', $prmscheck; - my $err; - my ($px, $sx); - my $prm_clean; # strip trailing "[array size]" and/or beginning "*" - - foreach $sx (0 .. $#sects) { - $err = 1; - foreach $px (0 .. $#prms) { - $prm_clean = $prms[$px]; - $prm_clean =~ s/\[.*\]//; - $prm_clean =~ s/$attribute//i; - # ignore array size in a parameter string; - # however, the original param string may contain - # spaces, e.g.: addr[6 + 2] - # and this appears in @prms as "addr[6" since the - # parameter list is split at spaces; - # hence just ignore "[..." for the sections check; - $prm_clean =~ s/\[.*//; - - ##$prm_clean =~ s/^\**//; - if ($prm_clean eq $sects[$sx]) { - $err = 0; - last; - } - } - if ($err) { - if ($decl_type eq "function") { - emit_warning("${file}:$.", - "Excess function parameter " . - "'$sects[$sx]' " . - "description in '$decl_name'\n"); - } elsif (($decl_type eq "struct") or - ($decl_type eq "union")) { - emit_warning("${file}:$.", - "Excess $decl_type member " . - "'$sects[$sx]' " . - "description in '$decl_name'\n"); - } - } - } -} - -## -# Checks the section describing the return value of a function. -sub check_return_section { - my $file = shift; - my $declaration_name = shift; - my $return_type = shift; - - # Ignore an empty return type (It's a macro) - # Ignore functions with a "void" return type. (But don't ignore "void *") - if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { - return; - } - - if (!defined($sections{$section_return}) || - $sections{$section_return} eq "") - { - emit_warning("${file}:$.", - "No description found for return value of " . - "'$declaration_name'\n"); - } -} - -## -# takes a function prototype and the name of the current file being -# processed and spits out all the details stored in the global -# arrays/hashes. -sub dump_function($$) { - my $prototype = shift; - my $file = shift; - my $func_macro = 0; - - print_lineno($new_start_line); - - $prototype =~ s/^static +//; - $prototype =~ s/^extern +//; - $prototype =~ s/^asmlinkage +//; - $prototype =~ s/^inline +//; - $prototype =~ s/^__inline__ +//; - $prototype =~ s/^__inline +//; - $prototype =~ s/^__always_inline +//; - $prototype =~ s/^noinline +//; - $prototype =~ s/^__FORTIFY_INLINE +//; - $prototype =~ s/__init +//; - $prototype =~ s/__init_or_module +//; - $prototype =~ s/__deprecated +//; - $prototype =~ s/__flatten +//; - $prototype =~ s/__meminit +//; - $prototype =~ s/__must_check +//; - $prototype =~ s/__weak +//; - $prototype =~ s/__sched +//; - $prototype =~ s/_noprof//; - $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; - $prototype =~ s/__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//; - $prototype =~ s/__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +//; - $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)/$1, $2/; - my $define = $prototype =~ s/^#\s*define\s+//; #ak added - $prototype =~ s/__attribute_const__ +//; - $prototype =~ s/__attribute__\s*\(\( - (?: - [\w\s]++ # attribute name - (?:\([^)]*+\))? # attribute arguments - \s*+,? # optional comma at the end - )+ - \)\)\s+//x; - - # Yes, this truly is vile. We are looking for: - # 1. Return type (may be nothing if we're looking at a macro) - # 2. Function name - # 3. Function parameters. - # - # All the while we have to watch out for function pointer parameters - # (which IIRC is what the two sections are for), C types (these - # regexps don't even start to express all the possibilities), and - # so on. - # - # If you mess with these regexps, it's a good idea to check that - # the following functions' documentation still comes out right: - # - parport_register_device (function pointer parameters) - # - atomic_set (macro) - # - pci_match_device, __copy_to_user (long return type) - my $name = qr{[a-zA-Z0-9_~:]+}; - my $prototype_end1 = qr{[^\(]*}; - my $prototype_end2 = qr{[^\{]*}; - my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)}; - my $type1 = qr{[\w\s]+}; - my $type2 = qr{$type1\*+}; - - if ($define && $prototype =~ m/^()($name)\s+/) { - # This is an object-like macro, it has no return type and no parameter - # list. - # Function-like macros are not allowed to have spaces between - # declaration_name and opening parenthesis (notice the \s+). - $return_type = $1; - $declaration_name = $2; - $func_macro = 1; - } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ || - $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ || - $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) { - $return_type = $1; - $declaration_name = $2; - my $args = $3; - - create_parameterlist($args, ',', $file, $declaration_name); - } else { - emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n"); - return; - } - - if ($identifier ne $declaration_name) { - emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n"); - return; - } - - my $prms = join " ", @parameterlist; - check_sections($file, $declaration_name, "function", $sectcheck, $prms); - - # This check emits a lot of warnings at the moment, because many - # functions don't have a 'Return' doc section. So until the number - # of warnings goes sufficiently down, the check is only performed in - # -Wreturn mode. - # TODO: always perform the check. - if ($Wreturn && !$func_macro) { - check_return_section($file, $declaration_name, $return_type); - } - - # The function parser can be called with a typedef parameter. - # Handle it. - if ($return_type =~ /typedef/) { - output_declaration($declaration_name, - 'function', - {'function' => $declaration_name, - 'typedef' => 1, - 'module' => $modulename, - 'functiontype' => $return_type, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'parametertypes' => \%parametertypes, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose, - 'func_macro' => $func_macro - }); - } else { - output_declaration($declaration_name, - 'function', - {'function' => $declaration_name, - 'module' => $modulename, - 'functiontype' => $return_type, - 'parameterlist' => \@parameterlist, - 'parameterdescs' => \%parameterdescs, - 'parametertypes' => \%parametertypes, - 'sectionlist' => \@sectionlist, - 'sections' => \%sections, - 'purpose' => $declaration_purpose, - 'func_macro' => $func_macro - }); - } -} - -sub reset_state { - $function = ""; - %parameterdescs = (); - %parametertypes = (); - @parameterlist = (); - %sections = (); - @sectionlist = (); - $sectcheck = ""; - $struct_actual = ""; - $prototype = ""; - - $state = STATE_NORMAL; - $inline_doc_state = STATE_INLINE_NA; -} - -sub tracepoint_munge($) { - my $file = shift; - my $tracepointname = 0; - my $tracepointargs = 0; - - if ($prototype =~ m/TRACE_EVENT\((.*?),/) { - $tracepointname = $1; - } - if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) { - $tracepointname = $1; - } - if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) { - $tracepointname = $2; - } - $tracepointname =~ s/^\s+//; #strip leading whitespace - if ($prototype =~ m/TP_PROTO\((.*?)\)/) { - $tracepointargs = $1; - } - if (($tracepointname eq 0) || ($tracepointargs eq 0)) { - emit_warning("${file}:$.", "Unrecognized tracepoint format: \n". - "$prototype\n"); - } else { - $prototype = "static inline void trace_$tracepointname($tracepointargs)"; - $identifier = "trace_$identifier"; - } -} - -sub syscall_munge() { - my $void = 0; - - $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's -## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) { - if ($prototype =~ m/SYSCALL_DEFINE0/) { - $void = 1; -## $prototype = "long sys_$1(void)"; - } - - $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name - if ($prototype =~ m/long (sys_.*?),/) { - $prototype =~ s/,/\(/; - } elsif ($void) { - $prototype =~ s/\)/\(void\)/; - } - - # now delete all of the odd-number commas in $prototype - # so that arg types & arg names don't have a comma between them - my $count = 0; - my $len = length($prototype); - if ($void) { - $len = 0; # skip the for-loop - } - for (my $ix = 0; $ix < $len; $ix++) { - if (substr($prototype, $ix, 1) eq ',') { - $count++; - if ($count % 2 == 1) { - substr($prototype, $ix, 1) = ' '; - } - } - } -} - -sub process_proto_function($$) { - my $x = shift; - my $file = shift; - - $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line - - if ($x =~ /^#/ && $x !~ /^#\s*define/) { - # do nothing - } elsif ($x =~ /([^\{]*)/) { - $prototype .= $1; - } - - if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) { - $prototype =~ s@/\*.*?\*/@@gos; # strip comments. - $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. - $prototype =~ s@^\s+@@gos; # strip leading spaces - - # Handle prototypes for function pointers like: - # int (*pcs_config)(struct foo) - $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos; - - if ($prototype =~ /SYSCALL_DEFINE/) { - syscall_munge(); - } - if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ || - $prototype =~ /DEFINE_SINGLE_EVENT/) - { - tracepoint_munge($file); - } - dump_function($prototype, $file); - reset_state(); - } -} - -sub process_proto_type($$) { - my $x = shift; - my $file = shift; - - $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. - $x =~ s@^\s+@@gos; # strip leading spaces - $x =~ s@\s+$@@gos; # strip trailing spaces - $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line - - if ($x =~ /^#/) { - # To distinguish preprocessor directive from regular declaration later. - $x .= ";"; - } - - while (1) { - if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) { - if( length $prototype ) { - $prototype .= " " - } - $prototype .= $1 . $2; - ($2 eq '{') && $brcount++; - ($2 eq '}') && $brcount--; - if (($2 eq ';') && ($brcount == 0)) { - dump_declaration($prototype, $file); - reset_state(); - last; - } - $x = $3; - } else { - $prototype .= $x; - last; - } - } -} - - -sub map_filename($) { - my $file; - my ($orig_file) = @_; - - if (defined($ENV{'SRCTREE'})) { - $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; - } else { - $file = $orig_file; - } - - return $file; -} - -sub process_export_file($) { - my ($orig_file) = @_; - my $file = map_filename($orig_file); - - if (!open(IN,"<$file")) { - print STDERR "Error: Cannot open file $file\n"; - ++$errors; - return; - } - - while () { - if (/$export_symbol/) { - next if (defined($nosymbol_table{$2})); - $function_table{$2} = 1; - } - if (/$export_symbol_ns/) { - next if (defined($nosymbol_table{$2})); - $function_table{$2} = 1; - } - } - - close(IN); -} - -# -# Parsers for the various processing states. -# -# STATE_NORMAL: looking for the /** to begin everything. -# -sub process_normal() { - if (/$doc_start/o) { - $state = STATE_NAME; # next line is always the function name - $declaration_start_line = $. + 1; - } -} - -# -# STATE_NAME: Looking for the "name - description" line -# -sub process_name($$) { - my $file = shift; - my $descr; - - if (/$doc_block/o) { - $state = STATE_DOCBLOCK; - $contents = ""; - $new_start_line = $.; - - if ( $1 eq "" ) { - $section = $section_intro; - } else { - $section = $1; - } - } elsif (/$doc_decl/o) { - $identifier = $1; - my $is_kernel_comment = 0; - my $decl_start = qr{$doc_com}; - # test for pointer declaration type, foo * bar() - desc - my $fn_type = qr{\w+\s*\*\s*}; - my $parenthesis = qr{\(\w*\)}; - my $decl_end = qr{[-:].*}; - if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) { - $identifier = $1; - } - if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { - $decl_type = $1; - $identifier = $2; - $is_kernel_comment = 1; - } - # Look for foo() or static void foo() - description; or misspelt - # identifier - elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || - /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) { - $identifier = $1; - $decl_type = 'function'; - $identifier =~ s/^define\s+//; - $is_kernel_comment = 1; - } - $identifier =~ s/\s+$//; - - $state = STATE_BODY; - # if there's no @param blocks need to set up default section - # here - $contents = ""; - $section = $section_default; - $new_start_line = $. + 1; - if (/[-:](.*)/) { - # strip leading/trailing/multiple spaces - $descr= $1; - $descr =~ s/^\s*//; - $descr =~ s/\s*$//; - $descr =~ s/\s+/ /g; - $declaration_purpose = $descr; - $state = STATE_BODY_MAYBE; - } else { - $declaration_purpose = ""; - } - - if (!$is_kernel_comment) { - emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_"); - $state = STATE_NORMAL; - } - - if (($declaration_purpose eq "") && $Wshort_desc) { - emit_warning("${file}:$.", "missing initial short description on line:\n$_"); - } - - if ($identifier eq "" && $decl_type ne "enum") { - emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_"); - $state = STATE_NORMAL; - } - - if ($verbose) { - print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n"; - } - } else { - emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n"); - $state = STATE_NORMAL; - } -} - - -# -# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. -# -sub process_body($$) { - my $file = shift; - - if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) { - dump_section($file, $section, $contents); - $section = $section_default; - $new_start_line = $.; - $contents = ""; - } - - if (/$doc_sect/i) { # case insensitive for supported section names - $newsection = $1; - $newcontents = $2; - - # map the supported section names to the canonical names - if ($newsection =~ m/^description$/i) { - $newsection = $section_default; - } elsif ($newsection =~ m/^context$/i) { - $newsection = $section_context; - } elsif ($newsection =~ m/^returns?$/i) { - $newsection = $section_return; - } elsif ($newsection =~ m/^\@return$/) { - # special: @return is a section, not a param description - $newsection = $section_return; - } - - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - } - - $state = STATE_BODY; - $contents = $newcontents; - $new_start_line = $.; - while (substr($contents, 0, 1) eq " ") { - $contents = substr($contents, 1); - } - if ($contents ne "") { - $contents .= "\n"; - } - $section = $newsection; - $leading_space = undef; - } elsif (/$doc_end/) { - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - # look for doc_com + + doc_end: - if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { - emit_warning("${file}:$.", "suspicious ending line: $_"); - } - - $prototype = ""; - $state = STATE_PROTO; - $brcount = 0; - $new_start_line = $. + 1; - } elsif (/$doc_content/) { - if ($1 eq "") { - if ($section eq $section_context) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - $new_start_line = $.; - $state = STATE_BODY; - } else { - if ($section ne $section_default) { - $state = STATE_BODY_WITH_BLANK_LINE; - } else { - $state = STATE_BODY; - } - $contents .= "\n"; - } - } elsif ($state == STATE_BODY_MAYBE) { - # Continued declaration purpose - chomp($declaration_purpose); - $declaration_purpose .= " " . $1; - $declaration_purpose =~ s/\s+/ /g; - } else { - my $cont = $1; - if ($section =~ m/^@/ || $section eq $section_context) { - if (!defined $leading_space) { - if ($cont =~ m/^(\s+)/) { - $leading_space = $1; - } else { - $leading_space = ""; - } - } - $cont =~ s/^$leading_space//; - } - $contents .= $cont . "\n"; - } - } else { - # i dont know - bad line? ignore. - emit_warning("${file}:$.", "bad line: $_"); - } -} - - -# -# STATE_PROTO: reading a function/whatever prototype. -# -sub process_proto($$) { - my $file = shift; - - if (/$doc_inline_oneline/) { - $section = $1; - $contents = $2; - if ($contents ne "") { - $contents .= "\n"; - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - } elsif (/$doc_inline_start/) { - $state = STATE_INLINE; - $inline_doc_state = STATE_INLINE_NAME; - } elsif ($decl_type eq 'function') { - process_proto_function($_, $file); - } else { - process_proto_type($_, $file); - } -} - -# -# STATE_DOCBLOCK: within a DOC: block. -# -sub process_docblock($$) { - my $file = shift; - - if (/$doc_end/) { - dump_doc_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - $function = ""; - %parameterdescs = (); - %parametertypes = (); - @parameterlist = (); - %sections = (); - @sectionlist = (); - $prototype = ""; - $state = STATE_NORMAL; - } elsif (/$doc_content/) { - if ( $1 eq "" ) { - $contents .= $blankline; - } else { - $contents .= $1 . "\n"; - } - } -} - -# -# STATE_INLINE: docbook comments within a prototype. -# -sub process_inline($$) { - my $file = shift; - - # First line (state 1) needs to be a @parameter - if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { - $section = $1; - $contents = $2; - $new_start_line = $.; - if ($contents ne "") { - while (substr($contents, 0, 1) eq " ") { - $contents = substr($contents, 1); - } - $contents .= "\n"; - } - $inline_doc_state = STATE_INLINE_TEXT; - # Documentation block end */ - } elsif (/$doc_inline_end/) { - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - $state = STATE_PROTO; - $inline_doc_state = STATE_INLINE_NA; - # Regular text - } elsif (/$doc_content/) { - if ($inline_doc_state == STATE_INLINE_TEXT) { - $contents .= $1 . "\n"; - # nuke leading blank lines - if ($contents =~ /^\s*$/) { - $contents = ""; - } - } elsif ($inline_doc_state == STATE_INLINE_NAME) { - $inline_doc_state = STATE_INLINE_ERROR; - emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_"); - } - } -} - - -sub process_file($) { - my $file; - my ($orig_file) = @_; - - $file = map_filename($orig_file); - - if (!open(IN_FILE,"<$file")) { - print STDERR "Error: Cannot open file $file\n"; - ++$errors; - return; - } - - $. = 1; - - $section_counter = 0; - while () { - while (!/^ \*/ && s/\\\s*$//) { - $_ .= ; - } - # Replace tabs by spaces - while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; - # Hand this line to the appropriate state handler - if ($state == STATE_NORMAL) { - process_normal(); - } elsif ($state == STATE_NAME) { - process_name($file, $_); - } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE || - $state == STATE_BODY_WITH_BLANK_LINE) { - process_body($file, $_); - } elsif ($state == STATE_INLINE) { # scanning for inline parameters - process_inline($file, $_); - } elsif ($state == STATE_PROTO) { - process_proto($file, $_); - } elsif ($state == STATE_DOCBLOCK) { - process_docblock($file, $_); - } - } - - # Make sure we got something interesting. - if (!$section_counter && $output_mode ne "none") { - if ($output_selection == OUTPUT_INCLUDE) { - emit_warning("${file}:1", "'$_' not found\n") - for keys %function_table; - } else { - emit_warning("${file}:1", "no structured comments found\n"); - } - } - close IN_FILE; -} - -$kernelversion = get_kernel_version(); - -# generate a sequence of code that will splice in highlighting information -# using the s// operator. -for (my $k = 0; $k < @highlights; $k++) { - my $pattern = $highlights[$k][0]; - my $result = $highlights[$k][1]; -# print STDERR "scanning pattern:$pattern, highlight:($result)\n"; - $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n"; -} - -if ($output_selection == OUTPUT_EXPORTED || - $output_selection == OUTPUT_INTERNAL) { - - push(@export_file_list, @ARGV); - - foreach (@export_file_list) { - chomp; - process_export_file($_); - } -} - -foreach (@ARGV) { - chomp; - process_file($_); -} -if ($verbose && $errors) { - print STDERR "$errors errors\n"; -} -if ($verbose && $warnings) { - print STDERR "$warnings warnings\n"; -} - -if ($Werror && $warnings) { - print STDERR "$warnings warnings as Errors\n"; - exit($warnings); -} else { - exit($output_mode eq "none" ? 0 : $errors) -} - -__END__ - -=head1 OPTIONS - -=head2 Output format selection (mutually exclusive): - -=over 8 - -=item -man - -Output troff manual page format. - -=item -rst - -Output reStructuredText format. This is the default. - -=item -none - -Do not output documentation, only warnings. - -=back - -=head2 Output format modifiers - -=head3 reStructuredText only - -=head2 Output selection (mutually exclusive): - -=over 8 - -=item -export - -Only output documentation for the symbols that have been exported using -EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. - -=item -internal - -Only output documentation for the symbols that have NOT been exported using -EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. - -=item -function NAME - -Only output documentation for the given function or DOC: section title. -All other functions and DOC: sections are ignored. - -May be specified multiple times. - -=item -nosymbol NAME - -Exclude the specified symbol from the output documentation. - -May be specified multiple times. - -=back - -=head2 Output selection modifiers: - -=over 8 - -=item -no-doc-sections - -Do not output DOC: sections. - -=item -export-file FILE - -Specify an additional FILE in which to look for EXPORT_SYMBOL information. - -To be used with -export or -internal. - -May be specified multiple times. - -=back - -=head3 reStructuredText only - -=over 8 - -=item -enable-lineno - -Enable output of .. LINENO lines. - -=back - -=head2 Other parameters: - -=over 8 - -=item -h, -help - -Print this help. - -=item -v - -Verbose output, more warnings and other information. - -=item -Werror - -Treat warnings as errors. - -=back - -=cut diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index d9fe2bcbd39c..7a1eaf986bcd 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -111,7 +111,7 @@ import sys # Import Python modules -LIB_DIR = "lib/kdoc" +LIB_DIR = "../tools/lib/python" SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) @@ -292,8 +292,8 @@ def main(): logger.warning("Python 3.7 or later is required for correct results") # Import kernel-doc libraries only after checking Python version - from kdoc_files import KernelFiles # pylint: disable=C0415 - from kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 + from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 + from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 if args.man: out_style = ManFormat(modulename=args.modulename) diff --git a/scripts/sphinx-build-wrapper b/scripts/sphinx-build-wrapper deleted file mode 100755 index abe8c26ae137..000000000000 --- a/scripts/sphinx-build-wrapper +++ /dev/null @@ -1,719 +0,0 @@ -#!/usr/bin/env python3 -# SPDX-License-Identifier: GPL-2.0 -# Copyright (C) 2025 Mauro Carvalho Chehab -# -# pylint: disable=R0902, R0912, R0913, R0914, R0915, R0917, C0103 -# -# Converted from docs Makefile and parallel-wrapper.sh, both under -# GPLv2, copyrighted since 2008 by the following authors: -# -# Akira Yokosawa -# Arnd Bergmann -# Breno Leitao -# Carlos Bilbao -# Dave Young -# Donald Hunter -# Geert Uytterhoeven -# Jani Nikula -# Jan Stancek -# Jonathan Corbet -# Joshua Clayton -# Kees Cook -# Linus Torvalds -# Magnus Damm -# Masahiro Yamada -# Mauro Carvalho Chehab -# Maxim Cournoyer -# Peter Foley -# Randy Dunlap -# Rob Herring -# Shuah Khan -# Thorsten Blum -# Tomas Winkler - - -""" -Sphinx build wrapper that handles Kernel-specific business rules: - -- it gets the Kernel build environment vars; -- it determines what's the best parallelism; -- it handles SPHINXDIRS - -This tool ensures that MIN_PYTHON_VERSION is satisfied. If version is -below that, it seeks for a new Python version. If found, it re-runs using -the newer version. -""" - -import argparse -import locale -import os -import re -import shlex -import shutil -import subprocess -import sys - -from concurrent import futures -from glob import glob - -LIB_DIR = "lib" -SRC_DIR = os.path.dirname(os.path.realpath(__file__)) - -sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) - -from jobserver import JobserverExec # pylint: disable=C0413 - - -def parse_version(version): - """Convert a major.minor.patch version into a tuple""" - return tuple(int(x) for x in version.split(".")) - -def ver_str(version): - """Returns a version tuple as major.minor.patch""" - - return ".".join([str(x) for x in version]) - -# Minimal supported Python version needed by Sphinx and its extensions -MIN_PYTHON_VERSION = parse_version("3.7") - -# Default value for --venv parameter -VENV_DEFAULT = "sphinx_latest" - -# List of make targets and its corresponding builder and output directory -TARGETS = { - "cleandocs": { - "builder": "clean", - }, - "htmldocs": { - "builder": "html", - }, - "epubdocs": { - "builder": "epub", - "out_dir": "epub", - }, - "texinfodocs": { - "builder": "texinfo", - "out_dir": "texinfo", - }, - "infodocs": { - "builder": "texinfo", - "out_dir": "texinfo", - }, - "latexdocs": { - "builder": "latex", - "out_dir": "latex", - }, - "pdfdocs": { - "builder": "latex", - "out_dir": "latex", - }, - "xmldocs": { - "builder": "xml", - "out_dir": "xml", - }, - "linkcheckdocs": { - "builder": "linkcheck" - }, -} - -# Paper sizes. An empty value will pick the default -PAPER = ["", "a4", "letter"] - -class SphinxBuilder: - """ - Handles a sphinx-build target, adding needed arguments to build - with the Kernel. - """ - - def is_rust_enabled(self): - """Check if rust is enabled at .config""" - config_path = os.path.join(self.srctree, ".config") - if os.path.isfile(config_path): - with open(config_path, "r", encoding="utf-8") as f: - return "CONFIG_RUST=y" in f.read() - return False - - def get_path(self, path, abs_path=False): - """ - Ancillary routine to handle patches the right way, as shell does. - - It first expands "~" and "~user". Then, if patch is not absolute, - join self.srctree. Finally, if requested, convert to abspath. - """ - - path = os.path.expanduser(path) - if not path.startswith("/"): - path = os.path.join(self.srctree, path) - - if abs_path: - return os.path.abspath(path) - - return path - - def __init__(self, venv=None, verbose=False, n_jobs=None, interactive=None): - """Initialize internal variables""" - self.venv = venv - self.verbose = None - - # Normal variables passed from Kernel's makefile - self.kernelversion = os.environ.get("KERNELVERSION", "unknown") - self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown") - self.pdflatex = os.environ.get("PDFLATEX", "xelatex") - - if not interactive: - self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape") - else: - self.latexopts = os.environ.get("LATEXOPTS", "") - - if not verbose: - verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "") - - # Handle SPHINXOPTS evironment - sphinxopts = shlex.split(os.environ.get("SPHINXOPTS", "")) - - # As we handle number of jobs and quiet in separate, we need to pick - # it the same way as sphinx-build would pick, so let's use argparse - # do to the right argument expansion - parser = argparse.ArgumentParser() - parser.add_argument('-j', '--jobs', type=int) - parser.add_argument('-q', '--quiet', type=int) - - # Other sphinx-build arguments go as-is, so place them - # at self.sphinxopts - sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts) - if sphinx_args.quiet == True: - self.verbose = False - - if sphinx_args.jobs: - self.n_jobs = sphinx_args.jobs - - # Command line arguments was passed, override SPHINXOPTS - if verbose is not None: - self.verbose = verbose - - self.n_jobs = n_jobs - - # Source tree directory. This needs to be at os.environ, as - # Sphinx extensions and media uAPI makefile needs it - self.srctree = os.environ.get("srctree") - if not self.srctree: - self.srctree = "." - os.environ["srctree"] = self.srctree - - # Now that we can expand srctree, get other directories as well - self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") - self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", - "scripts/kernel-doc.py")) - self.obj = os.environ.get("obj", "Documentation") - self.builddir = self.get_path(os.path.join(self.obj, "output"), - abs_path=True) - - # Media uAPI needs it - os.environ["BUILDDIR"] = self.builddir - - # Detect if rust is enabled - self.config_rust = self.is_rust_enabled() - - # Get directory locations for LaTeX build toolchain - self.pdflatex_cmd = shutil.which(self.pdflatex) - self.latexmk_cmd = shutil.which("latexmk") - - self.env = os.environ.copy() - - # If venv parameter is specified, run Sphinx from venv - if venv: - bin_dir = os.path.join(venv, "bin") - if os.path.isfile(os.path.join(bin_dir, "activate")): - # "activate" virtual env - self.env["PATH"] = bin_dir + ":" + self.env["PATH"] - self.env["VIRTUAL_ENV"] = venv - if "PYTHONHOME" in self.env: - del self.env["PYTHONHOME"] - print(f"Setting venv to {venv}") - else: - sys.exit(f"Venv {venv} not found.") - - def run_sphinx(self, sphinx_build, build_args, *args, **pwargs): - """ - Executes sphinx-build using current python3 command and setting - -j parameter if possible to run the build in parallel. - """ - - with JobserverExec() as jobserver: - if jobserver.claim: - n_jobs = str(jobserver.claim) - else: - n_jobs = "auto" # Supported since Sphinx 1.7 - - cmd = [] - - if self.venv: - cmd.append("python") - else: - cmd.append(sys.executable) - - cmd.append(sphinx_build) - - # if present, SPHINXOPTS or command line --jobs overrides default - if self.n_jobs: - n_jobs = str(self.n_jobs) - - if n_jobs: - cmd += [f"-j{n_jobs}"] - - if not self.verbose: - cmd.append("-q") - - cmd += self.sphinxopts - - cmd += build_args - - if self.verbose: - print(" ".join(cmd)) - - rc = subprocess.call(cmd, *args, **pwargs) - - def handle_html(self, css, output_dir): - """ - Extra steps for HTML and epub output. - - For such targets, we need to ensure that CSS will be properly - copied to the output _static directory - """ - - if not css: - return - - css = os.path.expanduser(css) - if not css.startswith("/"): - css = os.path.join(self.srctree, css) - - static_dir = os.path.join(output_dir, "_static") - os.makedirs(static_dir, exist_ok=True) - - try: - shutil.copy2(css, static_dir) - except (OSError, IOError) as e: - print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr) - - def build_pdf_file(self, latex_cmd, from_dir, path): - """Builds a single pdf file using latex_cmd""" - try: - subprocess.run(latex_cmd + [path], - cwd=from_dir, check=True) - - return True - except subprocess.CalledProcessError: - # LaTeX PDF error code is almost useless: it returns - # error codes even when build succeeds but has warnings. - # So, we'll ignore the results - return False - - def pdf_parallel_build(self, tex_suffix, latex_cmd, tex_files, n_jobs): - """Build PDF files in parallel if possible""" - builds = {} - build_failed = False - max_len = 0 - has_tex = False - - # Process files in parallel - with futures.ThreadPoolExecutor(max_workers=n_jobs) as executor: - jobs = {} - - for from_dir, pdf_dir, entry in tex_files: - name = entry.name - - if not name.endswith(tex_suffix): - continue - - name = name[:-len(tex_suffix)] - - max_len = max(max_len, len(name)) - - has_tex = True - - future = executor.submit(self.build_pdf_file, latex_cmd, - from_dir, entry.path) - jobs[future] = (from_dir, name, entry.path) - - for future in futures.as_completed(jobs): - from_dir, name, path = jobs[future] - - pdf_name = name + ".pdf" - pdf_from = os.path.join(from_dir, pdf_name) - - try: - success = future.result() - - if success and os.path.exists(pdf_from): - pdf_to = os.path.join(pdf_dir, pdf_name) - - os.rename(pdf_from, pdf_to) - builds[name] = os.path.relpath(pdf_to, self.builddir) - else: - builds[name] = "FAILED" - build_failed = True - except Exception as e: - builds[name] = f"FAILED ({str(e)})" - build_failed = True - - # Handle case where no .tex files were found - if not has_tex: - name = "Sphinx LaTeX builder" - max_len = max(max_len, len(name)) - builds[name] = "FAILED (no .tex file was generated)" - build_failed = True - - return builds, build_failed, max_len - - def handle_pdf(self, output_dirs): - """ - Extra steps for PDF output. - - As PDF is handled via a LaTeX output, after building the .tex file, - a new build is needed to create the PDF output from the latex - directory. - """ - builds = {} - max_len = 0 - tex_suffix = ".tex" - - # Get all tex files that will be used for PDF build - tex_files = [] - for from_dir in output_dirs: - pdf_dir = os.path.join(from_dir, "../pdf") - os.makedirs(pdf_dir, exist_ok=True) - - if self.latexmk_cmd: - latex_cmd = [self.latexmk_cmd, f"-{self.pdflatex}"] - else: - latex_cmd = [self.pdflatex] - - latex_cmd.extend(shlex.split(self.latexopts)) - - # Get a list of tex files to process - with os.scandir(from_dir) as it: - for entry in it: - if entry.name.endswith(tex_suffix): - tex_files.append((from_dir, pdf_dir, entry)) - - # When using make, this won't be used, as the number of jobs comes - # from POSIX jobserver. So, this covers the case where build comes - # from command line. On such case, serialize by default, except if - # the user explicitly sets the number of jobs. - n_jobs = 1 - - # n_jobs is either an integer or "auto". Only use it if it is a number - if self.n_jobs: - try: - n_jobs = int(self.n_jobs) - except ValueError: - pass - - # When using make, jobserver.claim is the number of jobs that were - # used with "-j" and that aren't used by other make targets - with JobserverExec() as jobserver: - n_jobs = 1 - - # Handle the case when a parameter is passed via command line, - # using it as default, if jobserver doesn't claim anything - if self.n_jobs: - try: - n_jobs = int(self.n_jobs) - except ValueError: - pass - - if jobserver.claim: - n_jobs = jobserver.claim - - # Build files in parallel - builds, build_failed, max_len = self.pdf_parallel_build(tex_suffix, - latex_cmd, - tex_files, - n_jobs) - - msg = "Summary" - msg += "\n" + "=" * len(msg) - print() - print(msg) - - for pdf_name, pdf_file in builds.items(): - print(f"{pdf_name:<{max_len}}: {pdf_file}") - - print() - - # return an error if a PDF file is missing - - if build_failed: - sys.exit(f"PDF build failed: not all PDF files were created.") - else: - print("All PDF files were built.") - - def handle_info(self, output_dirs): - """ - Extra steps for Info output. - - For texinfo generation, an additional make is needed from the - texinfo directory. - """ - - for output_dir in output_dirs: - try: - subprocess.run(["make", "info"], cwd=output_dir, check=True) - except subprocess.CalledProcessError as e: - sys.exit(f"Error generating info docs: {e}") - - def cleandocs(self, builder): - - shutil.rmtree(self.builddir, ignore_errors=True) - - def build(self, target, sphinxdirs=None, conf="conf.py", - theme=None, css=None, paper=None): - """ - Build documentation using Sphinx. This is the core function of this - module. It prepares all arguments required by sphinx-build. - """ - - builder = TARGETS[target]["builder"] - out_dir = TARGETS[target].get("out_dir", "") - - # Cleandocs doesn't require sphinx-build - if target == "cleandocs": - self.cleandocs(builder) - return - - # Other targets require sphinx-build - sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"]) - if not sphinxbuild: - sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n") - - if builder == "latex": - if not self.pdflatex_cmd and not self.latexmk_cmd: - sys.exit("Error: pdflatex or latexmk required for PDF generation") - - docs_dir = os.path.abspath(os.path.join(self.srctree, "Documentation")) - - # Prepare base arguments for Sphinx build - kerneldoc = self.kerneldoc - if kerneldoc.startswith(self.srctree): - kerneldoc = os.path.relpath(kerneldoc, self.srctree) - - # Prepare common Sphinx options - args = [ - "-b", builder, - "-c", docs_dir, - ] - - if builder == "latex": - if not paper: - paper = PAPER[1] - - args.extend(["-D", f"latex_elements.papersize={paper}paper"]) - - if self.config_rust: - args.extend(["-t", "rustdoc"]) - - if conf: - self.env["SPHINX_CONF"] = self.get_path(conf, abs_path=True) - - if not sphinxdirs: - sphinxdirs = os.environ.get("SPHINXDIRS", ".") - - # The sphinx-build tool has a bug: internally, it tries to set - # locale with locale.setlocale(locale.LC_ALL, ''). This causes a - # crash if language is not set. Detect and fix it. - try: - locale.setlocale(locale.LC_ALL, '') - except Exception: - self.env["LC_ALL"] = "C" - self.env["LANG"] = "C" - - # sphinxdirs can be a list or a whitespace-separated string - sphinxdirs_list = [] - for sphinxdir in sphinxdirs: - if isinstance(sphinxdir, list): - sphinxdirs_list += sphinxdir - else: - for name in sphinxdir.split(" "): - sphinxdirs_list.append(name) - - # Build each directory - output_dirs = [] - for sphinxdir in sphinxdirs_list: - src_dir = os.path.join(docs_dir, sphinxdir) - doctree_dir = os.path.join(self.builddir, ".doctrees") - output_dir = os.path.join(self.builddir, sphinxdir, out_dir) - - # Make directory names canonical - src_dir = os.path.normpath(src_dir) - doctree_dir = os.path.normpath(doctree_dir) - output_dir = os.path.normpath(output_dir) - - os.makedirs(doctree_dir, exist_ok=True) - os.makedirs(output_dir, exist_ok=True) - - output_dirs.append(output_dir) - - build_args = args + [ - "-d", doctree_dir, - "-D", f"kerneldoc_bin={kerneldoc}", - "-D", f"version={self.kernelversion}", - "-D", f"release={self.kernelrelease}", - "-D", f"kerneldoc_srctree={self.srctree}", - src_dir, - output_dir, - ] - - # Execute sphinx-build - try: - self.run_sphinx(sphinxbuild, build_args, env=self.env) - except Exception as e: - sys.exit(f"Build failed: {e}") - - # Ensure that html/epub will have needed static files - if target in ["htmldocs", "epubdocs"]: - self.handle_html(css, output_dir) - - # PDF and Info require a second build step - if target == "pdfdocs": - self.handle_pdf(output_dirs) - elif target == "infodocs": - self.handle_info(output_dirs) - - @staticmethod - def get_python_version(cmd): - """ - Get python version from a Python binary. As we need to detect if - are out there newer python binaries, we can't rely on sys.release here. - """ - - result = subprocess.run([cmd, "--version"], check=True, - stdout=subprocess.PIPE, stderr=subprocess.PIPE, - universal_newlines=True) - version = result.stdout.strip() - - match = re.search(r"(\d+\.\d+\.\d+)", version) - if match: - return parse_version(match.group(1)) - - print(f"Can't parse version {version}") - return (0, 0, 0) - - @staticmethod - def find_python(): - """ - Detect if are out there any python 3.xy version newer than the - current one. - - Note: this routine is limited to up to 2 digits for python3. We - may need to update it one day, hopefully on a distant future. - """ - patterns = [ - "python3.[0-9]", - "python3.[0-9][0-9]", - ] - - # Seek for a python binary newer than MIN_PYTHON_VERSION - for path in os.getenv("PATH", "").split(":"): - for pattern in patterns: - for cmd in glob(os.path.join(path, pattern)): - if os.path.isfile(cmd) and os.access(cmd, os.X_OK): - version = SphinxBuilder.get_python_version(cmd) - if version >= MIN_PYTHON_VERSION: - return cmd - - return None - - @staticmethod - def check_python(): - """ - Check if the current python binary satisfies our minimal requirement - for Sphinx build. If not, re-run with a newer version if found. - """ - cur_ver = sys.version_info[:3] - if cur_ver >= MIN_PYTHON_VERSION: - return - - python_ver = ver_str(cur_ver) - - new_python_cmd = SphinxBuilder.find_python() - if not new_python_cmd: - sys.exit(f"Python version {python_ver} is not supported anymore.") - - # Restart script using the newer version - script_path = os.path.abspath(sys.argv[0]) - args = [new_python_cmd, script_path] + sys.argv[1:] - - print(f"Python {python_ver} not supported. Changing to {new_python_cmd}") - - try: - os.execv(new_python_cmd, args) - except OSError as e: - sys.exit(f"Failed to restart with {new_python_cmd}: {e}") - -def jobs_type(value): - """ - Handle valid values for -j. Accepts Sphinx "-jauto", plus a number - equal or bigger than one. - """ - if value is None: - return None - - if value.lower() == 'auto': - return value.lower() - - try: - if int(value) >= 1: - return value - - raise argparse.ArgumentTypeError(f"Minimum jobs is 1, got {value}") - except ValueError: - raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}") - -def main(): - """ - Main function. The only mandatory argument is the target. If not - specified, the other arguments will use default values if not - specified at os.environ. - """ - parser = argparse.ArgumentParser(description="Kernel documentation builder") - - parser.add_argument("target", choices=list(TARGETS.keys()), - help="Documentation target to build") - parser.add_argument("--sphinxdirs", nargs="+", - help="Specific directories to build") - parser.add_argument("--conf", default="conf.py", - help="Sphinx configuration file") - - parser.add_argument("--theme", help="Sphinx theme to use") - - parser.add_argument("--css", help="Custom CSS file for HTML/EPUB") - - parser.add_argument("--paper", choices=PAPER, default=PAPER[0], - help="Paper size for LaTeX/PDF output") - - parser.add_argument("-v", "--verbose", action='store_true', - help="place build in verbose mode") - - parser.add_argument('-j', '--jobs', type=jobs_type, - help="Sets number of jobs to use with sphinx-build") - - parser.add_argument('-i', '--interactive', action='store_true', - help="Change latex default to run in interactive mode") - - parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}', - default=None, - help=f'If used, run Sphinx from a venv dir (default dir: {VENV_DEFAULT})') - - args = parser.parse_args() - - SphinxBuilder.check_python() - - builder = SphinxBuilder(venv=args.venv, verbose=args.verbose, - n_jobs=args.jobs, interactive=args.interactive) - - builder.build(args.target, sphinxdirs=args.sphinxdirs, conf=args.conf, - theme=args.theme, css=args.css, paper=args.paper) - -if __name__ == "__main__": - main() diff --git a/scripts/split-man.pl b/scripts/split-man.pl deleted file mode 100755 index 96bd99dc977a..000000000000 --- a/scripts/split-man.pl +++ /dev/null @@ -1,28 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# -# Author: Mauro Carvalho Chehab -# -# Produce manpages from kernel-doc. -# See Documentation/doc-guide/kernel-doc.rst for instructions - -if ($#ARGV < 0) { - die "where do I put the results?\n"; -} - -mkdir $ARGV[0],0777; -$state = 0; -while () { - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { - if ($state == 1) { close OUT } - $state = 1; - $fn = "$ARGV[0]/$1.9"; - print STDERR "Creating $fn\n"; - open OUT, ">$fn" or die "can't open $fn: $!\n"; - print OUT $_; - } elsif ($state != 0) { - print OUT $_; - } -} - -close OUT; diff --git a/tools/docs/check-variable-fonts.py b/tools/docs/check-variable-fonts.py new file mode 100755 index 000000000000..958d5a745724 --- /dev/null +++ b/tools/docs/check-variable-fonts.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-only +# Copyright (C) Akira Yokosawa, 2024 +# +# Ported to Python by (c) Mauro Carvalho Chehab, 2025 +# +# pylint: disable=C0103 + +""" +Detect problematic Noto CJK variable fonts. + +or more details, see .../tools/lib/python/kdoc/latex_fonts.py. +""" + +import argparse +import sys +import os.path + +src_dir = os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(src_dir, '../lib/python')) + +from kdoc.latex_fonts import LatexFontChecker + +checker = LatexFontChecker() + +parser=argparse.ArgumentParser(description=checker.description(), + formatter_class=argparse.RawTextHelpFormatter) +parser.add_argument("--deny-vf", + help="XDG_CONFIG_HOME dir containing fontconfig/fonts.conf file") + +args=parser.parse_args() + +msg = LatexFontChecker(args.deny_vf).check() +if msg: + print(msg) + +sys.exit(1) diff --git a/scripts/checktransupdate.py b/tools/docs/checktransupdate.py similarity index 97% rename from scripts/checktransupdate.py rename to tools/docs/checktransupdate.py index e39529e46c3d..e894652369a5 100755 --- a/scripts/checktransupdate.py +++ b/tools/docs/checktransupdate.py @@ -9,9 +9,9 @@ commit to find the latest english commit from the translation commit differences occur, report the file and commits that need to be updated. The usage is as follows: -- ./scripts/checktransupdate.py -l zh_CN +- tools/docs/checktransupdate.py -l zh_CN This will print all the files that need to be updated or translated in the zh_CN locale. -- ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst +- tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst This will only print the status of the specified file. The output is something like: @@ -168,7 +168,7 @@ def check_per_file(file_path): def valid_locales(locale): """Check if the locale is valid or not""" script_path = os.path.dirname(os.path.abspath(__file__)) - linux_path = os.path.join(script_path, "..") + linux_path = os.path.join(script_path, "../..") if not os.path.isdir(f"{linux_path}/Documentation/translations/{locale}"): raise ArgumentTypeError("Invalid locale: {locale}") return locale @@ -232,7 +232,7 @@ def config_logging(log_level, log_file="checktransupdate.log"): def main(): """Main function of the script""" script_path = os.path.dirname(os.path.abspath(__file__)) - linux_path = os.path.join(script_path, "..") + linux_path = os.path.join(script_path, "../..") parser = ArgumentParser(description="Check the translation update") parser.add_argument( diff --git a/scripts/documentation-file-ref-check b/tools/docs/documentation-file-ref-check similarity index 99% rename from scripts/documentation-file-ref-check rename to tools/docs/documentation-file-ref-check index 408b1dbe7884..0cad42f6943b 100755 --- a/scripts/documentation-file-ref-check +++ b/tools/docs/documentation-file-ref-check @@ -17,7 +17,7 @@ my %false_positives = ( ); my $scriptname = $0; -$scriptname =~ s,.*/([^/]+/),$1,; +$scriptname =~ s,tools/docs/([^/]+/),$1,; # Parse arguments my $help = 0; diff --git a/Documentation/features/scripts/features-refresh.sh b/tools/docs/features-refresh.sh similarity index 100% rename from Documentation/features/scripts/features-refresh.sh rename to tools/docs/features-refresh.sh diff --git a/scripts/find-unused-docs.sh b/tools/docs/find-unused-docs.sh similarity index 85% rename from scripts/find-unused-docs.sh rename to tools/docs/find-unused-docs.sh index d6d397fbf917..05552dbda5bc 100755 --- a/scripts/find-unused-docs.sh +++ b/tools/docs/find-unused-docs.sh @@ -5,10 +5,10 @@ # This script detects files with kernel-doc comments for exported functions # that are not included in documentation. # -# usage: Run 'scripts/find-unused-docs.sh directory' from top level of kernel +# usage: Run 'tools/docs/find-unused-docs.sh directory' from top level of kernel # tree. # -# example: $scripts/find-unused-docs.sh drivers/scsi +# example: $tools/docs/find-unused-docs.sh drivers/scsi # # Licensed under the terms of the GNU GPL License @@ -18,7 +18,7 @@ if ! [ -d "Documentation" ]; then fi if [ "$#" -ne 1 ]; then - echo "Usage: scripts/find-unused-docs.sh directory" + echo "Usage: tools/docs/find-unused-docs.sh directory" exit 1 fi diff --git a/scripts/get_abi.py b/tools/docs/get_abi.py similarity index 95% rename from scripts/get_abi.py rename to tools/docs/get_abi.py index 7ce4748a46d2..2f0b99401f26 100755 --- a/scripts/get_abi.py +++ b/tools/docs/get_abi.py @@ -14,15 +14,15 @@ import sys # Import Python modules -LIB_DIR = "lib/abi" +LIB_DIR = "../lib/python" SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) -from abi_parser import AbiParser # pylint: disable=C0413 -from abi_regex import AbiRegex # pylint: disable=C0413 -from helpers import ABI_DIR, DEBUG_HELP # pylint: disable=C0413 -from system_symbols import SystemSymbols # pylint: disable=C0413 +from abi.abi_parser import AbiParser # pylint: disable=C0413 +from abi.abi_regex import AbiRegex # pylint: disable=C0413 +from abi.helpers import ABI_DIR, DEBUG_HELP # pylint: disable=C0413 +from abi.system_symbols import SystemSymbols # pylint: disable=C0413 # Command line classes diff --git a/tools/docs/get_feat.py b/tools/docs/get_feat.py new file mode 100755 index 000000000000..2b5155a1f134 --- /dev/null +++ b/tools/docs/get_feat.py @@ -0,0 +1,225 @@ +#!/usr/bin/env python3 +# pylint: disable=R0902,R0911,R0912,R0914,R0915 +# Copyright(c) 2025: Mauro Carvalho Chehab . +# SPDX-License-Identifier: GPL-2.0 + + +""" +Parse the Linux Feature files and produce a ReST book. +""" + +import argparse +import os +import subprocess +import sys + +from pprint import pprint + +LIB_DIR = "../../tools/lib/python" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) + +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) + +from feat.parse_features import ParseFeature # pylint: disable=C0413 + +SRCTREE = os.path.join(os.path.dirname(os.path.realpath(__file__)), "../..") +DEFAULT_DIR = "Documentation/features" + + +class GetFeature: + """Helper class to parse feature parsing parameters""" + + @staticmethod + def get_current_arch(): + """Detects the current architecture""" + + proc = subprocess.run(["uname", "-m"], check=True, + capture_output=True, text=True) + + arch = proc.stdout.strip() + if arch in ["x86_64", "i386"]: + arch = "x86" + elif arch == "s390x": + arch = "s390" + + return arch + + def run_parser(self, args): + """Execute the feature parser""" + + feat = ParseFeature(args.directory, args.debug, args.enable_fname) + data = feat.parse() + + if args.debug > 2: + pprint(data) + + return feat + + def run_rest(self, args): + """ + Generate tables in ReST format. Three types of tables are + supported, depending on the calling arguments: + + - neither feature nor arch is passed: generates a full matrix; + - arch provided: generates a table of supported tables for the + guiven architecture, eventually filtered by feature; + - only feature provided: generates a table with feature details, + showing what architectures it is implemented. + """ + + feat = self.run_parser(args) + + if args.arch: + rst = feat.output_arch_table(args.arch, args.feat) + elif args.feat: + rst = feat.output_feature(args.feat) + else: + rst = feat.output_matrix() + + print(rst) + + def run_current(self, args): + """ + Instead of using a --arch parameter, get feature for the current + architecture. + """ + + args.arch = self.get_current_arch() + + self.run_rest(args) + + def run_list(self, args): + """ + Generate a list of features for a given architecture, in a format + parseable by other scripts. The output format is not ReST. + """ + + if not args.arch: + args.arch = self.get_current_arch() + + feat = self.run_parser(args) + msg = feat.list_arch_features(args.arch, args.feat) + + print(msg) + + def parse_arch(self, parser): + """Add a --arch parsing argument""" + + parser.add_argument("--arch", + help="Output features for an specific" + " architecture, optionally filtering for a " + "single specific feature.") + + def parse_feat(self, parser): + """Add a --feat parsing argument""" + + parser.add_argument("--feat", "--feature", + help="Output features for a single specific " + "feature.") + + + def current_args(self, subparsers): + """Implementscurrent argparse subparser""" + + parser = subparsers.add_parser("current", + formatter_class=argparse.RawTextHelpFormatter, + description="Output table in ReST " + "compatible ASCII format " + "with features for this " + "machine's architecture") + + self.parse_feat(parser) + parser.set_defaults(func=self.run_current) + + def rest_args(self, subparsers): + """Implement rest argparse subparser""" + + parser = subparsers.add_parser("rest", + formatter_class=argparse.RawTextHelpFormatter, + description="Output table(s) in ReST " + "compatible ASCII format " + "with features in ReST " + "markup language. The " + "output is affected by " + "--arch or --feat/--feature" + " flags.") + + self.parse_arch(parser) + self.parse_feat(parser) + parser.set_defaults(func=self.run_rest) + + def list_args(self, subparsers): + """Implement list argparse subparser""" + + parser = subparsers.add_parser("list", + formatter_class=argparse.RawTextHelpFormatter, + description="List features for this " + "machine's architecture, " + "using an easier to parse " + "format. The output is " + "affected by --arch flag.") + + self.parse_arch(parser) + self.parse_feat(parser) + parser.set_defaults(func=self.run_list) + + def validate_args(self, subparsers): + """Implement validate argparse subparser""" + + parser = subparsers.add_parser("validate", + formatter_class=argparse.RawTextHelpFormatter, + description="Validate the contents of " + "the files under " + f"{DEFAULT_DIR}.") + + parser.set_defaults(func=self.run_parser) + + def parser(self): + """ + Create an arparse with common options and several subparsers + """ + parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter) + + parser.add_argument("-d", "--debug", action="count", default=0, + help="Put the script in verbose mode, useful for " + "debugging. Can be called multiple times, to " + "increase verbosity.") + + parser.add_argument("--directory", "--dir", default=DEFAULT_DIR, + help="Changes the location of the Feature files. " + f"By default, it uses the {DEFAULT_DIR} " + "directory.") + + parser.add_argument("--enable-fname", action="store_true", + help="Prints the file name of the feature files. " + "This can be used in order to track " + "dependencies during documentation build.") + + subparsers = parser.add_subparsers() + + self.current_args(subparsers) + self.rest_args(subparsers) + self.list_args(subparsers) + self.validate_args(subparsers) + + args = parser.parse_args() + + return args + + +def main(): + """Main program""" + + feat = GetFeature() + + args = feat.parser() + + if "func" in args: + args.func(args) + else: + sys.exit(f"Please specify a valid command for {sys.argv[0]}") + + +# Call main method +if __name__ == "__main__": + main() diff --git a/Documentation/features/list-arch.sh b/tools/docs/list-arch.sh similarity index 83% rename from Documentation/features/list-arch.sh rename to tools/docs/list-arch.sh index ac8ff7f6f859..96fe83b7058b 100755 --- a/Documentation/features/list-arch.sh +++ b/tools/docs/list-arch.sh @@ -8,4 +8,4 @@ ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/' | sed 's/s390x/s390/')} -$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH +$(dirname $0)/get_feat.pl list --arch $ARCH diff --git a/tools/docs/parse-headers.py b/tools/docs/parse-headers.py index bfa4e46a53e3..436acea4c6ca 100755 --- a/tools/docs/parse-headers.py +++ b/tools/docs/parse-headers.py @@ -24,10 +24,13 @@ The optional ``FILE_RULES`` contains a set of rules like: replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` """ -import argparse +import argparse, sys +import os.path -from lib.parse_data_structs import ParseDataStructs -from lib.enrich_formatter import EnrichFormatter +src_dir = os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(src_dir, '../lib/python')) +from kdoc.parse_data_structs import ParseDataStructs +from kdoc.enrich_formatter import EnrichFormatter def main(): """Main function""" @@ -47,10 +50,7 @@ def main(): args = parser.parse_args() parser = ParseDataStructs(debug=args.debug) - parser.parse_file(args.file_in) - - if args.file_rules: - parser.process_exceptions(args.file_rules) + parser.parse_file(args.file_in, args.file_rules) parser.debug_print() parser.write_output(args.file_in, args.file_out, args.toc) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper new file mode 100755 index 000000000000..7a5fcef25429 --- /dev/null +++ b/tools/docs/sphinx-build-wrapper @@ -0,0 +1,864 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2025 Mauro Carvalho Chehab +# +# pylint: disable=R0902, R0912, R0913, R0914, R0915, R0917, C0103 +# +# Converted from docs Makefile and parallel-wrapper.sh, both under +# GPLv2, copyrighted since 2008 by the following authors: +# +# Akira Yokosawa +# Arnd Bergmann +# Breno Leitao +# Carlos Bilbao +# Dave Young +# Donald Hunter +# Geert Uytterhoeven +# Jani Nikula +# Jan Stancek +# Jonathan Corbet +# Joshua Clayton +# Kees Cook +# Linus Torvalds +# Magnus Damm +# Masahiro Yamada +# Mauro Carvalho Chehab +# Maxim Cournoyer +# Peter Foley +# Randy Dunlap +# Rob Herring +# Shuah Khan +# Thorsten Blum +# Tomas Winkler + + +""" +Sphinx build wrapper that handles Kernel-specific business rules: + +- it gets the Kernel build environment vars; +- it determines what's the best parallelism; +- it handles SPHINXDIRS + +This tool ensures that MIN_PYTHON_VERSION is satisfied. If version is +below that, it seeks for a new Python version. If found, it re-runs using +the newer version. +""" + +import argparse +import locale +import os +import re +import shlex +import shutil +import subprocess +import sys + +from concurrent import futures +from glob import glob + + +LIB_DIR = "../lib/python" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) + +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) + +from kdoc.python_version import PythonVersion +from kdoc.latex_fonts import LatexFontChecker +from jobserver import JobserverExec # pylint: disable=C0413,C0411,E0401 + +# +# Some constants +# +VENV_DEFAULT = "sphinx_latest" +MIN_PYTHON_VERSION = PythonVersion("3.7").version +PAPER = ["", "a4", "letter"] + +TARGETS = { + "cleandocs": { "builder": "clean" }, + "linkcheckdocs": { "builder": "linkcheck" }, + "htmldocs": { "builder": "html" }, + "epubdocs": { "builder": "epub", "out_dir": "epub" }, + "texinfodocs": { "builder": "texinfo", "out_dir": "texinfo" }, + "infodocs": { "builder": "texinfo", "out_dir": "texinfo" }, + "mandocs": { "builder": "man", "out_dir": "man" }, + "latexdocs": { "builder": "latex", "out_dir": "latex" }, + "pdfdocs": { "builder": "latex", "out_dir": "latex" }, + "xmldocs": { "builder": "xml", "out_dir": "xml" }, +} + + +# +# SphinxBuilder class +# + +class SphinxBuilder: + """ + Handles a sphinx-build target, adding needed arguments to build + with the Kernel. + """ + + def get_path(self, path, use_cwd=False, abs_path=False): + """ + Ancillary routine to handle patches the right way, as shell does. + + It first expands "~" and "~user". Then, if patch is not absolute, + join self.srctree. Finally, if requested, convert to abspath. + """ + + path = os.path.expanduser(path) + if not path.startswith("/"): + if use_cwd: + base = os.getcwd() + else: + base = self.srctree + + path = os.path.join(base, path) + + if abs_path: + return os.path.abspath(path) + + return path + + def check_rust(self): + """ + Checks if Rust is enabled + """ + self.rustdoc = False + + config = os.path.join(self.srctree, ".config") + + if not os.path.isfile(config): + return + + re_rust = re.compile(r"CONFIG_RUST=(m|y)") + + try: + with open(config, "r", encoding="utf-8") as fp: + for line in fp: + if re_rust.match(line): + self.rustdoc = True + return + + except OSError as e: + print(f"Failed to open {config}", file=sys.stderr) + + def get_sphinx_extra_opts(self, n_jobs): + """ + Get the number of jobs to be used for docs build passed via command + line and desired sphinx verbosity. + + The number of jobs can be on different places: + + 1) It can be passed via "-j" argument; + 2) The SPHINXOPTS="-j8" env var may have "-j"; + 3) if called via GNU make, -j specifies the desired number of jobs. + with GNU makefile, this number is available via POSIX jobserver; + 4) if none of the above is available, it should default to "-jauto", + and let sphinx decide the best value. + """ + + # + # SPHINXOPTS env var, if used, contains extra arguments to be used + # by sphinx-build time. Among them, it may contain sphinx verbosity + # and desired number of parallel jobs. + # + parser = argparse.ArgumentParser() + parser.add_argument('-j', '--jobs', type=int) + parser.add_argument('-q', '--quiet', action='store_true') + + # + # Other sphinx-build arguments go as-is, so place them + # at self.sphinxopts, using shell parser + # + sphinxopts = shlex.split(os.environ.get("SPHINXOPTS", "")) + + # + # Build a list of sphinx args, honoring verbosity here if specified + # + + verbose = self.verbose + sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts) + if sphinx_args.quiet is True: + verbose = False + + # + # If the user explicitly sets "-j" at command line, use it. + # Otherwise, pick it from SPHINXOPTS args + # + if n_jobs: + self.n_jobs = n_jobs + elif sphinx_args.jobs: + self.n_jobs = sphinx_args.jobs + else: + self.n_jobs = None + + if not verbose: + self.sphinxopts += ["-q"] + + def __init__(self, builddir, venv=None, verbose=False, n_jobs=None, + interactive=None): + """Initialize internal variables""" + self.venv = venv + self.verbose = None + + # + # Normal variables passed from Kernel's makefile + # + self.kernelversion = os.environ.get("KERNELVERSION", "unknown") + self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown") + self.pdflatex = os.environ.get("PDFLATEX", "xelatex") + + # + # Kernel main Makefile defines a PYTHON3 variable whose default is + # "python3". When set to a different value, it allows running a + # diferent version than the default official python3 package. + # Several distros package python3xx-sphinx packages with newer + # versions of Python and sphinx-build. + # + # Honor such variable different than default + # + self.python = os.environ.get("PYTHON3") + if self.python == "python3": + self.python = None + + if not interactive: + self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape") + else: + self.latexopts = os.environ.get("LATEXOPTS", "") + + if not verbose: + verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "") + + if verbose is not None: + self.verbose = verbose + + # + # Source tree directory. This needs to be at os.environ, as + # Sphinx extensions use it + # + self.srctree = os.environ.get("srctree") + if not self.srctree: + self.srctree = "." + os.environ["srctree"] = self.srctree + + # + # Now that we can expand srctree, get other directories as well + # + self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") + self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", + "scripts/kernel-doc.py")) + self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True) + + # + # Get directory locations for LaTeX build toolchain + # + self.pdflatex_cmd = shutil.which(self.pdflatex) + self.latexmk_cmd = shutil.which("latexmk") + + self.env = os.environ.copy() + + self.get_sphinx_extra_opts(n_jobs) + + self.check_rust() + + # + # If venv command line argument is specified, run Sphinx from venv + # + if venv: + bin_dir = os.path.join(venv, "bin") + if not os.path.isfile(os.path.join(bin_dir, "activate")): + sys.exit(f"Venv {venv} not found.") + + # "activate" virtual env + self.env["PATH"] = bin_dir + ":" + self.env["PATH"] + self.env["VIRTUAL_ENV"] = venv + if "PYTHONHOME" in self.env: + del self.env["PYTHONHOME"] + print(f"Setting venv to {venv}") + + def run_sphinx(self, sphinx_build, build_args, *args, **pwargs): + """ + Executes sphinx-build using current python3 command. + + When calling via GNU make, POSIX jobserver is used to tell how + many jobs are still available from a job pool. claim all remaining + jobs, as we don't want sphinx-build to run in parallel with other + jobs. + + Despite that, the user may actually force a different value than + the number of available jobs via command line. + + The "with" logic here is used to ensure that the claimed jobs will + be freed once subprocess finishes + """ + + with JobserverExec() as jobserver: + if jobserver.claim: + # + # when GNU make is used, claim available jobs from jobserver + # + n_jobs = str(jobserver.claim) + else: + # + # Otherwise, let sphinx decide by default + # + n_jobs = "auto" + + # + # If explicitly requested via command line, override default + # + if self.n_jobs: + n_jobs = str(self.n_jobs) + + # + # We can't simply call python3 sphinx-build, as OpenSUSE + # Tumbleweed uses an ELF binary file (/usr/bin/alts) to switch + # between different versions of sphinx-build. So, only call it + # prepending "python3.xx" when PYTHON3 variable is not default. + # + if self.python: + cmd = [self.python] + else: + cmd = [] + + cmd += [sphinx_build] + cmd += [f"-j{n_jobs}"] + cmd += build_args + cmd += self.sphinxopts + + if self.verbose: + print(" ".join(cmd)) + + return subprocess.call(cmd, *args, **pwargs) + + def handle_html(self, css, output_dir): + """ + Extra steps for HTML and epub output. + + For such targets, we need to ensure that CSS will be properly + copied to the output _static directory + """ + + if css: + css = os.path.expanduser(css) + if not css.startswith("/"): + css = os.path.join(self.srctree, css) + + static_dir = os.path.join(output_dir, "_static") + os.makedirs(static_dir, exist_ok=True) + + try: + shutil.copy2(css, static_dir) + except (OSError, IOError) as e: + print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr) + + if self.rustdoc: + print("Building rust docs") + if "MAKE" in self.env: + cmd = [self.env["MAKE"]] + else: + cmd = ["make", "LLVM=1"] + + cmd += [ "rustdoc"] + if self.verbose: + print(" ".join(cmd)) + + try: + subprocess.run(cmd, check=True) + except subprocess.CalledProcessError as e: + print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?", + file=sys.stderr) + + def build_pdf_file(self, latex_cmd, from_dir, path): + """Builds a single pdf file using latex_cmd""" + try: + subprocess.run(latex_cmd + [path], + cwd=from_dir, check=True, env=self.env) + + return True + except subprocess.CalledProcessError: + return False + + def pdf_parallel_build(self, tex_suffix, latex_cmd, tex_files, n_jobs): + """Build PDF files in parallel if possible""" + builds = {} + build_failed = False + max_len = 0 + has_tex = False + + # + # LaTeX PDF error code is almost useless for us: + # any warning makes it non-zero. For kernel doc builds it always return + # non-zero even when build succeeds. So, let's do the best next thing: + # Ignore build errors. At the end, check if all PDF files were built, + # printing a summary with the built ones and returning 0 if all of + # them were actually built. + # + with futures.ThreadPoolExecutor(max_workers=n_jobs) as executor: + jobs = {} + + for from_dir, pdf_dir, entry in tex_files: + name = entry.name + + if not name.endswith(tex_suffix): + continue + + name = name[:-len(tex_suffix)] + has_tex = True + + future = executor.submit(self.build_pdf_file, latex_cmd, + from_dir, entry.path) + jobs[future] = (from_dir, pdf_dir, name) + + for future in futures.as_completed(jobs): + from_dir, pdf_dir, name = jobs[future] + + pdf_name = name + ".pdf" + pdf_from = os.path.join(from_dir, pdf_name) + pdf_to = os.path.join(pdf_dir, pdf_name) + out_name = os.path.relpath(pdf_to, self.builddir) + max_len = max(max_len, len(out_name)) + + try: + success = future.result() + + if success and os.path.exists(pdf_from): + os.rename(pdf_from, pdf_to) + + # + # if verbose, get the name of built PDF file + # + if self.verbose: + builds[out_name] = "SUCCESS" + else: + builds[out_name] = "FAILED" + build_failed = True + except futures.Error as e: + builds[out_name] = f"FAILED ({repr(e)})" + build_failed = True + + # + # Handle case where no .tex files were found + # + if not has_tex: + out_name = "LaTeX files" + max_len = max(max_len, len(out_name)) + builds[out_name] = "FAILED: no .tex files were generated" + build_failed = True + + return builds, build_failed, max_len + + def handle_pdf(self, output_dirs, deny_vf): + """ + Extra steps for PDF output. + + As PDF is handled via a LaTeX output, after building the .tex file, + a new build is needed to create the PDF output from the latex + directory. + """ + builds = {} + max_len = 0 + tex_suffix = ".tex" + tex_files = [] + + # + # Since early 2024, Fedora and openSUSE tumbleweed have started + # deploying variable-font format of "Noto CJK", causing LaTeX + # to break with CJK. Work around it, by denying the variable font + # usage during xelatex build by passing the location of a config + # file with a deny list. + # + # See tools/docs/lib/latex_fonts.py for more details. + # + if deny_vf: + deny_vf = os.path.expanduser(deny_vf) + if os.path.isdir(deny_vf): + self.env["XDG_CONFIG_HOME"] = deny_vf + + for from_dir in output_dirs: + pdf_dir = os.path.join(from_dir, "../pdf") + os.makedirs(pdf_dir, exist_ok=True) + + if self.latexmk_cmd: + latex_cmd = [self.latexmk_cmd, f"-{self.pdflatex}"] + else: + latex_cmd = [self.pdflatex] + + latex_cmd.extend(shlex.split(self.latexopts)) + + # Get a list of tex files to process + with os.scandir(from_dir) as it: + for entry in it: + if entry.name.endswith(tex_suffix): + tex_files.append((from_dir, pdf_dir, entry)) + + # + # When using make, this won't be used, as the number of jobs comes + # from POSIX jobserver. So, this covers the case where build comes + # from command line. On such case, serialize by default, except if + # the user explicitly sets the number of jobs. + # + n_jobs = 1 + + # n_jobs is either an integer or "auto". Only use it if it is a number + if self.n_jobs: + try: + n_jobs = int(self.n_jobs) + except ValueError: + pass + + # + # When using make, jobserver.claim is the number of jobs that were + # used with "-j" and that aren't used by other make targets + # + with JobserverExec() as jobserver: + n_jobs = 1 + + # + # Handle the case when a parameter is passed via command line, + # using it as default, if jobserver doesn't claim anything + # + if self.n_jobs: + try: + n_jobs = int(self.n_jobs) + except ValueError: + pass + + if jobserver.claim: + n_jobs = jobserver.claim + + builds, build_failed, max_len = self.pdf_parallel_build(tex_suffix, + latex_cmd, + tex_files, + n_jobs) + + # + # In verbose mode, print a summary with the build results per file. + # Otherwise, print a single line with all failures, if any. + # On both cases, return code 1 indicates build failures, + # + if self.verbose: + msg = "Summary" + msg += "\n" + "=" * len(msg) + print() + print(msg) + + for pdf_name, pdf_file in builds.items(): + print(f"{pdf_name:<{max_len}}: {pdf_file}") + + print() + if build_failed: + msg = LatexFontChecker().check() + if msg: + print(msg) + + sys.exit("Error: not all PDF files were created.") + + elif build_failed: + n_failures = len(builds) + failures = ", ".join(builds.keys()) + + msg = LatexFontChecker().check() + if msg: + print(msg) + + sys.exit(f"Error: Can't build {n_failures} PDF file(s): {failures}") + + def handle_info(self, output_dirs): + """ + Extra steps for Info output. + + For texinfo generation, an additional make is needed from the + texinfo directory. + """ + + for output_dir in output_dirs: + try: + subprocess.run(["make", "info"], cwd=output_dir, check=True) + except subprocess.CalledProcessError as e: + sys.exit(f"Error generating info docs: {e}") + + def handle_man(self, kerneldoc, docs_dir, src_dir, output_dir): + """ + Create man pages from kernel-doc output + """ + + re_kernel_doc = re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)") + re_man = re.compile(r'^\.TH "[^"]*" (\d+) "([^"]*)"') + + if docs_dir == src_dir: + # + # Pick the entire set of kernel-doc markups from the entire tree + # + kdoc_files = set([self.srctree]) + else: + kdoc_files = set() + + for fname in glob(os.path.join(src_dir, "**"), recursive=True): + if os.path.isfile(fname) and fname.endswith(".rst"): + with open(fname, "r", encoding="utf-8") as in_fp: + data = in_fp.read() + + for line in data.split("\n"): + match = re_kernel_doc.match(line) + if match: + if os.path.isfile(match.group(1)): + kdoc_files.add(match.group(1)) + + if not kdoc_files: + sys.exit(f"Directory {src_dir} doesn't contain kernel-doc tags") + + cmd = [ kerneldoc, "-m" ] + sorted(kdoc_files) + try: + if self.verbose: + print(" ".join(cmd)) + + result = subprocess.run(cmd, stdout=subprocess.PIPE, text= True) + + if result.returncode: + print(f"Warning: kernel-doc returned {result.returncode} warnings") + + except (OSError, ValueError, subprocess.SubprocessError) as e: + sys.exit(f"Failed to create man pages for {src_dir}: {repr(e)}") + + fp = None + try: + for line in result.stdout.split("\n"): + match = re_man.match(line) + if not match: + if fp: + fp.write(line + '\n') + continue + + if fp: + fp.close() + + fname = f"{output_dir}/{match.group(2)}.{match.group(1)}" + + if self.verbose: + print(f"Creating {fname}") + fp = open(fname, "w", encoding="utf-8") + fp.write(line + '\n') + finally: + if fp: + fp.close() + + def cleandocs(self, builder): # pylint: disable=W0613 + """Remove documentation output directory""" + shutil.rmtree(self.builddir, ignore_errors=True) + + def build(self, target, sphinxdirs=None, + theme=None, css=None, paper=None, deny_vf=None, + skip_sphinx=False): + """ + Build documentation using Sphinx. This is the core function of this + module. It prepares all arguments required by sphinx-build. + """ + + builder = TARGETS[target]["builder"] + out_dir = TARGETS[target].get("out_dir", "") + + # + # Cleandocs doesn't require sphinx-build + # + if target == "cleandocs": + self.cleandocs(builder) + return + + if theme: + os.environ["DOCS_THEME"] = theme + + # + # Other targets require sphinx-build, so check if it exists + # + if not skip_sphinx: + sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"]) + if not sphinxbuild and target != "mandocs": + sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n") + + if target == "pdfdocs": + if not self.pdflatex_cmd and not self.latexmk_cmd: + sys.exit("Error: pdflatex or latexmk required for PDF generation") + + docs_dir = os.path.abspath(os.path.join(self.srctree, "Documentation")) + + # + # Fill in base arguments for Sphinx build + # + kerneldoc = self.kerneldoc + if kerneldoc.startswith(self.srctree): + kerneldoc = os.path.relpath(kerneldoc, self.srctree) + + args = [ "-b", builder, "-c", docs_dir ] + + if builder == "latex": + if not paper: + paper = PAPER[1] + + args.extend(["-D", f"latex_elements.papersize={paper}paper"]) + + if self.rustdoc: + args.extend(["-t", "rustdoc"]) + + if not sphinxdirs: + sphinxdirs = os.environ.get("SPHINXDIRS", ".") + + # + # The sphinx-build tool has a bug: internally, it tries to set + # locale with locale.setlocale(locale.LC_ALL, ''). This causes a + # crash if language is not set. Detect and fix it. + # + try: + locale.setlocale(locale.LC_ALL, '') + except locale.Error: + self.env["LC_ALL"] = "C" + + # + # sphinxdirs can be a list or a whitespace-separated string + # + sphinxdirs_list = [] + for sphinxdir in sphinxdirs: + if isinstance(sphinxdir, list): + sphinxdirs_list += sphinxdir + else: + sphinxdirs_list += sphinxdir.split() + + # + # Step 1: Build each directory in separate. + # + # This is not the best way of handling it, as cross-references between + # them will be broken, but this is what we've been doing since + # the beginning. + # + output_dirs = [] + for sphinxdir in sphinxdirs_list: + src_dir = os.path.join(docs_dir, sphinxdir) + doctree_dir = os.path.join(self.builddir, ".doctrees") + output_dir = os.path.join(self.builddir, sphinxdir, out_dir) + + # + # Make directory names canonical + # + src_dir = os.path.normpath(src_dir) + doctree_dir = os.path.normpath(doctree_dir) + output_dir = os.path.normpath(output_dir) + + os.makedirs(doctree_dir, exist_ok=True) + os.makedirs(output_dir, exist_ok=True) + + output_dirs.append(output_dir) + + build_args = args + [ + "-d", doctree_dir, + "-D", f"kerneldoc_bin={kerneldoc}", + "-D", f"version={self.kernelversion}", + "-D", f"release={self.kernelrelease}", + "-D", f"kerneldoc_srctree={self.srctree}", + src_dir, + output_dir, + ] + + if target == "mandocs": + self.handle_man(kerneldoc, docs_dir, src_dir, output_dir) + elif not skip_sphinx: + try: + result = self.run_sphinx(sphinxbuild, build_args, + env=self.env) + + if result: + sys.exit(f"Build failed: return code: {result}") + + except (OSError, ValueError, subprocess.SubprocessError) as e: + sys.exit(f"Build failed: {repr(e)}") + + # + # Ensure that each html/epub output will have needed static files + # + if target in ["htmldocs", "epubdocs"]: + self.handle_html(css, output_dir) + + # + # Step 2: Some targets (PDF and info) require an extra step once + # sphinx-build finishes + # + if target == "pdfdocs": + self.handle_pdf(output_dirs, deny_vf) + elif target == "infodocs": + self.handle_info(output_dirs) + +def jobs_type(value): + """ + Handle valid values for -j. Accepts Sphinx "-jauto", plus a number + equal or bigger than one. + """ + if value is None: + return None + + if value.lower() == 'auto': + return value.lower() + + try: + if int(value) >= 1: + return value + + raise argparse.ArgumentTypeError(f"Minimum jobs is 1, got {value}") + except ValueError: + raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}") # pylint: disable=W0707 + +def main(): + """ + Main function. The only mandatory argument is the target. If not + specified, the other arguments will use default values if not + specified at os.environ. + """ + parser = argparse.ArgumentParser(description="Kernel documentation builder") + + parser.add_argument("target", choices=list(TARGETS.keys()), + help="Documentation target to build") + parser.add_argument("--sphinxdirs", nargs="+", + help="Specific directories to build") + parser.add_argument("--builddir", default="output", + help="Sphinx configuration file") + + parser.add_argument("--theme", help="Sphinx theme to use") + + parser.add_argument("--css", help="Custom CSS file for HTML/EPUB") + + parser.add_argument("--paper", choices=PAPER, default=PAPER[0], + help="Paper size for LaTeX/PDF output") + + parser.add_argument('--deny-vf', + help="Configuration to deny variable fonts on pdf builds") + + parser.add_argument("-v", "--verbose", action='store_true', + help="place build in verbose mode") + + parser.add_argument('-j', '--jobs', type=jobs_type, + help="Sets number of jobs to use with sphinx-build") + + parser.add_argument('-i', '--interactive', action='store_true', + help="Change latex default to run in interactive mode") + + parser.add_argument('-s', '--skip-sphinx-build', action='store_true', + help="Skip sphinx-build step") + + parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}', + default=None, + help=f'If used, run Sphinx from a venv dir (default dir: {VENV_DEFAULT})') + + args = parser.parse_args() + + PythonVersion.check_python(MIN_PYTHON_VERSION, show_alternatives=True, + bail_out=True) + + builder = SphinxBuilder(builddir=args.builddir, venv=args.venv, + verbose=args.verbose, n_jobs=args.jobs, + interactive=args.interactive) + + builder.build(args.target, sphinxdirs=args.sphinxdirs, + theme=args.theme, css=args.css, paper=args.paper, + deny_vf=args.deny_vf, + skip_sphinx=args.skip_sphinx_build) + +if __name__ == "__main__": + main() diff --git a/scripts/sphinx-pre-install b/tools/docs/sphinx-pre-install similarity index 93% rename from scripts/sphinx-pre-install rename to tools/docs/sphinx-pre-install index 954ed3dc0645..965c9b093a41 100755 --- a/scripts/sphinx-pre-install +++ b/tools/docs/sphinx-pre-install @@ -26,26 +26,20 @@ system pacage install is recommended. """ import argparse +import locale import os import re import subprocess import sys from glob import glob +import os.path +src_dir = os.path.dirname(os.path.realpath(__file__)) +sys.path.insert(0, os.path.join(src_dir, '../lib/python')) +from kdoc.python_version import PythonVersion -def parse_version(version): - """Convert a major.minor.patch version into a tuple""" - return tuple(int(x) for x in version.split(".")) - - -def ver_str(version): - """Returns a version tuple as major.minor.patch""" - - return ".".join([str(x) for x in version]) - - -RECOMMENDED_VERSION = parse_version("3.4.3") -MIN_PYTHON_VERSION = parse_version("3.7") +RECOMMENDED_VERSION = PythonVersion("3.4.3").version +MIN_PYTHON_VERSION = PythonVersion("3.7").version class DepManager: @@ -235,95 +229,11 @@ class AncillaryMethods: return None - @staticmethod - def get_python_version(cmd): - """ - Get python version from a Python binary. As we need to detect if - are out there newer python binaries, we can't rely on sys.release here. - """ - - result = SphinxDependencyChecker.run([cmd, "--version"], - capture_output=True, text=True) - version = result.stdout.strip() - - match = re.search(r"(\d+\.\d+\.\d+)", version) - if match: - return parse_version(match.group(1)) - - print(f"Can't parse version {version}") - return (0, 0, 0) - - @staticmethod - def find_python(): - """ - Detect if are out there any python 3.xy version newer than the - current one. - - Note: this routine is limited to up to 2 digits for python3. We - may need to update it one day, hopefully on a distant future. - """ - patterns = [ - "python3.[0-9]", - "python3.[0-9][0-9]", - ] - - # Seek for a python binary newer than MIN_PYTHON_VERSION - for path in os.getenv("PATH", "").split(":"): - for pattern in patterns: - for cmd in glob(os.path.join(path, pattern)): - if os.path.isfile(cmd) and os.access(cmd, os.X_OK): - version = SphinxDependencyChecker.get_python_version(cmd) - if version >= MIN_PYTHON_VERSION: - return cmd - - @staticmethod - def check_python(): - """ - Check if the current python binary satisfies our minimal requirement - for Sphinx build. If not, re-run with a newer version if found. - """ - cur_ver = sys.version_info[:3] - if cur_ver >= MIN_PYTHON_VERSION: - ver = ver_str(cur_ver) - print(f"Python version: {ver}") - - # This could be useful for debugging purposes - if SphinxDependencyChecker.which("docutils"): - result = SphinxDependencyChecker.run(["docutils", "--version"], - capture_output=True, text=True) - ver = result.stdout.strip() - match = re.search(r"(\d+\.\d+\.\d+)", ver) - if match: - ver = match.group(1) - - print(f"Docutils version: {ver}") - - return - - python_ver = ver_str(cur_ver) - - new_python_cmd = SphinxDependencyChecker.find_python() - if not new_python_cmd: - print(f"ERROR: Python version {python_ver} is not spported anymore\n") - print(" Can't find a new version. This script may fail") - return - - # Restart script using the newer version - script_path = os.path.abspath(sys.argv[0]) - args = [new_python_cmd, script_path] + sys.argv[1:] - - print(f"Python {python_ver} not supported. Changing to {new_python_cmd}") - - try: - os.execv(new_python_cmd, args) - except OSError as e: - sys.exit(f"Failed to restart with {new_python_cmd}: {e}") - @staticmethod def run(*args, **kwargs): """ Excecute a command, hiding its output by default. - Preserve comatibility with older Python versions. + Preserve compatibility with older Python versions. """ capture_output = kwargs.pop('capture_output', False) @@ -406,7 +316,7 @@ class MissingCheckers(AncillaryMethods): Right now, we still need Perl for doc build, as it is required by some tools called at docs or kernel build time, like: - scripts/documentation-file-ref-check + tools/docs/documentation-file-ref-check Also, checkpatch is on Perl. """ @@ -516,8 +426,19 @@ class MissingCheckers(AncillaryMethods): """ Gets sphinx-build version. """ + env = os.environ.copy() + + # The sphinx-build tool has a bug: internally, it tries to set + # locale with locale.setlocale(locale.LC_ALL, ''). This causes a + # crash if language is not set. Detect and fix it. try: - result = self.run([cmd, "--version"], + locale.setlocale(locale.LC_ALL, '') + except Exception: + env["LC_ALL"] = "C" + env["LANG"] = "C" + + try: + result = self.run([cmd, "--version"], env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, check=True) @@ -527,11 +448,11 @@ class MissingCheckers(AncillaryMethods): for line in result.stdout.split("\n"): match = re.match(r"^sphinx-build\s+([\d\.]+)(?:\+(?:/[\da-f]+)|b\d+)?\s*$", line) if match: - return parse_version(match.group(1)) + return PythonVersion.parse_version(match.group(1)) match = re.match(r"^Sphinx.*\s+([\d\.]+)\s*$", line) if match: - return parse_version(match.group(1)) + return PythonVersion.parse_version(match.group(1)) def check_sphinx(self, conf): """ @@ -542,7 +463,7 @@ class MissingCheckers(AncillaryMethods): for line in f: match = re.match(r"^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]", line) if match: - self.min_version = parse_version(match.group(1)) + self.min_version = PythonVersion.parse_version(match.group(1)) break except IOError: sys.exit(f"Can't open {conf}") @@ -562,8 +483,8 @@ class MissingCheckers(AncillaryMethods): sys.exit(f"{sphinx} didn't return its version") if self.cur_version < self.min_version: - curver = ver_str(self.cur_version) - minver = ver_str(self.min_version) + curver = PythonVersion.ver_str(self.cur_version) + minver = PythonVersion.ver_str(self.min_version) print(f"ERROR: Sphinx version is {curver}. It should be >= {minver}") self.need_sphinx = 1 @@ -1304,7 +1225,7 @@ class SphinxDependencyChecker(MissingCheckers): else: if self.need_sphinx and ver >= self.min_version: return (f, ver) - elif parse_version(ver) > self.cur_version: + elif PythonVersion.parse_version(ver) > self.cur_version: return (f, ver) return ("", ver) @@ -1411,7 +1332,7 @@ class SphinxDependencyChecker(MissingCheckers): return if self.latest_avail_ver: - latest_avail_ver = ver_str(self.latest_avail_ver) + latest_avail_ver = PythonVersion.ver_str(self.latest_avail_ver) if not self.need_sphinx: # sphinx-build is present and its version is >= $min_version @@ -1507,7 +1428,7 @@ class SphinxDependencyChecker(MissingCheckers): else: print("Unknown OS") if self.cur_version != (0, 0, 0): - ver = ver_str(self.cur_version) + ver = PythonVersion.ver_str(self.cur_version) print(f"Sphinx version: {ver}\n") # Check the type of virtual env, depending on Python version @@ -1613,7 +1534,8 @@ def main(): checker = SphinxDependencyChecker(args) - checker.check_python() + PythonVersion.check_python(MIN_PYTHON_VERSION, + bail_out=True, success_on_error=True) checker.check_needs() # Call main if not used as module diff --git a/scripts/test_doc_build.py b/tools/docs/test_doc_build.py similarity index 100% rename from scripts/test_doc_build.py rename to tools/docs/test_doc_build.py diff --git a/tools/docs/lib/__init__.py b/tools/lib/python/__init__.py similarity index 100% rename from tools/docs/lib/__init__.py rename to tools/lib/python/__init__.py diff --git a/tools/lib/python/abi/__init__.py b/tools/lib/python/abi/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/scripts/lib/abi/abi_parser.py b/tools/lib/python/abi/abi_parser.py similarity index 99% rename from scripts/lib/abi/abi_parser.py rename to tools/lib/python/abi/abi_parser.py index 66a738013ce1..9b8db70067ef 100644 --- a/scripts/lib/abi/abi_parser.py +++ b/tools/lib/python/abi/abi_parser.py @@ -17,7 +17,7 @@ from random import randrange, seed # Import Python modules -from helpers import AbiDebug, ABI_DIR +from abi.helpers import AbiDebug, ABI_DIR class AbiParser: diff --git a/scripts/lib/abi/abi_regex.py b/tools/lib/python/abi/abi_regex.py similarity index 99% rename from scripts/lib/abi/abi_regex.py rename to tools/lib/python/abi/abi_regex.py index 8a57846cbc69..d5553206de3c 100644 --- a/scripts/lib/abi/abi_regex.py +++ b/tools/lib/python/abi/abi_regex.py @@ -12,8 +12,8 @@ import sys from pprint import pformat -from abi_parser import AbiParser -from helpers import AbiDebug +from abi.abi_parser import AbiParser +from abi.helpers import AbiDebug class AbiRegex(AbiParser): """Extends AbiParser to search ABI nodes with regular expressions""" diff --git a/scripts/lib/abi/helpers.py b/tools/lib/python/abi/helpers.py similarity index 100% rename from scripts/lib/abi/helpers.py rename to tools/lib/python/abi/helpers.py diff --git a/scripts/lib/abi/system_symbols.py b/tools/lib/python/abi/system_symbols.py similarity index 99% rename from scripts/lib/abi/system_symbols.py rename to tools/lib/python/abi/system_symbols.py index f15c94a6e33c..4a2554da217b 100644 --- a/scripts/lib/abi/system_symbols.py +++ b/tools/lib/python/abi/system_symbols.py @@ -15,7 +15,7 @@ from concurrent import futures from datetime import datetime from random import shuffle -from helpers import AbiDebug +from abi.helpers import AbiDebug class SystemSymbols: """Stores arguments for the class and initialize class vars""" diff --git a/tools/lib/python/feat/parse_features.py b/tools/lib/python/feat/parse_features.py new file mode 100755 index 000000000000..b88c04d3e2fe --- /dev/null +++ b/tools/lib/python/feat/parse_features.py @@ -0,0 +1,494 @@ +#!/usr/bin/env python3 +# pylint: disable=R0902,R0911,R0912,R0914,R0915 +# Copyright(c) 2025: Mauro Carvalho Chehab . +# SPDX-License-Identifier: GPL-2.0 + + +""" +Library to parse the Linux Feature files and produce a ReST book. +""" + +import os +import re +import sys + +from glob import iglob + + +class ParseFeature: + """ + Parses Documentation/features, allowing to generate ReST documentation + from it. + """ + + h_name = "Feature" + h_kconfig = "Kconfig" + h_description = "Description" + h_subsys = "Subsystem" + h_status = "Status" + h_arch = "Architecture" + + # Sort order for status. Others will be mapped at the end. + status_map = { + "ok": 0, + "TODO": 1, + "N/A": 2, + # The only missing status is "..", which was mapped as "---", + # as this is an special ReST cell value. Let it get the + # default order (99). + } + + def __init__(self, prefix, debug=0, enable_fname=False): + """ + Sets internal variables + """ + + self.prefix = prefix + self.debug = debug + self.enable_fname = enable_fname + + self.data = {} + + # Initial maximum values use just the headers + self.max_size_name = len(self.h_name) + self.max_size_kconfig = len(self.h_kconfig) + self.max_size_description = len(self.h_description) + self.max_size_desc_word = 0 + self.max_size_subsys = len(self.h_subsys) + self.max_size_status = len(self.h_status) + self.max_size_arch = len(self.h_arch) + self.max_size_arch_with_header = self.max_size_arch + self.max_size_arch + self.description_size = 1 + + self.msg = "" + + def emit(self, msg="", end="\n"): + self.msg += msg + end + + def parse_error(self, fname, ln, msg, data=None): + """ + Displays an error message, printing file name and line + """ + + if ln: + fname += f"#{ln}" + + print(f"Warning: file {fname}: {msg}", file=sys.stderr, end="") + + if data: + data = data.rstrip() + print(f":\n\t{data}", file=sys.stderr) + else: + print("", file=sys.stderr) + + def parse_feat_file(self, fname): + """Parses a single arch-support.txt feature file""" + + if os.path.isdir(fname): + return + + base = os.path.basename(fname) + + if base != "arch-support.txt": + if self.debug: + print(f"ignoring {fname}", file=sys.stderr) + return + + subsys = os.path.dirname(fname).split("/")[-2] + self.max_size_subsys = max(self.max_size_subsys, len(subsys)) + + feature_name = "" + kconfig = "" + description = "" + comments = "" + arch_table = {} + + if self.debug > 1: + print(f"Opening {fname}", file=sys.stderr) + + if self.enable_fname: + full_fname = os.path.abspath(fname) + self.emit(f".. FILE {full_fname}") + + with open(fname, encoding="utf-8") as f: + for ln, line in enumerate(f, start=1): + line = line.strip() + + match = re.match(r"^\#\s+Feature\s+name:\s*(.*\S)", line) + if match: + feature_name = match.group(1) + + self.max_size_name = max(self.max_size_name, + len(feature_name)) + continue + + match = re.match(r"^\#\s+Kconfig:\s*(.*\S)", line) + if match: + kconfig = match.group(1) + + self.max_size_kconfig = max(self.max_size_kconfig, + len(kconfig)) + continue + + match = re.match(r"^\#\s+description:\s*(.*\S)", line) + if match: + description = match.group(1) + + self.max_size_description = max(self.max_size_description, + len(description)) + + words = re.split(r"\s+", line)[1:] + for word in words: + self.max_size_desc_word = max(self.max_size_desc_word, + len(word)) + + continue + + if re.search(r"^\\s*$", line): + continue + + if re.match(r"^\s*\-+\s*$", line): + continue + + if re.search(r"^\s*\|\s*arch\s*\|\s*status\s*\|\s*$", line): + continue + + match = re.match(r"^\#\s*(.*)$", line) + if match: + comments += match.group(1) + continue + + match = re.match(r"^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$", line) + if match: + arch = match.group(1) + status = match.group(2) + + self.max_size_status = max(self.max_size_status, + len(status)) + self.max_size_arch = max(self.max_size_arch, len(arch)) + + if status == "..": + status = "---" + + arch_table[arch] = status + + continue + + self.parse_error(fname, ln, "Line is invalid", line) + + if not feature_name: + self.parse_error(fname, 0, "Feature name not found") + return + if not subsys: + self.parse_error(fname, 0, "Subsystem not found") + return + if not kconfig: + self.parse_error(fname, 0, "Kconfig not found") + return + if not description: + self.parse_error(fname, 0, "Description not found") + return + if not arch_table: + self.parse_error(fname, 0, "Architecture table not found") + return + + self.data[feature_name] = { + "where": fname, + "subsys": subsys, + "kconfig": kconfig, + "description": description, + "comments": comments, + "table": arch_table, + } + + self.max_size_arch_with_header = self.max_size_arch + len(self.h_arch) + + def parse(self): + """Parses all arch-support.txt feature files inside self.prefix""" + + path = os.path.expanduser(self.prefix) + + if self.debug > 2: + print(f"Running parser for {path}") + + example_path = os.path.join(path, "arch-support.txt") + + for fname in iglob(os.path.join(path, "**"), recursive=True): + if fname != example_path: + self.parse_feat_file(fname) + + return self.data + + def output_arch_table(self, arch, feat=None): + """ + Output feature(s) for a given architecture. + """ + + title = f"Feature status on {arch} architecture" + + self.emit("=" * len(title)) + self.emit(title) + self.emit("=" * len(title)) + self.emit() + + self.emit("=" * self.max_size_subsys + " ", end="") + self.emit("=" * self.max_size_name + " ", end="") + self.emit("=" * self.max_size_kconfig + " ", end="") + self.emit("=" * self.max_size_status + " ", end="") + self.emit("=" * self.max_size_description) + + self.emit(f"{self.h_subsys:<{self.max_size_subsys}} ", end="") + self.emit(f"{self.h_name:<{self.max_size_name}} ", end="") + self.emit(f"{self.h_kconfig:<{self.max_size_kconfig}} ", end="") + self.emit(f"{self.h_status:<{self.max_size_status}} ", end="") + self.emit(f"{self.h_description:<{self.max_size_description}}") + + self.emit("=" * self.max_size_subsys + " ", end="") + self.emit("=" * self.max_size_name + " ", end="") + self.emit("=" * self.max_size_kconfig + " ", end="") + self.emit("=" * self.max_size_status + " ", end="") + self.emit("=" * self.max_size_description) + + sorted_features = sorted(self.data.keys(), + key=lambda x: (self.data[x]["subsys"], + x.lower())) + + for name in sorted_features: + if feat and name != feat: + continue + + arch_table = self.data[name]["table"] + + if not arch in arch_table: + continue + + self.emit(f"{self.data[name]['subsys']:<{self.max_size_subsys}} ", + end="") + self.emit(f"{name:<{self.max_size_name}} ", end="") + self.emit(f"{self.data[name]['kconfig']:<{self.max_size_kconfig}} ", + end="") + self.emit(f"{arch_table[arch]:<{self.max_size_status}} ", + end="") + self.emit(f"{self.data[name]['description']}") + + self.emit("=" * self.max_size_subsys + " ", end="") + self.emit("=" * self.max_size_name + " ", end="") + self.emit("=" * self.max_size_kconfig + " ", end="") + self.emit("=" * self.max_size_status + " ", end="") + self.emit("=" * self.max_size_description) + + return self.msg + + def output_feature(self, feat): + """ + Output a feature on all architectures + """ + + title = f"Feature {feat}" + + self.emit("=" * len(title)) + self.emit(title) + self.emit("=" * len(title)) + self.emit() + + if not feat in self.data: + return + + if self.data[feat]["subsys"]: + self.emit(f":Subsystem: {self.data[feat]['subsys']}") + if self.data[feat]["kconfig"]: + self.emit(f":Kconfig: {self.data[feat]['kconfig']}") + + desc = self.data[feat]["description"] + desc = desc[0].upper() + desc[1:] + desc = desc.rstrip(". \t") + self.emit(f"\n{desc}.\n") + + com = self.data[feat]["comments"].strip() + if com: + self.emit("Comments") + self.emit("--------") + self.emit(f"\n{com}\n") + + self.emit("=" * self.max_size_arch + " ", end="") + self.emit("=" * self.max_size_status) + + self.emit(f"{self.h_arch:<{self.max_size_arch}} ", end="") + self.emit(f"{self.h_status:<{self.max_size_status}}") + + self.emit("=" * self.max_size_arch + " ", end="") + self.emit("=" * self.max_size_status) + + arch_table = self.data[feat]["table"] + for arch in sorted(arch_table.keys()): + self.emit(f"{arch:<{self.max_size_arch}} ", end="") + self.emit(f"{arch_table[arch]:<{self.max_size_status}}") + + self.emit("=" * self.max_size_arch + " ", end="") + self.emit("=" * self.max_size_status) + + return self.msg + + def matrix_lines(self, desc_size, max_size_status, header): + """ + Helper function to split element tables at the output matrix + """ + + if header: + ln_marker = "=" + else: + ln_marker = "-" + + self.emit("+" + ln_marker * self.max_size_name + "+", end="") + self.emit(ln_marker * desc_size, end="") + self.emit("+" + ln_marker * max_size_status + "+") + + def output_matrix(self): + """ + Generates a set of tables, groped by subsystem, containing + what's the feature state on each architecture. + """ + + title = "Feature status on all architectures" + + self.emit("=" * len(title)) + self.emit(title) + self.emit("=" * len(title)) + self.emit() + + desc_title = f"{self.h_kconfig} / {self.h_description}" + + desc_size = self.max_size_kconfig + 4 + if not self.description_size: + desc_size = max(self.max_size_description, desc_size) + else: + desc_size = max(self.description_size, desc_size) + + desc_size = max(self.max_size_desc_word, desc_size, len(desc_title)) + + notcompat = "Not compatible" + self.max_size_status = max(self.max_size_status, len(notcompat)) + + min_status_size = self.max_size_status + self.max_size_arch + 4 + max_size_status = max(min_status_size, self.max_size_status) + + h_status_per_arch = "Status per architecture" + max_size_status = max(max_size_status, len(h_status_per_arch)) + + cur_subsys = None + for name in sorted(self.data.keys(), + key=lambda x: (self.data[x]["subsys"], x.lower())): + if not cur_subsys or cur_subsys != self.data[name]["subsys"]: + if cur_subsys: + self.emit() + + cur_subsys = self.data[name]["subsys"] + + title = f"Subsystem: {cur_subsys}" + self.emit(title) + self.emit("=" * len(title)) + self.emit() + + self.matrix_lines(desc_size, max_size_status, 0) + + self.emit(f"|{self.h_name:<{self.max_size_name}}", end="") + self.emit(f"|{desc_title:<{desc_size}}", end="") + self.emit(f"|{h_status_per_arch:<{max_size_status}}|") + + self.matrix_lines(desc_size, max_size_status, 1) + + lines = [] + descs = [] + cur_status = "" + line = "" + + arch_table = sorted(self.data[name]["table"].items(), + key=lambda x: (self.status_map.get(x[1], 99), + x[0].lower())) + + for arch, status in arch_table: + if status == "---": + status = notcompat + + if status != cur_status: + if line != "": + lines.append(line) + line = "" + line = f"- **{status}**: {arch}" + elif len(line) + len(arch) + 2 < max_size_status: + line += f", {arch}" + else: + lines.append(line) + line = f" {arch}" + cur_status = status + + if line != "": + lines.append(line) + + description = self.data[name]["description"] + while len(description) > desc_size: + desc_line = description[:desc_size] + + last_space = desc_line.rfind(" ") + if last_space != -1: + desc_line = desc_line[:last_space] + descs.append(desc_line) + description = description[last_space + 1:] + else: + desc_line = desc_line[:-1] + descs.append(desc_line + "\\") + description = description[len(desc_line):] + + if description: + descs.append(description) + + while len(lines) < 2 + len(descs): + lines.append("") + + for ln, line in enumerate(lines): + col = ["", ""] + + if not ln: + col[0] = name + col[1] = f"``{self.data[name]['kconfig']}``" + else: + if ln >= 2 and descs: + col[1] = descs.pop(0) + + self.emit(f"|{col[0]:<{self.max_size_name}}", end="") + self.emit(f"|{col[1]:<{desc_size}}", end="") + self.emit(f"|{line:<{max_size_status}}|") + + self.matrix_lines(desc_size, max_size_status, 0) + + return self.msg + + def list_arch_features(self, arch, feat): + """ + Print a matrix of kernel feature support for the chosen architecture. + """ + self.emit("#") + self.emit(f"# Kernel feature support matrix of the '{arch}' architecture:") + self.emit("#") + + # Sort by subsystem, then by feature name (case‑insensitive) + for name in sorted(self.data.keys(), + key=lambda n: (self.data[n]["subsys"].lower(), + n.lower())): + if feat and name != feat: + continue + + feature = self.data[name] + arch_table = feature["table"] + status = arch_table.get(arch, "") + status = " " * ((4 - len(status)) // 2) + status + + self.emit(f"{feature['subsys']:>{self.max_size_subsys + 1}}/ ", + end="") + self.emit(f"{name:<{self.max_size_name}}: ", end="") + self.emit(f"{status:<5}| ", end="") + self.emit(f"{feature['kconfig']:>{self.max_size_kconfig}} ", + end="") + self.emit(f"# {feature['description']}") + + return self.msg diff --git a/tools/lib/python/jobserver.py b/tools/lib/python/jobserver.py new file mode 100755 index 000000000000..a24f30ef4fa8 --- /dev/null +++ b/tools/lib/python/jobserver.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0+ +# +# pylint: disable=C0103,C0209 +# +# + +""" +Interacts with the POSIX jobserver during the Kernel build time. + +A "normal" jobserver task, like the one initiated by a make subrocess would do: + + - open read/write file descriptors to communicate with the job server; + - ask for one slot by calling: + claim = os.read(reader, 1) + - when the job finshes, call: + os.write(writer, b"+") # os.write(writer, claim) + +Here, the goal is different: This script aims to get the remaining number +of slots available, using all of them to run a command which handle tasks in +parallel. To to that, it has a loop that ends only after there are no +slots left. It then increments the number by one, in order to allow a +call equivalent to make -j$((claim+1)), e.g. having a parent make creating +$claim child to do the actual work. + +The end goal here is to keep the total number of build tasks under the +limit established by the initial make -j$n_proc call. + +See: + https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver +""" + +import errno +import os +import subprocess +import sys + +class JobserverExec: + """ + Claim all slots from make using POSIX Jobserver. + + The main methods here are: + - open(): reserves all slots; + - close(): method returns all used slots back to make; + - run(): executes a command setting PARALLELISM= + """ + + def __init__(self): + """Initialize internal vars""" + self.claim = 0 + self.jobs = b"" + self.reader = None + self.writer = None + self.is_open = False + + def open(self): + """Reserve all available slots to be claimed later on""" + + if self.is_open: + return + + try: + # Fetch the make environment options. + flags = os.environ["MAKEFLAGS"] + # Look for "--jobserver=R,W" + # Note that GNU Make has used --jobserver-fds and --jobserver-auth + # so this handles all of them. + opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] + + # Parse out R,W file descriptor numbers and set them nonblocking. + # If the MAKEFLAGS variable contains multiple instances of the + # --jobserver-auth= option, the last one is relevant. + fds = opts[-1].split("=", 1)[1] + + # Starting with GNU Make 4.4, named pipes are used for reader + # and writer. + # Example argument: --jobserver-auth=fifo:/tmp/GMfifo8134 + _, _, path = fds.partition("fifo:") + + if path: + self.reader = os.open(path, os.O_RDONLY | os.O_NONBLOCK) + self.writer = os.open(path, os.O_WRONLY) + else: + self.reader, self.writer = [int(x) for x in fds.split(",", 1)] + # Open a private copy of reader to avoid setting nonblocking + # on an unexpecting process with the same reader fd. + self.reader = os.open("/proc/self/fd/%d" % (self.reader), + os.O_RDONLY | os.O_NONBLOCK) + + # Read out as many jobserver slots as possible + while True: + try: + slot = os.read(self.reader, 8) + self.jobs += slot + except (OSError, IOError) as e: + if e.errno == errno.EWOULDBLOCK: + # Stop at the end of the jobserver queue. + break + # If something went wrong, give back the jobs. + if self.jobs: + os.write(self.writer, self.jobs) + raise e + + # Add a bump for our caller's reserveration, since we're just going + # to sit here blocked on our child. + self.claim = len(self.jobs) + 1 + + except (KeyError, IndexError, ValueError, OSError, IOError): + # Any missing environment strings or bad fds should result in just + # not being parallel. + self.claim = None + + self.is_open = True + + def close(self): + """Return all reserved slots to Jobserver""" + + if not self.is_open: + return + + # Return all the reserved slots. + if len(self.jobs): + os.write(self.writer, self.jobs) + + self.is_open = False + + def __enter__(self): + self.open() + return self + + def __exit__(self, exc_type, exc_value, exc_traceback): + self.close() + + def run(self, cmd, *args, **pwargs): + """ + Run a command setting PARALLELISM env variable to the number of + available job slots (claim) + 1, e.g. it will reserve claim slots + to do the actual build work, plus one to monitor its children. + """ + self.open() # Ensure that self.claim is set + + # We can only claim parallelism if there was a jobserver (i.e. a + # top-level "-jN" argument) and there were no other failures. Otherwise + # leave out the environment variable and let the child figure out what + # is best. + if self.claim: + os.environ["PARALLELISM"] = str(self.claim) + + return subprocess.call(cmd, *args, **pwargs) diff --git a/tools/lib/python/kdoc/__init__.py b/tools/lib/python/kdoc/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/tools/docs/lib/enrich_formatter.py b/tools/lib/python/kdoc/enrich_formatter.py similarity index 100% rename from tools/docs/lib/enrich_formatter.py rename to tools/lib/python/kdoc/enrich_formatter.py diff --git a/scripts/lib/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py similarity index 95% rename from scripts/lib/kdoc/kdoc_files.py rename to tools/lib/python/kdoc/kdoc_files.py index 9e09b45b02fa..bfe02baf1606 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/tools/lib/python/kdoc/kdoc_files.py @@ -13,8 +13,8 @@ import logging import os import re -from kdoc_parser import KernelDoc -from kdoc_output import OutputFormat +from kdoc.kdoc_parser import KernelDoc +from kdoc.kdoc_output import OutputFormat class GlobSourceFiles: @@ -49,7 +49,7 @@ class GlobSourceFiles: for entry in obj: name = os.path.join(dirname, entry.name) - if entry.is_dir(): + if entry.is_dir(follow_symlinks=False): yield from self._parse_dir(name) if not entry.is_file(): @@ -64,7 +64,7 @@ class GlobSourceFiles: def parse_files(self, file_list, file_not_found_cb): """ - Define an interator to parse all source files from file_list, + Define an iterator to parse all source files from file_list, handling directories if any """ @@ -229,7 +229,7 @@ class KernelFiles(): Return output messages from a file name using the output style filtering. - If output type was not handled by the syler, return None. + If output type was not handled by the styler, return None. """ # NOTE: we can add rules here to filter out unwanted parts, @@ -275,7 +275,10 @@ class KernelFiles(): self.config.log.warning("No kernel-doc for file %s", fname) continue - for arg in self.results[fname]: + symbols = self.results[fname] + self.out_style.set_symbols(symbols) + + for arg in symbols: m = self.out_msg(fname, arg.name, arg) if m is None: diff --git a/scripts/lib/kdoc/kdoc_item.py b/tools/lib/python/kdoc/kdoc_item.py similarity index 93% rename from scripts/lib/kdoc/kdoc_item.py rename to tools/lib/python/kdoc/kdoc_item.py index b3b225764550..19805301cb2c 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/tools/lib/python/kdoc/kdoc_item.py @@ -5,8 +5,9 @@ # class KdocItem: - def __init__(self, name, type, start_line, **other_stuff): + def __init__(self, name, fname, type, start_line, **other_stuff): self.name = name + self.fname = fname self.type = type self.declaration_start_line = start_line self.sections = {} diff --git a/scripts/lib/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py similarity index 88% rename from scripts/lib/kdoc/kdoc_output.py rename to tools/lib/python/kdoc/kdoc_output.py index ea8914537ba0..b1aaa7fc3604 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -8,7 +8,7 @@ Implement output filters to print kernel-doc documentation. The implementation uses a virtual base class (OutputFormat) which -contains a dispatches to virtual methods, and some code to filter +contains dispatches to virtual methods, and some code to filter out output messages. The actual implementation is done on one separate class per each type @@ -19,8 +19,8 @@ import os import re from datetime import datetime -from kdoc_parser import KernelDoc, type_param -from kdoc_re import KernRe +from kdoc.kdoc_parser import KernelDoc, type_param +from kdoc.kdoc_re import KernRe function_pointer = KernRe(r"([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)", cache=False) @@ -59,7 +59,7 @@ class OutputFormat: OUTPUT_EXPORTED = 2 # output exported symbols OUTPUT_INTERNAL = 3 # output non-exported symbols - # Virtual member to be overriden at the inherited classes + # Virtual member to be overridden at the inherited classes highlights = [] def __init__(self): @@ -85,7 +85,7 @@ class OutputFormat: def set_filter(self, export, internal, symbol, nosymbol, function_table, enable_lineno, no_doc_sections): """ - Initialize filter variables according with the requested mode. + Initialize filter variables according to the requested mode. Only one choice is valid between export, internal and symbol. @@ -208,13 +208,16 @@ class OutputFormat: return self.data # Warn if some type requires an output logic - self.config.log.warning("doesn't now how to output '%s' block", + self.config.log.warning("doesn't know how to output '%s' block", dtype) return None # Virtual methods to be overridden by inherited classes # At the base class, those do nothing. + def set_symbols(self, symbols): + """Get a list of all symbols from kernel_doc""" + def out_doc(self, fname, name, args): """Outputs a DOC block""" @@ -577,6 +580,7 @@ class ManFormat(OutputFormat): super().__init__() self.modulename = modulename + self.symbols = [] dt = None tstamp = os.environ.get("KBUILD_BUILD_TIMESTAMP") @@ -593,6 +597,69 @@ class ManFormat(OutputFormat): self.man_date = dt.strftime("%B %Y") + def arg_name(self, args, name): + """ + Return the name that will be used for the man page. + + As we may have the same name on different namespaces, + prepend the data type for all types except functions and typedefs. + + The doc section is special: it uses the modulename. + """ + + dtype = args.type + + if dtype == "doc": + return self.modulename + + if dtype in ["function", "typedef"]: + return name + + return f"{dtype} {name}" + + def set_symbols(self, symbols): + """ + Get a list of all symbols from kernel_doc. + + Man pages will uses it to add a SEE ALSO section with other + symbols at the same file. + """ + self.symbols = symbols + + def out_tail(self, fname, name, args): + """Adds a tail for all man pages""" + + # SEE ALSO section + self.data += f'.SH "SEE ALSO"' + "\n.PP\n" + self.data += (f"Kernel file \\fB{args.fname}\\fR\n") + if len(self.symbols) >= 2: + cur_name = self.arg_name(args, name) + + related = [] + for arg in self.symbols: + out_name = self.arg_name(arg, arg.name) + + if cur_name == out_name: + continue + + related.append(f"\\fB{out_name}\\fR(9)") + + self.data += ",\n".join(related) + "\n" + + # TODO: does it make sense to add other sections? Maybe + # REPORTING ISSUES? LICENSE? + + def msg(self, fname, name, args): + """ + Handles a single entry from kernel-doc parser. + + Add a tail at the end of man pages output. + """ + super().msg(fname, name, args) + self.out_tail(fname, name, args) + + return self.data + def output_highlight(self, block): """ Outputs a C symbol that may require being highlighted with @@ -618,7 +685,9 @@ class ManFormat(OutputFormat): if not self.check_doc(name, args): return - self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n" + out_name = self.arg_name(args, name) + + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" for section, text in args.sections.items(): self.data += f'.SH "{section}"' + "\n" @@ -627,7 +696,9 @@ class ManFormat(OutputFormat): def out_function(self, fname, name, args): """output function in man""" - self.data += f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" + out_name = self.arg_name(args, name) + + self.data += f'.TH "{name}" 9 "{out_name}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" self.data += ".SH NAME\n" self.data += f"{name} \\- {args['purpose']}\n" @@ -671,7 +742,9 @@ class ManFormat(OutputFormat): self.output_highlight(text) def out_enum(self, fname, name, args): - self.data += f'.TH "{self.modulename}" 9 "enum {name}" "{self.man_date}" "API Manual" LINUX' + "\n" + out_name = self.arg_name(args, name) + + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" self.data += ".SH NAME\n" self.data += f"enum {name} \\- {args['purpose']}\n" @@ -703,8 +776,9 @@ class ManFormat(OutputFormat): def out_typedef(self, fname, name, args): module = self.modulename purpose = args.get('purpose') + out_name = self.arg_name(args, name) - self.data += f'.TH "{module}" 9 "{name}" "{self.man_date}" "API Manual" LINUX' + "\n" + self.data += f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" self.data += ".SH NAME\n" self.data += f"typedef {name} \\- {purpose}\n" @@ -717,8 +791,9 @@ class ManFormat(OutputFormat): module = self.modulename purpose = args.get('purpose') definition = args.get('definition') + out_name = self.arg_name(args, name) - self.data += f'.TH "{module}" 9 "{args.type} {name}" "{self.man_date}" "API Manual" LINUX' + "\n" + self.data += f'.TH "{module}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" self.data += ".SH NAME\n" self.data += f"{args.type} {name} \\- {purpose}\n" diff --git a/scripts/lib/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py similarity index 97% rename from scripts/lib/kdoc/kdoc_parser.py rename to tools/lib/python/kdoc/kdoc_parser.py index 2376f180b1fa..500aafc50032 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -16,14 +16,14 @@ import sys import re from pprint import pformat -from kdoc_re import NestedMatch, KernRe -from kdoc_item import KdocItem +from kdoc.kdoc_re import NestedMatch, KernRe +from kdoc.kdoc_item import KdocItem # # Regular expressions used to parse kernel-doc markups at KernelDoc class. # -# Let's declare them in lowercase outside any class to make easier to -# convert from the python script. +# Let's declare them in lowercase outside any class to make it easier to +# convert from the Perl script. # # As those are evaluated at the beginning, no need to cache them # @@ -86,6 +86,8 @@ struct_xforms = [ (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__packed\s*', re.S), ' '), (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), + (KernRe(r'\s*__private', re.S), ' '), + (KernRe(r'\s*__rcu', re.S), ' '), (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), (KernRe(r'\s*____cacheline_aligned', re.S), ' '), (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), @@ -133,7 +135,7 @@ struct_xforms = [ # TODO: use NestedMatch for FOO($1, $2, ...) matches # # it is better to also move those to the NestedMatch logic, - # to ensure that parenthesis will be properly matched. + # to ensure that parentheses will be properly matched. # (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), @@ -153,7 +155,7 @@ struct_xforms = [ (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'), ] # -# Regexes here are guaranteed to have the end limiter matching +# Regexes here are guaranteed to have the end delimiter matching # the start delimiter. Yet, right now, only one replace group # is allowed. # @@ -183,6 +185,7 @@ function_xforms = [ (KernRe(r"__weak +"), ""), (KernRe(r"__sched +"), ""), (KernRe(r"_noprof"), ""), + (KernRe(r"__always_unused *"), ""), (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), @@ -254,8 +257,9 @@ SECTION_DEFAULT = "Description" # default section class KernelEntry: - def __init__(self, config, ln): + def __init__(self, config, fname, ln): self.config = config + self.fname = fname self._contents = [] self.prototype = "" @@ -274,6 +278,8 @@ class KernelEntry: self.leading_space = None + self.fname = fname + # State flags self.brcount = 0 self.declaration_start_line = ln + 1 @@ -288,9 +294,11 @@ class KernelEntry: return '\n'.join(self._contents) + '\n' # TODO: rename to emit_message after removal of kernel-doc.pl - def emit_msg(self, log_msg, warning=True): + def emit_msg(self, ln, msg, *, warning=True): """Emit a message""" + log_msg = f"{self.fname}:{ln} {msg}" + if not warning: self.config.log.info(log_msg) return @@ -336,7 +344,7 @@ class KernelEntry: # Only warn on user-specified duplicate section names if name != SECTION_DEFAULT: self.emit_msg(self.new_start_line, - f"duplicate section name '{name}'\n") + f"duplicate section name '{name}'") # Treat as a new paragraph - add a blank line self.sections[name] += '\n' + contents else: @@ -350,6 +358,7 @@ class KernelEntry: self.section = SECTION_DEFAULT self._contents = [] +python_warning = False class KernelDoc: """ @@ -383,19 +392,23 @@ class KernelDoc: # We need Python 3.7 for its "dicts remember the insertion # order" guarantee # - if sys.version_info.major == 3 and sys.version_info.minor < 7: + global python_warning + if (not python_warning and + sys.version_info.major == 3 and sys.version_info.minor < 7): + self.emit_msg(0, 'Python 3.7 or later is required for correct results') + python_warning = True - def emit_msg(self, ln, msg, warning=True): + def emit_msg(self, ln, msg, *, warning=True): """Emit a message""" - log_msg = f"{self.fname}:{ln} {msg}" - if self.entry: - self.entry.emit_msg(log_msg, warning) + self.entry.emit_msg(ln, msg, warning=warning) return + log_msg = f"{self.fname}:{ln} {msg}" + if warning: self.config.log.warning(log_msg) else: @@ -417,7 +430,8 @@ class KernelDoc: The actual output and output filters will be handled elsewhere """ - item = KdocItem(name, dtype, self.entry.declaration_start_line, **args) + item = KdocItem(name, self.fname, dtype, + self.entry.declaration_start_line, **args) item.warnings = self.entry.warnings # Drop empty sections @@ -440,7 +454,14 @@ class KernelDoc: variables used by the state machine. """ - self.entry = KernelEntry(self.config, ln) + # + # Flush the warnings out before we proceed further + # + if self.entry and self.entry not in self.entries: + for log_msg in self.entry.warnings: + self.config.log.warning(log_msg) + + self.entry = KernelEntry(self.config, self.fname, ln) # State flags self.state = state.NORMAL @@ -794,7 +815,7 @@ class KernelDoc: def dump_struct(self, ln, proto): """ - Store an entry for an struct or union + Store an entry for a struct or union """ # # Do the basic parse to get the pieces of the declaration. @@ -901,7 +922,7 @@ class KernelDoc: for k in self.entry.parameterdescs: if k not in member_set: self.emit_msg(ln, - f"Excess enum value '%{k}' description in '{declaration_name}'") + f"Excess enum value '@{k}' description in '{declaration_name}'") self.output_declaration('enum', declaration_name, purpose=self.entry.declaration_purpose) @@ -923,7 +944,7 @@ class KernelDoc: def dump_function(self, ln, prototype): """ - Stores a function of function macro inside self.entries array. + Stores a function or function macro inside self.entries array. """ found = func_macro = False @@ -1158,7 +1179,7 @@ class KernelDoc: # else: self.emit_msg(ln, - f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") + f"This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst\n{line}") self.state = state.NORMAL return # diff --git a/scripts/lib/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py similarity index 91% rename from scripts/lib/kdoc/kdoc_re.py rename to tools/lib/python/kdoc/kdoc_re.py index 612223e1e723..2dfa1bf83d64 100644 --- a/scripts/lib/kdoc/kdoc_re.py +++ b/tools/lib/python/kdoc/kdoc_re.py @@ -16,7 +16,7 @@ re_cache = {} class KernRe: """ - Helper class to simplify regex declaration and usage, + Helper class to simplify regex declaration and usage. It calls re.compile for a given pattern. It also allows adding regular expressions and define sub at class init time. @@ -27,7 +27,7 @@ class KernRe: def _add_regex(self, string, flags): """ - Adds a new regex or re-use it from the cache. + Adds a new regex or reuses it from the cache. """ self.regex = re_cache.get(string, None) if not self.regex: @@ -114,7 +114,7 @@ class NestedMatch: '\\bSTRUCT_GROUP(\\(((?:(?>[^)(]+)|(?1))*)\\))[^;]*;' - which is used to properly match open/close parenthesis of the + which is used to properly match open/close parentheses of the string search STRUCT_GROUP(), Add a class that counts pairs of delimiters, using it to match and @@ -136,13 +136,13 @@ class NestedMatch: # \bSTRUCT_GROUP\( # # is similar to: STRUCT_GROUP\((.*)\) - # except that the content inside the match group is delimiter's aligned. + # except that the content inside the match group is delimiter-aligned. # - # The content inside parenthesis are converted into a single replace + # The content inside parentheses is converted into a single replace # group (e.g. r`\1'). # # It would be nice to change such definition to support multiple - # match groups, allowing a regex equivalent to. + # match groups, allowing a regex equivalent to: # # FOO\((.*), (.*), (.*)\) # @@ -168,14 +168,14 @@ class NestedMatch: but I ended using a different implementation to align all three types of delimiters and seek for an initial regular expression. - The algorithm seeks for open/close paired delimiters and place them - into a stack, yielding a start/stop position of each match when the + The algorithm seeks for open/close paired delimiters and places them + into a stack, yielding a start/stop position of each match when the stack is zeroed. - The algorithm shoud work fine for properly paired lines, but will - silently ignore end delimiters that preceeds an start delimiter. + The algorithm should work fine for properly paired lines, but will + silently ignore end delimiters that precede a start delimiter. This should be OK for kernel-doc parser, as unaligned delimiters - would cause compilation errors. So, we don't need to rise exceptions + would cause compilation errors. So, we don't need to raise exceptions to cover such issues. """ @@ -203,7 +203,7 @@ class NestedMatch: stack.append(end) continue - # Does the end delimiter match what it is expected? + # Does the end delimiter match what is expected? if stack and d == stack[-1]: stack.pop() diff --git a/tools/lib/python/kdoc/latex_fonts.py b/tools/lib/python/kdoc/latex_fonts.py new file mode 100755 index 000000000000..29317f8006ea --- /dev/null +++ b/tools/lib/python/kdoc/latex_fonts.py @@ -0,0 +1,167 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-only +# Copyright (C) Akira Yokosawa, 2024 +# +# Ported to Python by (c) Mauro Carvalho Chehab, 2025 + +""" +Detect problematic Noto CJK variable fonts. + +For "make pdfdocs", reports of build errors of translations.pdf started +arriving early 2024 [1, 2]. It turned out that Fedora and openSUSE +tumbleweed have started deploying variable-font [3] format of "Noto CJK" +fonts [4, 5]. For PDF, a LaTeX package named xeCJK is used for CJK +(Chinese, Japanese, Korean) pages. xeCJK requires XeLaTeX/XeTeX, which +does not (and likely never will) understand variable fonts for historical +reasons. + +The build error happens even when both of variable- and non-variable-format +fonts are found on the build system. To make matters worse, Fedora enlists +variable "Noto CJK" fonts in the requirements of langpacks-ja, -ko, -zh_CN, +-zh_TW, etc. Hence developers who have interest in CJK pages are more +likely to encounter the build errors. + +This script is invoked from the error path of "make pdfdocs" and emits +suggestions if variable-font files of "Noto CJK" fonts are in the list of +fonts accessible from XeTeX. + +References: +[1]: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ +[2]: https://lore.kernel.org/r/1708585803.600323099@f111.i.mail.ru/ +[3]: https://en.wikipedia.org/wiki/Variable_font +[4]: https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts +[5]: https://build.opensuse.org/request/show/1157217 + +#=========================================================================== +Workarounds for building translations.pdf +#=========================================================================== + +* Denylist "variable font" Noto CJK fonts. + - Create $HOME/deny-vf/fontconfig/fonts.conf from template below, with + tweaks if necessary. Remove leading "". + - Path of fontconfig/fonts.conf can be overridden by setting an env + variable FONTS_CONF_DENY_VF. + + * Template: +----------------------------------------------------------------- + + + + + + + + /usr/share/fonts/google-noto-*-cjk-vf-fonts + + /usr/share/fonts/truetype/Noto*CJK*-VF.otf + + + +----------------------------------------------------------------- + + The denylisting is activated for "make pdfdocs". + +* For skipping CJK pages in PDF + - Uninstall texlive-xecjk. + Denylisting is not needed in this case. + +* For printing CJK pages in PDF + - Need non-variable "Noto CJK" fonts. + * Fedora + - google-noto-sans-cjk-fonts + - google-noto-serif-cjk-fonts + * openSUSE tumbleweed + - Non-variable "Noto CJK" fonts are not available as distro packages + as of April, 2024. Fetch a set of font files from upstream Noto + CJK Font released at: + https://github.com/notofonts/noto-cjk/tree/main/Sans#super-otc + and at: + https://github.com/notofonts/noto-cjk/tree/main/Serif#super-otc + , then uncompress and deploy them. + - Remember to update fontconfig cache by running fc-cache. + +!!! Caution !!! + Uninstalling "variable font" packages can be dangerous. + They might be depended upon by other packages important for your work. + Denylisting should be less invasive, as it is effective only while + XeLaTeX runs in "make pdfdocs". +""" + +import os +import re +import subprocess +import textwrap +import sys + +class LatexFontChecker: + """ + Detect problems with CJK variable fonts that affect PDF builds for + translations. + """ + + def __init__(self, deny_vf=None): + if not deny_vf: + deny_vf = os.environ.get('FONTS_CONF_DENY_VF', "~/deny-vf") + + self.environ = os.environ.copy() + self.environ['XDG_CONFIG_HOME'] = os.path.expanduser(deny_vf) + + self.re_cjk = re.compile(r"([^:]+):\s*Noto\s+(Sans|Sans Mono|Serif) CJK") + + def description(self): + return __doc__ + + def get_noto_cjk_vf_fonts(self): + """Get Noto CJK fonts""" + + cjk_fonts = set() + cmd = ["fc-list", ":", "file", "family", "variable"] + try: + result = subprocess.run(cmd,stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + universal_newlines=True, + env=self.environ, + check=True) + + except subprocess.CalledProcessError as exc: + sys.exit(f"Error running fc-list: {repr(exc)}") + + for line in result.stdout.splitlines(): + if 'variable=True' not in line: + continue + + match = self.re_cjk.search(line) + if match: + cjk_fonts.add(match.group(1)) + + return sorted(cjk_fonts) + + def check(self): + """Check for problems with CJK fonts""" + + fonts = textwrap.indent("\n".join(self.get_noto_cjk_vf_fonts()), " ") + if not fonts: + return None + + rel_file = os.path.relpath(__file__, os.getcwd()) + + msg = "=" * 77 + "\n" + msg += 'XeTeX is confused by "variable font" files listed below:\n' + msg += fonts + "\n" + msg += textwrap.dedent(f""" + For CJK pages in PDF, they need to be hidden from XeTeX by denylisting. + Or, CJK pages can be skipped by uninstalling texlive-xecjk. + + For more info on denylisting, other options, and variable font, run: + + tools/docs/check-variable-fonts.py -h + """) + msg += "=" * 77 + + return msg diff --git a/tools/docs/lib/parse_data_structs.py b/tools/lib/python/kdoc/parse_data_structs.py similarity index 75% rename from tools/docs/lib/parse_data_structs.py rename to tools/lib/python/kdoc/parse_data_structs.py index a5aa2e182052..25361996cd20 100755 --- a/tools/docs/lib/parse_data_structs.py +++ b/tools/lib/python/kdoc/parse_data_structs.py @@ -53,11 +53,19 @@ class ParseDataStructs: replace - Replaces how old_symbol with a new reference. The new_reference can be: + Replaces how old_symbol with a new reference. The new_reference can be: + - A simple symbol name; - A full Sphinx reference. - On both cases, can be: + 3. Namespace rules + + namespace + + Sets C namespace to be used during cross-reference generation. Can + be overridden by replace rules. + + On ignore and replace rules, can be: - ioctl: for defines that end with _IO*, e.g. ioctl definitions - define: for other defines - symbol: for symbols defined within enums; @@ -71,6 +79,8 @@ class ParseDataStructs: ignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` + + namespace MC """ # Parser regexes with multiple ways to capture enums and structs @@ -140,10 +150,96 @@ class ParseDataStructs: self.symbols = {} + self.namespace = None + self.ignore = [] + self.replace = [] + for symbol_type in self.DEF_SYMBOL_TYPES: self.symbols[symbol_type] = {} - def store_type(self, symbol_type: str, symbol: str, + def read_exceptions(self, fname: str): + if not fname: + return + + name = os.path.basename(fname) + + with open(fname, "r", encoding="utf-8", errors="backslashreplace") as f: + for ln, line in enumerate(f): + ln += 1 + line = line.strip() + if not line or line.startswith("#"): + continue + + # ignore rules + match = re.match(r"^ignore\s+(\w+)\s+(\S+)", line) + + if match: + self.ignore.append((ln, match.group(1), match.group(2))) + continue + + # replace rules + match = re.match(r"^replace\s+(\S+)\s+(\S+)\s+(\S+)", line) + if match: + self.replace.append((ln, match.group(1), match.group(2), + match.group(3))) + continue + + match = re.match(r"^namespace\s+(\S+)", line) + if match: + self.namespace = match.group(1) + continue + + sys.exit(f"{name}:{ln}: invalid line: {line}") + + def apply_exceptions(self): + """ + Process exceptions file with rules to ignore or replace references. + """ + + # Handle ignore rules + for ln, c_type, symbol in self.ignore: + if c_type not in self.DEF_SYMBOL_TYPES: + sys.exit(f"{name}:{ln}: {c_type} is invalid") + + d = self.symbols[c_type] + if symbol in d: + del d[symbol] + + # Handle replace rules + for ln, c_type, old, new in self.replace: + if c_type not in self.DEF_SYMBOL_TYPES: + sys.exit(f"{name}:{ln}: {c_type} is invalid") + + reftype = None + + # Parse reference type when the type is specified + + match = re.match(r"^\:c\:(\w+)\:\`(.+)\`", new) + if match: + reftype = f":c:{match.group(1)}" + new = match.group(2) + else: + match = re.search(r"(\:ref)\:\`(.+)\`", new) + if match: + reftype = match.group(1) + new = match.group(2) + + # If the replacement rule doesn't have a type, get default + if not reftype: + reftype = self.DEF_SYMBOL_TYPES[c_type].get("ref_type") + if not reftype: + reftype = self.DEF_SYMBOL_TYPES[c_type].get("real_type") + + new_ref = f"{reftype}:`{old} <{new}>`" + + # Change self.symbols to use the replacement rule + if old in self.symbols[c_type]: + (_, ln) = self.symbols[c_type][old] + self.symbols[c_type][old] = (new_ref, ln) + else: + print(f"{name}:{ln}: Warning: can't find {old} {c_type}") + + def store_type(self, ln, symbol_type: str, symbol: str, ref_name: str = None, replace_underscores: bool = True): """ Stores a new symbol at self.symbols under symbol_type. @@ -157,35 +253,42 @@ class ParseDataStructs: ref_type = defs.get("ref_type") # Determine ref_link based on symbol type - if ref_type: - if symbol_type == "enum": - ref_link = f"{ref_type}:`{symbol}`" - else: - if not ref_name: - ref_name = symbol.lower() + if ref_type or self.namespace: + if not ref_name: + ref_name = symbol.lower() - # c-type references don't support hash - if ref_type == ":ref" and replace_underscores: - ref_name = ref_name.replace("_", "-") + # c-type references don't support hash + if ref_type == ":ref" and replace_underscores: + ref_name = ref_name.replace("_", "-") + # C domain references may have namespaces + if ref_type.startswith(":c:"): + if self.namespace: + ref_name = f"{self.namespace}.{ref_name}" + + if ref_type: ref_link = f"{ref_type}:`{symbol} <{ref_name}>`" + else: + ref_link = f"`{symbol} <{ref_name}>`" else: ref_link = symbol - self.symbols[symbol_type][symbol] = f"{prefix}{ref_link}{suffix}" + self.symbols[symbol_type][symbol] = (f"{prefix}{ref_link}{suffix}", ln) def store_line(self, line): """Stores a line at self.data, properly indented""" line = " " + line.expandtabs() self.data += line.rstrip(" ") - def parse_file(self, file_in: str): + def parse_file(self, file_in: str, exceptions: str = None): """Reads a C source file and get identifiers""" self.data = "" is_enum = False is_comment = False multiline = "" + self.read_exceptions(exceptions) + with open(file_in, "r", encoding="utf-8", errors="backslashreplace") as f: for line_no, line in enumerate(f): @@ -240,20 +343,20 @@ class ParseDataStructs: if is_enum: match = re.match(r"^\s*([_\w][\w\d_]+)\s*[\,=]?", line) if match: - self.store_type("symbol", match.group(1)) + self.store_type(line_no, "symbol", match.group(1)) if "}" in line: is_enum = False continue match = re.match(r"^\s*#\s*define\s+([\w_]+)\s+_IO", line) if match: - self.store_type("ioctl", match.group(1), + self.store_type(line_no, "ioctl", match.group(1), replace_underscores=False) continue match = re.match(r"^\s*#\s*define\s+([\w_]+)(\s+|$)", line) if match: - self.store_type("define", match.group(1)) + self.store_type(line_no, "define", match.group(1)) continue match = re.match(r"^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);", @@ -261,90 +364,23 @@ class ParseDataStructs: if match: name = match.group(2).strip() symbol = match.group(3) - self.store_type("typedef", symbol, ref_name=name) + self.store_type(line_no, "typedef", symbol, ref_name=name) continue for re_enum in self.RE_ENUMS: match = re_enum.match(line) if match: - self.store_type("enum", match.group(1)) + self.store_type(line_no, "enum", match.group(1)) is_enum = True break for re_struct in self.RE_STRUCTS: match = re_struct.match(line) if match: - self.store_type("struct", match.group(1)) + self.store_type(line_no, "struct", match.group(1)) break - def process_exceptions(self, fname: str): - """ - Process exceptions file with rules to ignore or replace references. - """ - if not fname: - return - - name = os.path.basename(fname) - - with open(fname, "r", encoding="utf-8", errors="backslashreplace") as f: - for ln, line in enumerate(f): - ln += 1 - line = line.strip() - if not line or line.startswith("#"): - continue - - # Handle ignore rules - match = re.match(r"^ignore\s+(\w+)\s+(\S+)", line) - if match: - c_type = match.group(1) - symbol = match.group(2) - - if c_type not in self.DEF_SYMBOL_TYPES: - sys.exit(f"{name}:{ln}: {c_type} is invalid") - - d = self.symbols[c_type] - if symbol in d: - del d[symbol] - - continue - - # Handle replace rules - match = re.match(r"^replace\s+(\S+)\s+(\S+)\s+(\S+)", line) - if not match: - sys.exit(f"{name}:{ln}: invalid line: {line}") - - c_type, old, new = match.groups() - - if c_type not in self.DEF_SYMBOL_TYPES: - sys.exit(f"{name}:{ln}: {c_type} is invalid") - - reftype = None - - # Parse reference type when the type is specified - - match = re.match(r"^\:c\:(data|func|macro|type)\:\`(.+)\`", new) - if match: - reftype = f":c:{match.group(1)}" - new = match.group(2) - else: - match = re.search(r"(\:ref)\:\`(.+)\`", new) - if match: - reftype = match.group(1) - new = match.group(2) - - # If the replacement rule doesn't have a type, get default - if not reftype: - reftype = self.DEF_SYMBOL_TYPES[c_type].get("ref_type") - if not reftype: - reftype = self.DEF_SYMBOL_TYPES[c_type].get("real_type") - - new_ref = f"{reftype}:`{old} <{new}>`" - - # Change self.symbols to use the replacement rule - if old in self.symbols[c_type]: - self.symbols[c_type][old] = new_ref - else: - print(f"{name}:{ln}: Warning: can't find {old} {c_type}") + self.apply_exceptions() def debug_print(self): """ @@ -360,8 +396,8 @@ class ParseDataStructs: print(f"{c_type}:") - for symbol, ref in sorted(refs.items()): - print(f" {symbol} -> {ref}") + for symbol, (ref, ln) in sorted(refs.items()): + print(f" #{ln:<5d} {symbol} -> {ref}") print() @@ -384,7 +420,7 @@ class ParseDataStructs: # Process all reference types for ref_dict in self.symbols.values(): - for symbol, replacement in ref_dict.items(): + for symbol, (replacement, _) in ref_dict.items(): symbol = re.escape(re.sub(r"([\_\`\*\<\>\&\\\\:\/])", r"\\\1", symbol)) text = re.sub(fr'{start_delim}{symbol}{end_delim}', fr'\1{replacement}\2', text) @@ -397,16 +433,10 @@ class ParseDataStructs: def gen_toc(self): """ - Create a TOC table pointing to each symbol from the header + Create a list of symbols to be part of a TOC contents table """ text = [] - # Add header - text.append(".. contents:: Table of Contents") - text.append(" :depth: 2") - text.append(" :local:") - text.append("") - # Sort symbol types per description symbol_descriptions = [] for k, v in self.DEF_SYMBOL_TYPES.items(): @@ -426,8 +456,8 @@ class ParseDataStructs: text.append("") # Sort symbols alphabetically - for symbol, ref in sorted(refs.items()): - text.append(f"* :{ref}:") + for symbol, (ref, ln) in sorted(refs.items()): + text.append(f"- LINENO_{ln}: {ref}") text.append("") # Add empty line between categories diff --git a/tools/lib/python/kdoc/python_version.py b/tools/lib/python/kdoc/python_version.py new file mode 100644 index 000000000000..e83088013db2 --- /dev/null +++ b/tools/lib/python/kdoc/python_version.py @@ -0,0 +1,178 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (c) 2017-2025 Mauro Carvalho Chehab + +""" +Handle Python version check logic. + +Not all Python versions are supported by scripts. Yet, on some cases, +like during documentation build, a newer version of python could be +available. + +This class allows checking if the minimal requirements are followed. + +Better than that, PythonVersion.check_python() not only checks the minimal +requirements, but it automatically switches to a the newest available +Python version if present. + +""" + +import os +import re +import subprocess +import shlex +import sys + +from glob import glob +from textwrap import indent + +class PythonVersion: + """ + Ancillary methods that checks for missing dependencies for different + types of types, like binaries, python modules, rpm deps, etc. + """ + + def __init__(self, version): + """Ïnitialize self.version tuple from a version string""" + self.version = self.parse_version(version) + + @staticmethod + def parse_version(version): + """Convert a major.minor.patch version into a tuple""" + return tuple(int(x) for x in version.split(".")) + + @staticmethod + def ver_str(version): + """Returns a version tuple as major.minor.patch""" + return ".".join([str(x) for x in version]) + + @staticmethod + def cmd_print(cmd, max_len=80): + cmd_line = [] + + for w in cmd: + w = shlex.quote(w) + + if cmd_line: + if not max_len or len(cmd_line[-1]) + len(w) < max_len: + cmd_line[-1] += " " + w + continue + else: + cmd_line[-1] += " \\" + cmd_line.append(w) + else: + cmd_line.append(w) + + return "\n ".join(cmd_line) + + def __str__(self): + """Returns a version tuple as major.minor.patch from self.version""" + return self.ver_str(self.version) + + @staticmethod + def get_python_version(cmd): + """ + Get python version from a Python binary. As we need to detect if + are out there newer python binaries, we can't rely on sys.release here. + """ + + kwargs = {} + if sys.version_info < (3, 7): + kwargs['universal_newlines'] = True + else: + kwargs['text'] = True + + result = subprocess.run([cmd, "--version"], + stdout = subprocess.PIPE, + stderr = subprocess.PIPE, + **kwargs, check=False) + + version = result.stdout.strip() + + match = re.search(r"(\d+\.\d+\.\d+)", version) + if match: + return PythonVersion.parse_version(match.group(1)) + + print(f"Can't parse version {version}") + return (0, 0, 0) + + @staticmethod + def find_python(min_version): + """ + Detect if are out there any python 3.xy version newer than the + current one. + + Note: this routine is limited to up to 2 digits for python3. We + may need to update it one day, hopefully on a distant future. + """ + patterns = [ + "python3.[0-9][0-9]", + "python3.[0-9]", + ] + + python_cmd = [] + + # Seek for a python binary newer than min_version + for path in os.getenv("PATH", "").split(":"): + for pattern in patterns: + for cmd in glob(os.path.join(path, pattern)): + if os.path.isfile(cmd) and os.access(cmd, os.X_OK): + version = PythonVersion.get_python_version(cmd) + if version >= min_version: + python_cmd.append((version, cmd)) + + return sorted(python_cmd, reverse=True) + + @staticmethod + def check_python(min_version, show_alternatives=False, bail_out=False, + success_on_error=False): + """ + Check if the current python binary satisfies our minimal requirement + for Sphinx build. If not, re-run with a newer version if found. + """ + cur_ver = sys.version_info[:3] + if cur_ver >= min_version: + ver = PythonVersion.ver_str(cur_ver) + return + + python_ver = PythonVersion.ver_str(cur_ver) + + available_versions = PythonVersion.find_python(min_version) + if not available_versions: + print(f"ERROR: Python version {python_ver} is not supported anymore\n") + print(" Can't find a new version. This script may fail") + return + + script_path = os.path.abspath(sys.argv[0]) + + # Check possible alternatives + if available_versions: + new_python_cmd = available_versions[0][1] + else: + new_python_cmd = None + + if show_alternatives and available_versions: + print("You could run, instead:") + for _, cmd in available_versions: + args = [cmd, script_path] + sys.argv[1:] + + cmd_str = indent(PythonVersion.cmd_print(args), " ") + print(f"{cmd_str}\n") + + if bail_out: + msg = f"Python {python_ver} not supported. Bailing out" + if success_on_error: + print(msg, file=sys.stderr) + sys.exit(0) + else: + sys.exit(msg) + + print(f"Python {python_ver} not supported. Changing to {new_python_cmd}") + + # Restart script using the newer version + args = [new_python_cmd, script_path] + sys.argv[1:] + + try: + os.execv(new_python_cmd, args) + except OSError as e: + sys.exit(f"Failed to restart with {new_python_cmd}: {e}")