Following a recent discussion at last Plumbers, John Stultz, Sumit
Sewal, TJ Mercier and I came to an agreement that we should document
what the dma-buf heaps names are expected to be, and what the buffers
attributes you'll get should be documented.
Let's create that doc to make sure those attributes and names are
guaranteed going forward.
Reviewed-by: T.J. Mercier <tjmercier@google.com>
Signed-off-by: Maxime Ripard <mripard@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250306135114.1943738-1-mripard@kernel.org
Commit fb12098d8e ("docs: submit-checklist: Allow creating
cross-references for ABI README") assumes that the path of
"Documentation/ABI/README" would be converted to a cross-ref to
the README.
However, as the README is included by the "kernel-abi" directive
at Documentation/admin-guide/abi.rst, the expected conversion
does not happen.
Instead, use the path where the "kernel-abi" directive exists for
the conversion to work. Restore the original path of README in
inline-literal form as an additional note for readers of the .rst
file.
Apply the same changes for translations.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Fixes: fb12098d8e ("docs: submit-checklist: Allow creating cross-references for ABI README")
Fixes: eb0c714120 ("docs: translations: Allow creating cross-references for ABI README")
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Alex Shi <alexs@kernel.org>
Cc: Yanteng Si <si.yanteng@linux.dev>
Cc: Dongliang Mu <dzm91@hust.edu.cn>
Cc: Hu Haowen <2023002089@link.tyut.edu.cn>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Carlos Bilbao <carlos.bilbao@kernel.org>
Cc: Avadhut Naik <avadhut.naik@amd.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250304075734.56660-1-akiyks@gmail.com
Updates the document to clearly describe the scope and role the TAB plays
in making decisions on unresolved violations. If and when the CoC has to
make a call on instituting a ban, it doesn't act without the TAB's approval
and only when the TAB approves it with 2/3 vote in favor of the measure.
These changes ensure that the TAB role and its oversight on CoC measures
is consistently described throughout the document.
Fixes: c818d5c64c ("Documentation/CoC: spell out enforcement for unacceptable behaviors")
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Miguel Ojeda <ojeda@kernel.org>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuah@kernel.org>
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250306211231.13154-1-shuah@kernel.org
Both get_feat.pl and list-arch.sh use uname -m to get the machine hardware
name to figure out the current architecture if no architecture is specified
with a command line option.
This doesn't work for s390, since for 64 bit kernels the hardware name is
s390x, while the architecture name within the kernel, as well as in all
feature files is s390.
Therefore substitute s390x with s390 similar to what is already done for
x86_64 and i386.
Signed-off-by: Heiko Carstens <hca@linux.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250312155219.3597768-1-hca@linux.ibm.com
kerneldoc.py extension doesn't handle a "\" character at the end
of the line: it will just merge it to the cmd line, producing
this command:
scripts/kernel-doc -rst -enable-lineno -function iscsi_iser_pdu_alloc -function iser_initialize_task_headers -function \ -function iscsi_iser_task_init -function iscsi_iser_mtask_xmit -function iscsi_iser_task_xmit -function \ -function iscsi_iser_cleanup_task -function iscsi_iser_check_protection -function \ -function iscsi_iser_conn_create -function iscsi_iser_conn_bind -function \ -function iscsi_iser_conn_start -function iscsi_iser_conn_stop -function \ -function iscsi_iser_session_destroy -function iscsi_iser_session_create -function \ -function iscsi_iser_set_param -function iscsi_iser_ep_connect -function iscsi_iser_ep_poll -function \ -function iscsi_iser_ep_disconnect ./drivers/infiniband/ulp/iser/iscsi_iser.c
which may not work as expected.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/64e7949439c5fc39f2c9441027ad02bc60cbf0dd.1740387599.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Kerneldoc requires a "-" after the name of a function for it
to be recognized as a function.
Add it.
Fix those kernel-doc warnings:
include/asm-generic/io.h:1215: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* memset_io Set a range of I/O memory to a constant value
include/asm-generic/io.h:1227: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* memcpy_fromio Copy a block of data from I/O memory
include/asm-generic/io.h:1239: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* memcpy_toio Copy a block of data into I/O memory
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Link: https://lore.kernel.org/r/066968c00196ed88f6dc97e3d317926fc4ab7d52.1740387599.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is a brand-new translation against
commit 2783096fb1 ("docs: submit-checklist: Expand on build tests
against different word sizes"), rather than an update of
ja_JP/SubmitChecklist, which has never updated since 2008 except for
trivial changes not involving translation.
As we now have two reST contents under the ja_JP translation,
to avoid duplicated boiler plates, split out ja_JP's own disclaimer
part into a new section and put a reference to it at the beginning of
each doc.
As there is no prospect of ja_JP to have a lot of translated docs,
keep those .rst files in the toctree of ja_JP/index.rst.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Tsugikazu Shibata <shibata@linuxfoundation.org>
Reviewed-by: Tsugikazu Shibata <shibata@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250217060132.64670-1-akiyks@gmail.com
Dongliang Mu has translated a substantial portion of kernel documentation
into Chinese, developed scripts/checktransupdate.py utility to automate
tracking of translated content updates, and actively reviewed patches.
Thus, add Dongliang Mu as a reviewer for the translations of
Chinese Documentation.
Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250217043109.3571459-1-dzm91@hust.edu.cn
Add a reference to my new book, The Linux Memory Manager, an in-depth
exploration of the memory management subsystem, to
process/kernel-docs.rst.
This is not yet published, but the full draft is available on pre-order, so
it seems worthwhile adding it here. The situation is made clear in the
'notes' section.
The 'pre-release' was made available in February 2025, and full release is
scheduled for Fall 2025. The book's ISBN-13 is 978-1718504462.
The document will be updated upon release to reflect this.
Signed-off-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Reviewed-by: Carlos Bilbao <carlos.bilbao@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250218154303.45595-1-lorenzo.stoakes@oracle.com
Mauro says:
This series increases the minimal requirements for Sphinx and Python, and
drop some backward-compatible code from Sphinx extension.
Looking at Sphinx release dates:
Release 2.4.0 (released Feb 09, 2020)
Release 2.4.4 (released Mar 05, 2020) (current minimal requirement)
Release 3.4.0 (released Dec 20, 2020)
Release 3.4.3 (released Jan 08, 2021)
(https://www.sphinx-doc.org/en/master/changes/index.html)
And Python release dates, we have:
Python Release date
3.5 2015-09-13 (current minimal requirement)
3.6 2016-12-23
3.7 2018-06-27
3.8 2019-10-14
3.9 2020-10-05
3.10 2021-10-04
(according with https://en.wikipedia.org/w/index.php?title=History_of_Python)
The new minimal requirements are now compatible with the toolset available on Jan, 2021,
e.g.:
- Sphinx 3.4.3;
- Python 3.9
The new Sphinx minimal requirement allows dropping all backward-compatible code
we have at kernel-doc and at Sphinx extensions.
The new Python minimal requirement also matches the current required level for
almost all scripts (*).
Those matches a 4-years old toolchain, which sounds a reasonable period
of time, as Python/Sphinx aren't required for the Kernel build.
(*) Except for a couple scripts inside tools that require python 3.10:
$ vermin -v $(git ls-files '*.py')|grep 3.10
!2, 3.10 tools/net/sunrpc/xdrgen/generators/__init__.py
!2, 3.10 tools/net/sunrpc/xdrgen/generators/program.py
!2, 3.10 tools/net/sunrpc/xdrgen/subcmds/source.py
!2, 3.10 tools/net/sunrpc/xdrgen/xdr_ast.py
!2, 3.10 tools/perf/scripts/python/mem-phys-addr.py
!2, 3.10 tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py
Such scripts aren't required for Kernel builds, so it should be OK to set minimal
python version to 3.9.
The ABI documentation looks a little bit better if it starts
with the contents of the README is placed at the beginning.
Move it to the beginning of the ABI chapter. While here, improve
the README text and change the title that will be shown at the
html/pdf output to be coherent with both ABI file contents and
with the generated documentation output.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20250211055809.1898623-1-mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fixed some spelling mistakes identified by misspell tool.
The example code in Documentation/driver-api/nvdimm/nvdimm.rst contained a
misspelled identifier (paramaters instead of parameters).
This typo would have caused a compilation error if copied as-is.
Signed-off-by: Aditya Dutt <duttaditya18@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250211103002.199004-1-duttaditya18@gmail.com
Kernel-doc has an obscure logic that uses an external file
to map files via a .tmp_filelist.txt file stored at the current
directory. The rationale for such code predates git time,
as it was added on Kernel v2.4.5.5, with the following description:
# 26/05/2001 - Support for separate source and object trees.
# Return error code.
# Keith Owens <kaos@ocs.com.au>
from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historic
tree:
https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/
Support for separate source and object trees is now done on a different
way via make O=<object>.
There's no logic to create such file, so it sounds to me that this is
just dead code.
So, drop it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/fd3b28dec36ba1668325d6770d4c4754414337fc.1739340170.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As warned by get_abi.py, there are two symbols that are
defined twice:
WARNING: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: \
/new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; \
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: \
/new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; \
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
As the documentation at testing/sysfs-devices-system-cpu, drop
the duplicated one from stable.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c3dce809f577584cf9aedafc6c2a0d5a9ca909ac.1739394480.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Adding company name in round brackets to From/SoB lines
is fairly common, but I don't see it documented anywhere.
Every now and then people try to add the sponsorship lines
to the commit message, fun example from this merge window:
Sponsored by: The FreeBSD Foundation
from commit 2ce67f8bf1 ("wifi: iwlwifi: mvm: fix iwl_ssid_exist()
check"). Better format would be:
Author: Miri Korenblit (FreeBSD Foundation) <...
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250203174626.1131225-1-kuba@kernel.org
