Commit f9616386 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-6.19' of git://git.lwn.net/linux 

Pull documentation updates from Jonathan Corbet:
 "This has been another busy cycle for documentation, with a lot of
  build-system thrashing. That work should slow down from here on out.

   - The various scripts and tools for documentation were spread out in
     several directories; now they are (almost) all coalesced under
     tools/docs/. The holdout is the kernel-doc script, which cannot be
     easily moved without some further thought.

   - As the amount of Python code increases, we are accumulating modules
     that are imported by multiple programs. These modules have been
     pulled together under tools/lib/python/ -- at least, for
     documentation-related programs. There is other Python code in the
     tree that might eventually want to move toward this organization.

   - The Perl kernel-doc.pl script has been removed. It is no longer
     used by default, and nobody has missed it, least of all anybody who
     actually had to look at it.

   - The docs build was controlled by a complex mess of makefilese that
     few dared to touch. Mauro has moved that logic into a new program
     (tools/docs/sphinx-build-wrapper) that, with any luck at all, will
     be far easier to understand and maintain.

   - The get_feat.pl program, used to access information under
     Documentation/features/, has been rewritten in Python, bringing an
     end to the use of Perl in the docs subsystem.

   - The top-level README file has been reorganized into a more
     reader-friendly presentation.

   - A lot of Chinese translation additions

   - Typo fixes and documentation updates as usual"

* tag 'docs-6.19' of git://git.lwn.net/linux: (164 commits)
  docs: makefile: move rustdoc check to the build wrapper
  README: restructure with role-based documentation and guidelines
  docs: kdoc: various fixes for grammar, spelling, punctuation
  docs: kdoc_parser: use '@' for Excess enum value
  docs: submitting-patches: Clarify that removal of Acks needs explanation too
  docs: kdoc_parser: add data/function attributes to ignore
  docs: MAINTAINERS: update Mauro's files/paths
  docs/zh_CN: Add wd719x.rst translation
  docs/zh_CN: Add libsas.rst translation
  get_feat.pl: remove it, as it got replaced by get_feat.py
  Documentation/sphinx/kernel_feat.py: use class directly
  tools/docs/get_feat.py: convert get_feat.pl to Python
  Documentation/admin-guide: fix typo and comment in cscope example
  docs/zh_CN: Add data-integrity.rst translation
  docs/zh_CN: Add blk-mq.rst translation
  docs/zh_CN: Add block/index.rst translation
  docs/zh_CN: Update the Chinese translation of kbuild.rst
  docs: bring some order to our Python module hierarchy
  docs: Move the python libraries to tools/lib/python
  Documentation/kernel-parameters: Move the kernel build options
  ...
parents a619fe35 464257ba

.pylintrc

+1 −1
Original line number Diff line number Diff line 
[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"]'

Documentation/ABI/testing/sysfs-module

+2 −0
Original line number Diff line number Diff line
@@ -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

Documentation/Kconfig

+1 −1
Original line number Diff line number Diff line
@@ -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'.

Documentation/Makefile

+35 −125
Original line number Diff line number Diff line
@@ -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)



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) .

# 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)



# 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'

Documentation/accounting/taskstats.rst

+28 −26
Original line number Diff line number Diff line
@@ -85,19 +85,19 @@ 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.

   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:



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.
@@ -108,9 +108,11 @@ same structure is used for both per-pid and per-tgid stats. 
   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

   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

   f) TASKSTATS_TYPE_STATS: contains the per-tgid stats for exiting task's

      process





per-tgid stats