2 paragraph warning and note take a bit more space, let's merge them together,
and guide to other maintainer and reviewers.
Cc: Yanteng Si <si.yanteng@linux.dev>
Cc: Dongliang Mu <dzm91@hust.edu.cn>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Reviewed-by: Tang Yizhou <yizhou.tang@shopee.com>
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn>
Signed-off-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/20250305025101.27717-1-alexs@kernel.org
Translate .../security/snp-tdx-threat-model.rst into Chinese.
Update the translation through commit "cdae7e8a69c3"
("docs/MAINTAINERS: Update my email address")
Fixed pdfdocs warning by Alex Shi.
Reviewed-by: Yanteng Si <si.yanteng@linux.dev>
Signed-off-by: Yuxian Mao <maoyuxian@cqsoftware.com.cn>
Signed-off-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/20250304071401.117780-1-maoyuxian@cqsoftware.com.cn
The guidelines mention that firmware updates can't break the kernel,
but it doesn't state directly that they can't break userspace programs.
Make it explicit that firmware updates cannot break UAPI.
Signed-off-by: Jacek Lawrynowicz <jacek.lawrynowicz@linux.intel.com>
Acked-by: Dave Airlie <airlied@redhat.com>
[jc: fixed "no trailing newline"]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250314100137.2972355-1-jacek.lawrynowicz@linux.intel.com
Point out that explicit permission is usually needed to tag other people
in changes, but mention that implicit permission can be sufficient in
certain cases. This fixes slight inconsistencies between Reported-by:
and Suggested-by: and makes the usage more intuitive.
While at it, explicitly mention the dangers of our bugzilla instance, as
it makes it easy to forget that email addresses visible there are only
shown to logged-in users.
The latter is not a theoretical issue, as one maintainer mentioned that
his employer received a EU GDPR (general data protection regulation)
complaint after exposing a email address used in bugzilla through a tag
in a patch description.
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Simona Vetter <simona.vetter@ffwll.ch>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/588cf2763baa8fea1f4825f4eaa7023fe88bb6c1.1738852082.git.linux@leemhuis.info
The highuid.rst document describes a transition that is outdated and no
longer relevant. Additionally, it references filesystems (ncpfs and smbfs),
which have been removed or replaced.
Suggested-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Kang Taeho <kangtaeho2456@gmail.com>
Link: https://lore.kernel.org/r/20250313145650.278346-1-kangtaeho2456@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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
Ammend missing "install" operation keyword after "apt-get", and fix
"build-essentials" to "build-essential".
Signed-off-by: I Hsin Cheng <richard120310@gmail.com>
Reviewed-by: Charlie Jenkins <charlie@rivosinc.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250306030708.8133-1-richard120310@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>
Added section in Documentation/input/input-programming.rst about
input_setup_polling() and input_set_poll_interval()
Signed-off-by: Brendan Connelly <brendanjconnelly17@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250208173554.209688-1-brendanjconnelly17@gmail.com
Fix spelling of "interference" in the CFS bandwidth control documentation.
The word was misspelled as "interferenece".
Signed-off-by: Suchit Karunakaran <suchitkarunakaran@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250219112254.28691-1-suchitkarunakaran@gmail.com
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
Update the documentation to reflect the change in variable types of
'nr' and 'size' from 'int' to 'size_t', ensuring consistency with
commit dec6c0aac4 ("lib min_heap: Switch to size_t").
Signed-off-by: Yu-Chun Lin <eleanor15x@gmail.com>
Acked-by: Kuan-Wei Chiu <visitorckw@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250215155421.2010336-1-eleanor15x@gmail.com
The introduction discussed stat file formats for very old kernel versions,
which obscured key information that readers may find useful. Additionally,
the example file contents and the reference to "15 fields" did not account
for the flush fields added in b686631865 ("block: add iostat counters for
flush requests") [1].
Rewrite the introduction to focus only on the current kernel's disk I/O stat
file formats. Also, clean up wording for conciseness.
Link: https://lore.kernel.org/lkml/157433282607.7928.5202409984272248322.stgit@buzz/T/ [1]
Signed-off-by: David Reaver <me@davidreaver.com>
Link: https://lore.kernel.org/r/20250215180114.157948-1-me@davidreaver.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The format description of reserve_mem uses [KNG] as units, rather than
[KMG].
Fix it.
Signed-off-by: Mike Rapoport (Microsoft) <rppt@kernel.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250218070845.3769520-1-rppt@kernel.org
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
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
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
Sphinx logging system doesn't like warnings during module load,
as it understands that such logs are produced at the wrong time:
WARNING: while setting up extension automarkup: /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: while setting up extension automarkup: /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
So, use a function to allocate/process ABI files and use it to
be called at kernel_abi.py, as automarkup also needs it to
produce the right cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
Now that all ABI files are handled together, we can add a feature
at automarkup for it to generate cross-references for ABI symbols.
The cross-reference logic can produce references for all existing
files, except for README (as this is not parsed).
For symbols, they need to be an exact match of what it is
described at the docs, which is not always true due to wildcards.
If symbols at /sys /proc and /config are identical, a cross-reference
will be used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org
Now that get_abi has gained support for filtering its output,
split ABI symbols from files at the html output.
That makes pages smaller and easier to navigate.
As an additional bonus, as it will paralelize files handling,
it gives an additional performance improvement.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/30e3cf2a8aeef23ca889de60a90f7de141e0dc0e.1739182025.git.mchehab+huawei@kernel.org
Right now, the logic parses ABI files on 4 steps, one for each
directory. While this is fine in principle, by doing that, not
all symbol cross-references will be created.
Change the logic to do the parsing only once in order to get
a global dictionary to be used when creating ABI cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org