Commit 3e443d16 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

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

Pull documentation updates from Jonathan Corbet:
 "A moderately busy cycle for documentation this time around:

   - The most significant change is the replacement of the old
     kernel-doc script (a monstrous collection of Perl regexes that
     predates the Git era) with a Python reimplementation. That, too, is
     a horrifying collection of regexes, but in a much cleaner and more
     maintainable structure that integrates far better with the Sphinx
     build system.

     This change has been in linux-next for the full 6.15 cycle; the
     small number of problems that turned up have been addressed,
     seemingly to everybody's satisfaction. The Perl kernel-doc script
     remains in tree (as scripts/kernel-doc.pl) and can be used with a
     command-line option if need be. Unless some reason to keep it
     around materializes, it will probably go away in 6.17.

     Credit goes to Mauro Carvalho Chehab for doing all this work.

   - Some RTLA documentation updates

   - A handful of Chinese translations

   - The usual collection of typo fixes, general updates, etc"

* tag 'docs-6.16' of git://git.lwn.net/linux: (85 commits)
  Docs: doc-guide: update sphinx.rst Sphinx version number
  docs: doc-guide: clarify latest theme usage
  Documentation/scheduler: Fix typo in sched-stats domain field description
  scripts: kernel-doc: prevent a KeyError when checking output
  docs: kerneldoc.py: simplify exception handling logic
  MAINTAINERS: update linux-doc entry to cover new Python scripts
  docs: align with scripts/syscall.tbl migration
  Documentation: NTB: Fix typo
  Documentation: ioctl-number: Update table intro
  docs: conf.py: drop backward support for old Sphinx versions
  Docs: driver-api/basics: add kobject_event interfaces
  Docs: relay: editing cleanups
  docs: fix "incase" typo in coresight/panic.rst
  Fix spelling error for 'parallel'
  docs: admin-guide: fix typos in reporting-issues.rst
  docs: dmaengine: add explanation for DMA_ASYNC_TX capability
  Documentation: leds: improve readibility of multicolor doc
  docs: fix typo in firmware-related section
  docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable
  Documentation: ioctl-number: Update outdated submission info
  ...
parents 95bf3760 d6d88600

.gitignore

+1 −0
Original line number Diff line number Diff line
@@ -40,6 +40,7 @@ 
*.o

*.o.*

*.patch

*.pyc

*.rmeta

*.rpm

*.rsi

.pylintrc

0 → 100644
+2 −0
Original line number Diff line number Diff line 
[MASTER]

init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi"]'

Documentation/Makefile

+5 −4
Original line number Diff line number Diff line
@@ -60,9 +60,8 @@ endif #HAVE_LATEXMK 
# Internal variables.

PAPEROPT_a4     = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

KERNELDOC       = $(srctree)/scripts/kernel-doc

KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)

ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)

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
@@ -83,9 +82,11 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; 
# $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 = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \

	PYTHONDONTWRITEBYTECODE=1 \

	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 \

Documentation/admin-guide/namespaces/resource-control.rst

+12 −12
Original line number Diff line number Diff line 
===========================

Namespaces research control

===========================

====================================

User namespaces and resource control

====================================



There are a lot of kinds of objects in the kernel that don't have

individual limits or that have limits that are ineffective when a set

of processes is allowed to switch user ids.  With user namespaces

enabled in a kernel for people who don't trust their users or their

users programs to play nice this problems becomes more acute.

The kernel contains many kinds of objects that either don't have

individual limits or that have limits which are ineffective when

a set of processes is allowed to switch their UID. On a system

where the admins don't trust their users or their users' programs,

user namespaces expose the system to potential misuse of resources.



Therefore it is recommended that memory control groups be enabled in

kernels that enable user namespaces, and it is further recommended

that userspace configure memory control groups to limit how much

memory user's they don't trust to play nice can use.

In order to mitigate this, we recommend that admins enable memory

control groups on any system that enables user namespaces.

Furthermore, we recommend that admins configure the memory control

groups to limit the maximum memory usable by any untrusted user.



Memory control groups can be configured by installing the libcgroup

package present on most distros editing /etc/cgrules.conf,

Documentation/admin-guide/pm/cpufreq.rst

+4 −4
Original line number Diff line number Diff line
@@ -231,7 +231,7 @@ are the following: 
	present).



	The existence of the limit may be a result of some (often unintentional)

	BIOS settings, restrictions coming from a service processor or another

	BIOS settings, restrictions coming from a service processor or other

	BIOS/HW-based mechanisms.



	This does not cover ACPI thermal limitations which can be discovered
@@ -258,8 +258,8 @@ are the following: 
        extension on ARM). If one cannot be determined, this attribute should

        not be present.



        Note, that failed attempt to retrieve current frequency for a given

        CPU(s) will result in an appropriate error, i.e: EAGAIN for CPU that

        Note that failed attempt to retrieve current frequency for a given

        CPU(s) will result in an appropriate error, i.e.: EAGAIN for CPU that

        remains idle (raised on ARM).



``cpuinfo_max_freq``
@@ -499,7 +499,7 @@ This governor exposes the following tunables: 
	represented by it to be 1.5 times as high as the transition latency

	(the default)::



	# echo `$(($(cat cpuinfo_transition_latency) * 3 / 2)) > ondemand/sampling_rate

	# echo `$(($(cat cpuinfo_transition_latency) * 3 / 2))` > ondemand/sampling_rate



``up_threshold``

	If the estimated CPU load is above this value (in percent), the governor