Translate the license-rules.rst document into Brazilian Portuguese.
This document provides guidelines on how licenses should be identified
and handled within the kernel source code.
Additionally, update the pt_BR/process/index.rst to include the new
translation in the documentation tree.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260503160352.160135-1-danielmaraboo@gmail.com>
The context analysis macros are function attributes that should be
in the function_xforms list. Somewhere along the way they were
inserted into the struct_xforms list instead. This causes docs build
warnings to continue to be emitted for context macros.
Move the context analysis macros to the function_xforms list where
they should be to eliminate these warnings.
Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex)
Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260505221548.163751-1-rdunlap@infradead.org>
The `__counted_by_ptr` macro was recently introduced [1] to extend
bounds checking semantics to standard dynamically allocated pointers.
However, the new Python implementation of kernel-doc does not currently
recognize it as a compiler attribute. When kernel-doc encounters a
struct member annotated with this macro, it fails to parse the variable
name correctly, resulting in false-positive warnings like:
Warning: ... struct member '__counted_by_ptr(cmdcnt' not described
Add `__counted_by_ptr` to the `struct_xforms` regex list so it gets
safely stripped out during the parsing phase, mirroring the existing
behavior for `__counted_by`. Update the corresponding unit tests.
Link: https://git.kernel.org/torvalds/c/150a04d817d8 [1]
Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260506-kdoc-__counted_by_ptr-v1-1-70763486871f@linaro.org>
This series improve the output at process/maintainers: instead of a
pure enriched text, the maintainer's file content is now converted
to a table, and has gained a javascript to allow filtering entries.
The initial patches change the logic to split parsing from
output generation. Then, everything is stored into a dict at
the parsing phase, and ona header description variable.
This way, it is easier to adjust the output handler to produce
a more structured document. Right now, the entries are sorted
alphabetically, per subsystem's name(*).
(*) Currently, MAINTAINERS file has several entries not sorted.
One has to run:
scripts/parse-maintainers.pl --input MAINTAINERS --output MAINTAINERS.new
to sort it.
The TOC tree needs to use paths relative to the document containing
the maintainers-profile-toc directive. Fix it.
While here, address a warning from sashiko-bot, which points
that using partition can be problematic if the root Linux path
ends being something like:
foo/Documentation/linux/
causing the documentation dir to be at:
foo/Documentation/linux/Documentation
Very unlikely, but fixing it is trivial: just use regex to
pick the last one.
Notice that I dropped the comment about using os.fspath() as
the logic already uses os.path.abspath() which should work
equally well.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <2b07e12eaa07bf81824ad427335783b170e01dba.1778309595.git.mchehab+huawei@kernel.org>
Instead of one big __init__ code, split the MaintainersParser
code in a way that the state machine remains on __init__, but
the actual parser for descriptions and subsystems are moved
to separate functions.
To make parser easier, instead storing parsed results on a list,
place them directly on a string.
That granted 15% of performance increase(*) with Python 3.14 and
made the logic simpler.
(*) measured by creating a new directory under Documentation/,
and placing justmaintainers.rst and an index file there,
building it via sphinx-build-wrapper.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <0b72530cf496ce5e2987ca784058a50f4dc814d2.1777987027.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <26376e92a5e31e5d285b8676ed443a247b42e4c5.1778309595.git.mchehab+huawei@kernel.org>
"Advice" is an uncountable noun, so "these advices" is grammatically
incorrect.
Replace it with "all of this advice" instead, which keeps the sentence
grammatical while also making it clear that it refers to the full set of
recommendations in the paragraph.
Signed-off-by: Chen-Shi-Hong <eric039eric@gmail.com>
Reviewed-by: WangYuli <wangyl5933@chinaunicom.cn>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260514082808.655-1-eric039eric@gmail.com>
The threat-model document says that only users with CAP_SYS_ADMIN can carry
out a number of admin-level tasks, but there are numerous capabilities that
can confer that sort of power. Generalize the text slightly to make it
clear that CAP_SYS_ADMIN is not the only all-powerful capability.
Acked-by: Willy Tarreau <w@1wt.eu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rather than make readers search for this document, just a link to it where
it is referenced.
(While I was at it, I removed the unused and unneeded _threatmodel label
from the top of threat-model.rst).
Acked-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
AI tools are increasingly used to assist in bug discovery. While these
tools can identify valid issues, reports that are submitted without
manual verification often lack context, contain speculative impact
assessments, or include unnecessary formatting. Such reports increase
triage effort, waste maintainers' time and may be ignored.
Reports where the reporter has verified the issue and the proposed fix
typically meet quality standards. This documentation outlines specific
requirements for length, formatting, and impact evaluation to reduce
the effort needed to deal with these reports.
Cc: Greg KH <gregkh@linuxfoundation.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260509094755.2838-4-w@1wt.eu>
The use of automated tools to find bugs in random locations of the kernel
induces a raise of security reports even if most of them should just be
reported as regular bugs. This patch is an attempt at drawing a line
between what qualifies as a security bug and what does not, hoping to
improve the situation and ease decision on the reporter's side.
It defers the enumeration to a new file, threat-model.rst, that tries
to enumerate various classes of issues that are and are not security
bugs. This should permit to more easily update this file for various
subsystem-specific rules without having to revisit the security bug
reporting guide.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Suggested-by: Leon Romanovsky <leon@kernel.org>
Suggested-by: Greg KH <gregkh@linuxfoundation.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260509094755.2838-3-w@1wt.eu>
With the increase of automated reports, the security team is dealing
with way more messages than really needed. The reporting process works
well with most teams so there is no need to systematically involve the
security team in reports.
Let's suggest to keep it for small lists of recipients and new reporters
only. This should continue to cover the risk of lost messages while
reducing the volume from prolific reporters.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260509094755.2838-2-w@1wt.eu>
Mauro says:
This patch series change the way maintainer entry profile links
are added to the documentation. Instead of having an entry for
each of them at an ReST file, get them from MAINTAINERS content.
That should likely make easier to maintain, as there will be a single
point to place all such profiles.
The output is a per-subsystem sorted (*) series of links shown as a
list like this:
- Arm And Arm64 Soc Sub-Architectures (Common Parts)
- Arm/Samsung S3C, S5P And Exynos Arm Architectures
- Arm/Tesla Fsd Soc Support
...
- Xfs Filesystem
Please notice that the series is doing one logical change per patch.
I could have merged some changes altogether, but I opted doing it
in small steps to help reviews. If you prefer, feel free to merge
maintainers_include changes on merge.
There is one interesting side effect of this series: there is no
need to add rst files containing profiles inside a TOC tree: Just
creating the file anywhere inside Documentation and adding a P entry
is enough. Adding them to a TOC won't hurt.
There are three "types" of profiles:
1. Profiles already included inside subsystem-specific documentation.
This is the most common case;
2. Profiles that are hosted externally;
3. Profiles that are at the same location as maintainer-handbooks.rst.
For (3), we need to create a TOC, as they don't exist elsewhere.
Change the logic to create TOC just for (3), prepending the
content of maintainer-handbooks with a sorted entry of all types,
before the TOC.
With such change, we can have an unique sorted list of profiles,
having the subsystem names used there listed.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <10d06a3f530e07ad981aba93617a9a7f4d63c408.1777295258.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <46961bc932be804cec19f06d202c23423d4aa12a.1777295258.git.mchehab+huawei@kernel.org>
Fix grammar and punctuation.
Add a missing struct member (pm_nb) and its description.
Add a subheading for Helper Functions between the struct descriptions
and just pure helper functions.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260228010402.2389343-5-rdunlap@infradead.org>
fs/cramfs/README still carries a "Future Development" section written
around the Linux 2.3.39 era discussing design decisions that have long
since been settled:
- Block size is 4096 and matches PAGE_SIZE on the reader.
- Endianness is host-endian; mkcramfs -B / -L handles cross-builds.
- Block-pointer extensions (CRAMFS_FLAG_EXT_BLOCK_POINTERS) ended up
being the answer to layout flexibility rather than inode growth.
Drop the stale forward-looking section -- the factual format
description above remains accurate and is kept as-is.
While here, replace the dead sourceforge URL in the "Tools" section
with the current location of the user-space tools on github.
Signed-off-by: Nicolas Pitre <nico@fluxnic.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260422211039.270552-2-nico@fluxnic.net>
Two paragraphs in cramfs.rst have been misleading for a long time:
- "Hard links are supported, but hard linked files will still have
a link count of 1": mkcramfs does not preserve hard links; it
deduplicates by content (eliminate_doubles()). Two names for
the same on-disk inode in the source tree become two separate
(content-shared) entries in the image, and cramfs always reports
a link count of 1.
- "Currently, cramfs must be written and read with architectures of
the same endianness ... PAGE_SIZE == 4096 ... is a bug, but it
hasn't been decided what the best fix is": the endianness
situation has been settled for years -- the kernel checks for
CRAMFS_MAGIC_WEND in cramfs_fill_super() and refuses the mount,
and mkcramfs has gained -B / -L for producing images of the
opposite endianness from the build host (useful for cross-builds,
but the reader still needs to match). Restate this accurately.
Signed-off-by: Nicolas Pitre <nico@fluxnic.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260422211039.270552-1-nico@fluxnic.net>
The sched monitor page was linking to Daniel's website which is now
down. The main purpose of the link was to point to a source for the
models from the original author and that can be found also in his
published paper.
Replace the link with a reference to Daniel's "A thread synchronization
model for the PREEMPT_RT Linux kernel" which can be found online and
includes the models definitions as well as the work behind them (not the
original patches but since they're based on a 5.0 kernel and are mostly
included upstream, there's little value in keeping them in the docs).
Fixes: 03abeaa63c ("Documentation/rv: Add docs for the sched monitors")
Signed-off-by: Gabriele Monaco <gmonaco@redhat.com>
Acked-by: Matteo Martelli <matteo.martelli@codethink.co.uk>
Tested-by: Matteo Martelli <matteo.martelli@codethink.co.uk>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260427131709.170505-2-gmonaco@redhat.com>
The isolcpus= option has been marked as deprecated in 2017. Back then it
was desired for the domain sub option to be configured dynamically at
runtime instead using this boot command line which provides a static
configuration. In the meantime this option was extended by other sub
options which don't have runtime counterpart or it does not make sense
to provide one.
The deprecated part always referred to the default `domain' sub option
but it was not obvious. Also the reasoning behind the deprecation is
sort of dubious: There is nothing wrong with a static configuration if
there is no desired to reconfigure. This is useful on systems which
have one purpose and the CPU partition configuration is not changed for
the entire lifetime.
Remove the "Deprecated" note. Remove the part of the description which
suggest to use cpuset.sched_load_balance and instead point to the
documentation file which explains how to use cpusets to configure this
at runtime.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Acked-by: Waiman Long <longman@redhat.com>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260427150739.bwVmmkj2@linutronix.de>
Fix missing "from" in "prevent <pid> being reused" and
add spacing in vm_area_struct range notation for readability.
No functional changes.
Signed-off-by: Myro Demma <myro@myromyro.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260428133001.11384-1-myro@myromyro.com>
The Portuguese translation of maintainer-kvm-x86.rst exists in the
directory, but it was not listed in the toctree of
maintainer-handbooks.rst.
Add the missing entry to ensure the document is properly indexed and
reachable through the main maintainer handbook page.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260428180208.175472-1-danielmaraboo@gmail.com>
