* Re: [PATCH v4 1/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: SeongJae Park @ 2026-04-30 0:53 UTC (permalink / raw)
To: Manuel Ebner
Cc: SeongJae Park, Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook,
linux-kernel, workflows, linux-sound, linux-media, linux-mm
In-Reply-To: <20260429071445.309733-2-manuelebner@mailbox.org>
On Wed, 29 Apr 2026 09:14:44 +0200 Manuel Ebner <manuelebner@mailbox.org> wrote:
> Update the documentation to reflect new type-aware kmalloc-family as
> suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
> and family")
>
> ptr = kmalloc(sizeof(*ptr), gfp);
> -> ptr = kmalloc_obj(*ptr);
> ptr = kmalloc(sizeof(struct some_obj_name), gfp);
> -> ptr = kmalloc_obj(*ptr);
> ptr = kzalloc(sizeof(*ptr), gfp);
> -> ptr = kzalloc_obj(*ptr);
> ptr = kmalloc_array(count, sizeof(*ptr), gfp);
> -> ptr = kmalloc_objs(*ptr, count);
> ptr = kcalloc(count, sizeof(*ptr), gfp);
> -> ptr = kzalloc_objs(*ptr, count);
>
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
Acked-by: SeongJae Park <sj@kernel.org>
Thanks,
SJ
[...]
^ permalink raw reply
* Re: [PATCH v4 3/3] Documentation: deprecated.rst: kmalloc-family: mark argument as optional
From: Vlastimil Babka @ 2026-04-29 8:01 UTC (permalink / raw)
To: Manuel Ebner, Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook,
linux-kernel
Cc: workflows, linux-mm, Geert Uytterhoeven
In-Reply-To: <20260429072704.311603-2-manuelebner@mailbox.org>
On 4/29/26 09:27, Manuel Ebner wrote:
> put the optional argument (gfp) in square brackets
> add default value = GFP_KERNEL
>
> eg. ptr = kmalloc_obj(*ptr, gfp);
> -> ptr = kmalloc_obj(*ptr [, gfp] );
>
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org>
> ---
> Documentation/process/deprecated.rst | 15 ++++++++-------
> 1 file changed, 8 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
> index fed56864d036..ac75b7ecac47 100644
> --- a/Documentation/process/deprecated.rst
> +++ b/Documentation/process/deprecated.rst
> @@ -392,13 +392,14 @@ allocations. For example, these open coded assignments::
>
> become, respectively::
>
> - ptr = kmalloc_obj(*ptr, gfp);
> - ptr = kzalloc_obj(*ptr, gfp);
> - ptr = kmalloc_objs(*ptr, count, gfp);
> - ptr = kzalloc_objs(*ptr, count, gfp);
> - ptr = kmalloc_flex(*ptr, flex_member, count, gfp);
> - __auto_type ptr = kmalloc_obj(struct foo, gfp);
> -
> + ptr = kmalloc_obj(*ptr [, gfp] );
> + ptr = kzalloc_obj(*ptr [, gfp] );
> + ptr = kmalloc_objs(*ptr, count [, gfp] );
> + ptr = kzalloc_objs(*ptr, count [, gfp] );
> + ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
> + __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
> +
> +The argument gfp is optional, the default value is GFP_KERNEL.
> If `ptr->flex_member` is annotated with __counted_by(), the allocation
> will automatically fail if `count` is larger than the maximum
> representable value that can be stored in the counter member associated
^ permalink raw reply
* Re: [PATCH v4 1/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: Vlastimil Babka @ 2026-04-29 8:00 UTC (permalink / raw)
To: Manuel Ebner, Jonathan Corbet, Shuah Khan, linux-doc
Cc: Kees Cook, linux-kernel, workflows, linux-sound, linux-media,
linux-mm
In-Reply-To: <20260429071445.309733-2-manuelebner@mailbox.org>
On 4/29/26 09:14, Manuel Ebner wrote:
> Update the documentation to reflect new type-aware kmalloc-family as
> suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
> and family")
>
> ptr = kmalloc(sizeof(*ptr), gfp);
> -> ptr = kmalloc_obj(*ptr);
> ptr = kmalloc(sizeof(struct some_obj_name), gfp);
> -> ptr = kmalloc_obj(*ptr);
> ptr = kzalloc(sizeof(*ptr), gfp);
> -> ptr = kzalloc_obj(*ptr);
> ptr = kmalloc_array(count, sizeof(*ptr), gfp);
> -> ptr = kmalloc_objs(*ptr, count);
> ptr = kcalloc(count, sizeof(*ptr), gfp);
> -> ptr = kzalloc_objs(*ptr, count);
>
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org>
^ permalink raw reply
* [PATCH v4 3/3] Documentation: deprecated.rst: kmalloc-family: mark argument as optional
From: Manuel Ebner @ 2026-04-29 7:27 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook, linux-kernel
Cc: workflows, linux-mm, Geert Uytterhoeven, Manuel Ebner
In-Reply-To: <20260429070759.309110-3-manuelebner@mailbox.org>
put the optional argument (gfp) in square brackets
add default value = GFP_KERNEL
eg. ptr = kmalloc_obj(*ptr, gfp);
-> ptr = kmalloc_obj(*ptr [, gfp] );
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
Documentation/process/deprecated.rst | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index fed56864d036..ac75b7ecac47 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -392,13 +392,14 @@ allocations. For example, these open coded assignments::
become, respectively::
- ptr = kmalloc_obj(*ptr, gfp);
- ptr = kzalloc_obj(*ptr, gfp);
- ptr = kmalloc_objs(*ptr, count, gfp);
- ptr = kzalloc_objs(*ptr, count, gfp);
- ptr = kmalloc_flex(*ptr, flex_member, count, gfp);
- __auto_type ptr = kmalloc_obj(struct foo, gfp);
-
+ ptr = kmalloc_obj(*ptr [, gfp] );
+ ptr = kzalloc_obj(*ptr [, gfp] );
+ ptr = kmalloc_objs(*ptr, count [, gfp] );
+ ptr = kzalloc_objs(*ptr, count [, gfp] );
+ ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
+ __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
+
+The argument gfp is optional, the default value is GFP_KERNEL.
If `ptr->flex_member` is annotated with __counted_by(), the allocation
will automatically fail if `count` is larger than the maximum
representable value that can be stored in the counter member associated
--
2.53.0
^ permalink raw reply related
* [PATCH v4 1/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-29 7:14 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc
Cc: Kees Cook, linux-kernel, workflows, linux-sound, linux-media,
linux-mm, Manuel Ebner
In-Reply-To: <20260429070759.309110-3-manuelebner@mailbox.org>
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
and family")
ptr = kmalloc(sizeof(*ptr), gfp);
-> ptr = kmalloc_obj(*ptr);
ptr = kmalloc(sizeof(struct some_obj_name), gfp);
-> ptr = kmalloc_obj(*ptr);
ptr = kzalloc(sizeof(*ptr), gfp);
-> ptr = kzalloc_obj(*ptr);
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
-> ptr = kmalloc_objs(*ptr, count);
ptr = kcalloc(count, sizeof(*ptr), gfp);
-> ptr = kzalloc_objs(*ptr, count);
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
Documentation/core-api/kref.rst | 4 ++--
Documentation/core-api/list.rst | 4 ++--
Documentation/driver-api/mailbox.rst | 4 ++--
Documentation/driver-api/media/v4l2-fh.rst | 2 +-
Documentation/kernel-hacking/locking.rst | 4 ++--
Documentation/locking/locktypes.rst | 4 ++--
Documentation/process/coding-style.rst | 8 ++++----
.../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
Documentation/spi/spi-summary.rst | 4 ++--
.../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
.../translations/it_IT/locking/locktypes.rst | 4 ++--
.../translations/it_IT/process/coding-style.rst | 2 +-
.../translations/sp_SP/process/coding-style.rst | 2 +-
Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/video4linux/v4l2-framework.txt | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
18 files changed, 36 insertions(+), 36 deletions(-)
diff --git a/Documentation/core-api/kref.rst b/Documentation/core-api/kref.rst
index 8db9ff03d952..1c14c036699d 100644
--- a/Documentation/core-api/kref.rst
+++ b/Documentation/core-api/kref.rst
@@ -40,7 +40,7 @@ kref_init as so::
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -100,7 +100,7 @@ thread to process::
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst
index 241464ca0549..86cd0a1b77ea 100644
--- a/Documentation/core-api/list.rst
+++ b/Documentation/core-api/list.rst
@@ -112,7 +112,7 @@ list:
/* State 1 */
- grock = kzalloc(sizeof(*grock), GFP_KERNEL);
+ grock = kzalloc_obj(*grock);
if (!grock)
return -ENOMEM;
grock->name = "Grock";
@@ -123,7 +123,7 @@ list:
/* State 2 */
- dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL);
+ dimitri = kzalloc_obj(*dimitri);
if (!dimitri)
return -ENOMEM;
dimitri->name = "Dimitri";
diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst
index 463dd032b96c..4bcd73a99115 100644
--- a/Documentation/driver-api/mailbox.rst
+++ b/Documentation/driver-api/mailbox.rst
@@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately).
struct async_pkt ap;
struct sync_pkt sp;
- dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
- dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
+ dc_sync = kzalloc_obj(*dc_sync);
+ dc_async = kzalloc_obj(*dc_async);
/* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev;
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index a934caa483a4..38319130ebf5 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -42,7 +42,7 @@ Example:
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh);
...
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index dff0646a717b..d02e62367c4f 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 37b6a5670c2f..ac1ad722a9e7 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code
works perfectly::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
But this code fails on PREEMPT_RT kernels because the memory allocator is
fully preemptible and therefore cannot be invoked from truly atomic
@@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable
preemption on PREEMPT_RT kernels::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 35b381230f6e..a3bf75dc7c88 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -936,7 +936,7 @@ used.
---------------------
The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
+kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
@@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
@@ -959,13 +959,13 @@ The preferred form for allocating an array is the following:
.. code-block:: c
- p = kmalloc_array(n, sizeof(...), ...);
+ p = kmalloc_objs(*ptr, n, ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
- p = kcalloc(n, sizeof(...), ...);
+ p = kzalloc_objs(*ptr, n, ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 895752cbcedd..12433612aa9c 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -266,7 +266,7 @@ to details explained in the following section.
....
/* allocate a chip-specific data with zero filled */
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
if (chip == NULL)
return -ENOMEM;
@@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()`
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
The chip record should have the field to hold the card pointer at least,
@@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below::
return -ENXIO;
}
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
@@ -1737,7 +1737,7 @@ callback::
{
struct my_pcm_data *data;
....
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
substream->runtime->private_data = data;
....
}
@@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
- struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
+ struct mydata *p = kmalloc_obj(*p);
hw->private_data = p;
hw->private_free = mydata_free;
@@ -3833,7 +3833,7 @@ chip data individually::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
....
card->private_data = chip;
....
diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst
index 6e21e6f86912..7ad6af76c247 100644
--- a/Documentation/spi/spi-summary.rst
+++ b/Documentation/spi/spi-summary.rst
@@ -249,7 +249,7 @@ And SOC-specific utility code might look something like::
{
struct mysoc_spi_data *pdata2;
- pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
+ pdata2 = kmalloc_obj(*pdata2);
*pdata2 = pdata;
...
if (n == 2) {
@@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master).
return -ENODEV;
/* get memory for driver's per-chip state */
- chip = kzalloc(sizeof *chip, GFP_KERNEL);
+ chip = kzalloc(*chip);
if (!chip)
return -ENOMEM;
spi_set_drvdata(spi, chip);
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4c21cf60f775..acca89a3743a 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst
index 1c7056283b9d..d5fa36aa05cc 100644
--- a/Documentation/translations/it_IT/locking/locktypes.rst
+++ b/Documentation/translations/it_IT/locking/locktypes.rst
@@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di
memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di
memoria può essere oggetto di prelazione e quindi non può essere chiamato in un
@@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel
PREEMPT_RT::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index c0dc786b8474..2a499412a2e3 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa, dove il nome della struttura viene scritto interamente,
peggiora la leggibilità e introduce possibili bachi quando il tipo di
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 7d63aa8426e6..44c93d5f6beb 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia
diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
index b9902af310c5..fcff01e99852 100644
--- a/Documentation/translations/zh_CN/core-api/kref.rst
+++ b/Documentation/translations/zh_CN/core-api/kref.rst
@@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -106,7 +106,7 @@ Kref规则
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 5a342a024c01..55d5da974d89 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能
会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof
diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index f0be21a60a0f..ba43c5c4797c 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -799,7 +799,7 @@ int my_open(struct file *file)
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh);
...
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index e2ba97b3d8bb..63c78982a1af 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能
會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof
--
2.53.0
^ permalink raw reply related
* [PATCH v4 0/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-29 7:08 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook
Cc: linux-kernel, workflows, linux-sound, rcu, linux-media, linux-mm,
Manuel Ebner
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
and family")
[v3] -> [v4]:
state the default argument in deprecated.rst [3/3]
[v2] -> [v3]:
remove obvious wrong replacements in [1/3]
add Acked-by: Paul E. McKenney in [2/3]
change how to mark the optional argument in [3/3]
add recipants
--cc="linux-mm@kvack.org"
--to="Kees Cook"
--cc="Geert Uytterhoeven"
[v1] -> [v2]:
put RCU/* in a seperate patch [Patch 2/3]
Omit optional argument (GFP_KERNEL) as suggested by https://lwn.net/Articles/1062856/
deprecated.rst: change the argument gfp to optional [Patch 3/3]
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Greg KH @ 2026-04-29 6:10 UTC (permalink / raw)
To: Willy Tarreau
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <afF2d6RzRf2Flnv7@1wt.eu>
On Wed, Apr 29, 2026 at 05:09:43AM +0200, Willy Tarreau wrote:
> On Tue, Apr 28, 2026 at 03:13:01PM -0600, Greg KH wrote:
> > > > We can point at other files, as this list is going to get long over
> > > > time, which is a good thing.
> > >
> > > Sure. I'm just unsure where this could be enumerated, as it's likely
> > > that there would be just one or two lines max per subsystem for the
> > > majority of them. Or we could have a totally separate file, "threat
> > > model", that goes into great lengths detailing all this with sections
> > > per category or subsystem when they start to grow maybe, and refer only
> > > to that one from security-bugs ?
> >
> > I think a separate file is good, I know I need to write up what the USB
> > model is, and it's different from PCI, and different from other
> > subsystems. All should probably be documented eventually.
>
> Would you be interested in me trying to initiate a new "threat-model.rst"
> file that tries to unroll the points mentioned in the list ? I'm concerned
> that that withuot having many details initially, it could look a bit odd,
> because the list we currently have would be more suitable for an "other"
> section.
Sure, a small file to start with would be good for people to work off
of and add to.
> > > > > > (like what the IB subsystem does which I
> > > > > > don't think you listed above, or the USB subsystem.)
> > > > >
> > > > > Indeed I didn't list IB (I'm never sure about it, I seem to remember
> > > > > we simply trust any peer, is that right?), nor did I make specific
> > > > > mentions for USB which is implicitly covered by "hardware emulation
> > > > > or modification".
> > > >
> > > > Ah, but USB does cover "some" modification of devices, so this is going
> > > > to be something that is good to document over time, if for no other
> > > > reason to keep these scanning tools in check from hallucinating crazy
> > > > situations that are obviously not a valid thing we care about.
> > >
> > > OK but does this mean you still want to get these reports in the end ?
> >
> > I want a patch if a user cares about that threat-model (as Android does
> > but no one else) as it's up to the user groups that want to change the
> > default kernel's behavior like this to actually submit patches to do so.
>
> Yes, OK, but we want them in any case. That's the idea I tried to convey
> in the proposed doc (maybe not well enough), basically "this is a bug and
> it is worth reporting, but no need to involve s@k.o for this".
Yes, you conveyed that, sorry if I insinuated otherwise.
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-04-29 3:09 UTC (permalink / raw)
To: Greg KH
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <2026042804-overbook-ripeness-73dd@gregkh>
On Tue, Apr 28, 2026 at 03:13:01PM -0600, Greg KH wrote:
> > > We can point at other files, as this list is going to get long over
> > > time, which is a good thing.
> >
> > Sure. I'm just unsure where this could be enumerated, as it's likely
> > that there would be just one or two lines max per subsystem for the
> > majority of them. Or we could have a totally separate file, "threat
> > model", that goes into great lengths detailing all this with sections
> > per category or subsystem when they start to grow maybe, and refer only
> > to that one from security-bugs ?
>
> I think a separate file is good, I know I need to write up what the USB
> model is, and it's different from PCI, and different from other
> subsystems. All should probably be documented eventually.
Would you be interested in me trying to initiate a new "threat-model.rst"
file that tries to unroll the points mentioned in the list ? I'm concerned
that that withuot having many details initially, it could look a bit odd,
because the list we currently have would be more suitable for an "other"
section.
> > > > > (like what the IB subsystem does which I
> > > > > don't think you listed above, or the USB subsystem.)
> > > >
> > > > Indeed I didn't list IB (I'm never sure about it, I seem to remember
> > > > we simply trust any peer, is that right?), nor did I make specific
> > > > mentions for USB which is implicitly covered by "hardware emulation
> > > > or modification".
> > >
> > > Ah, but USB does cover "some" modification of devices, so this is going
> > > to be something that is good to document over time, if for no other
> > > reason to keep these scanning tools in check from hallucinating crazy
> > > situations that are obviously not a valid thing we care about.
> >
> > OK but does this mean you still want to get these reports in the end ?
>
> I want a patch if a user cares about that threat-model (as Android does
> but no one else) as it's up to the user groups that want to change the
> default kernel's behavior like this to actually submit patches to do so.
Yes, OK, but we want them in any case. That's the idea I tried to convey
in the proposed doc (maybe not well enough), basically "this is a bug and
it is worth reporting, but no need to involve s@k.o for this".
thanks,
Willy
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Greg KH @ 2026-04-28 21:13 UTC (permalink / raw)
To: Willy Tarreau
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <ae-LVyDQPVwxesCO@1wt.eu>
On Mon, Apr 27, 2026 at 06:14:15PM +0200, Willy Tarreau wrote:
> On Mon, Apr 27, 2026 at 09:35:04AM -0600, Greg KH wrote:
> > On Mon, Apr 27, 2026 at 05:27:46PM +0200, Willy Tarreau wrote:
> > > On Mon, Apr 27, 2026 at 07:48:23AM -0600, Greg KH wrote:
> > > > On Sun, Apr 26, 2026 at 06:39:13PM +0200, Willy Tarreau wrote:
> > > > > +In the Linux kernel's threat model, an issue is **not** a security bug, and
> > > > > +should not be reported to the security list, when triggering it requires the
> > > > > +reporter to first undermine the system they are attacking. This includes, but
> > > > > +is not limited to, behavior that only manifests after the administrator has
> > > > > +explicitly enabled it (loading a module, setting a sysctl, writing to a debugfs
> > > > > +knob, or otherwise using an interface documented as privileged or unsafe); bugs
> > > > > +reachable only through root or CAP_SYS_ADMIN or CAP_NET_ADMIN on a machine the
> > > > > +actor already fully controls, with no further privilege boundary being crossed;
> > > > > +prediction of random numbers that only works in a totally silent environment
> > > > > +(such as IP ID, TCP ports or sequence numbers that can only be guessed in a
> > > > > +lab), issues that appear only in debug, lockdep, KASAN, fault-injection,
> > > > > +CONFIG_NOMMU, or other developer-oriented kernel builds that are not intended
> > > > > +for production use; problems seen only under development simulators, emulators,
> > > > > +or fuzzing harnesses that present hardware or input states which cannot occur
> > > > > +on real systems; bugs that require modified or emulated hardware; missing
> > > > > +hardening or defence-in-depth suggestions with no demonstrable exploit path
> > > > > +(including local ASLR bypass); mounting file systems that would be fixed or
> > > > > +rejected by fsck; and bugs in out-of-tree modules or vendor forks, which should
> > > > > +be reported to the relevant vendor. Functional and performance regressions,
> > > > > +and disagreements with documented kernel policy (for example, "root can load
> > > > > +modules"), are likewise ordinary bugs or feature requests rather than security
> > > > > +issues, and should be reported via the usual channels.
> > > >
> > > > This is a great list to start with, but perhaps we should put it in list
> > > > form so that it's easier to read?
> > >
> > > In fact that's what I tried first and it was super long with many short
> > > lines, making it possibly worse. But maybe aggregating several short
> > > entries on a line by similarities could work, I can give it a try.
> > >
> > > > Also, I can see this turning into a separate document eventually as
> > > > different subsystems should have a chance to weigh in on what they
> > > > consider the threat model to be
> > >
> > > My fear if we redirect to other files is that it won't be read again.
> > > However, we could possibly suggest to always look for the subsystem's
> > > specific rules in this subsytem's doc, leaving enough freedom to
> > > maintainers to reject more things.
> >
> > AI tools are good at following links, so I wouldn't worry about that.
>
> Yes but let's not forget the minority of humble humans still sending
> honest reports ;-)
>
> > We can point at other files, as this list is going to get long over
> > time, which is a good thing.
>
> Sure. I'm just unsure where this could be enumerated, as it's likely
> that there would be just one or two lines max per subsystem for the
> majority of them. Or we could have a totally separate file, "threat
> model", that goes into great lengths detailing all this with sections
> per category or subsystem when they start to grow maybe, and refer only
> to that one from security-bugs ?
I think a separate file is good, I know I need to write up what the USB
model is, and it's different from PCI, and different from other
subsystems. All should probably be documented eventually.
> > > > (like what the IB subsystem does which I
> > > > don't think you listed above, or the USB subsystem.)
> > >
> > > Indeed I didn't list IB (I'm never sure about it, I seem to remember
> > > we simply trust any peer, is that right?), nor did I make specific
> > > mentions for USB which is implicitly covered by "hardware emulation
> > > or modification".
> >
> > Ah, but USB does cover "some" modification of devices, so this is going
> > to be something that is good to document over time, if for no other
> > reason to keep these scanning tools in check from hallucinating crazy
> > situations that are obviously not a valid thing we care about.
>
> OK but does this mean you still want to get these reports in the end ?
I want a patch if a user cares about that threat-model (as Android does
but no one else) as it's up to the user groups that want to change the
default kernel's behavior like this to actually submit patches to do so.
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-04-27 16:14 UTC (permalink / raw)
To: Greg KH
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <2026042724-bullhorn-bobtail-ae6f@gregkh>
On Mon, Apr 27, 2026 at 09:35:04AM -0600, Greg KH wrote:
> On Mon, Apr 27, 2026 at 05:27:46PM +0200, Willy Tarreau wrote:
> > On Mon, Apr 27, 2026 at 07:48:23AM -0600, Greg KH wrote:
> > > On Sun, Apr 26, 2026 at 06:39:13PM +0200, Willy Tarreau wrote:
> > > > +In the Linux kernel's threat model, an issue is **not** a security bug, and
> > > > +should not be reported to the security list, when triggering it requires the
> > > > +reporter to first undermine the system they are attacking. This includes, but
> > > > +is not limited to, behavior that only manifests after the administrator has
> > > > +explicitly enabled it (loading a module, setting a sysctl, writing to a debugfs
> > > > +knob, or otherwise using an interface documented as privileged or unsafe); bugs
> > > > +reachable only through root or CAP_SYS_ADMIN or CAP_NET_ADMIN on a machine the
> > > > +actor already fully controls, with no further privilege boundary being crossed;
> > > > +prediction of random numbers that only works in a totally silent environment
> > > > +(such as IP ID, TCP ports or sequence numbers that can only be guessed in a
> > > > +lab), issues that appear only in debug, lockdep, KASAN, fault-injection,
> > > > +CONFIG_NOMMU, or other developer-oriented kernel builds that are not intended
> > > > +for production use; problems seen only under development simulators, emulators,
> > > > +or fuzzing harnesses that present hardware or input states which cannot occur
> > > > +on real systems; bugs that require modified or emulated hardware; missing
> > > > +hardening or defence-in-depth suggestions with no demonstrable exploit path
> > > > +(including local ASLR bypass); mounting file systems that would be fixed or
> > > > +rejected by fsck; and bugs in out-of-tree modules or vendor forks, which should
> > > > +be reported to the relevant vendor. Functional and performance regressions,
> > > > +and disagreements with documented kernel policy (for example, "root can load
> > > > +modules"), are likewise ordinary bugs or feature requests rather than security
> > > > +issues, and should be reported via the usual channels.
> > >
> > > This is a great list to start with, but perhaps we should put it in list
> > > form so that it's easier to read?
> >
> > In fact that's what I tried first and it was super long with many short
> > lines, making it possibly worse. But maybe aggregating several short
> > entries on a line by similarities could work, I can give it a try.
> >
> > > Also, I can see this turning into a separate document eventually as
> > > different subsystems should have a chance to weigh in on what they
> > > consider the threat model to be
> >
> > My fear if we redirect to other files is that it won't be read again.
> > However, we could possibly suggest to always look for the subsystem's
> > specific rules in this subsytem's doc, leaving enough freedom to
> > maintainers to reject more things.
>
> AI tools are good at following links, so I wouldn't worry about that.
Yes but let's not forget the minority of humble humans still sending
honest reports ;-)
> We can point at other files, as this list is going to get long over
> time, which is a good thing.
Sure. I'm just unsure where this could be enumerated, as it's likely
that there would be just one or two lines max per subsystem for the
majority of them. Or we could have a totally separate file, "threat
model", that goes into great lengths detailing all this with sections
per category or subsystem when they start to grow maybe, and refer only
to that one from security-bugs ?
> > > (like what the IB subsystem does which I
> > > don't think you listed above, or the USB subsystem.)
> >
> > Indeed I didn't list IB (I'm never sure about it, I seem to remember
> > we simply trust any peer, is that right?), nor did I make specific
> > mentions for USB which is implicitly covered by "hardware emulation
> > or modification".
>
> Ah, but USB does cover "some" modification of devices, so this is going
> to be something that is good to document over time, if for no other
> reason to keep these scanning tools in check from hallucinating crazy
> situations that are obviously not a valid thing we care about.
OK but does this mean you still want to get these reports in the end ?
Willy
^ permalink raw reply
* Re: [PATCH 1/3] Documentation: security-bugs: do not systematically Cc the security team
From: Willy Tarreau @ 2026-04-27 16:09 UTC (permalink / raw)
To: Greg KH
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <2026042727-unselect-unlaced-37bb@gregkh>
On Mon, Apr 27, 2026 at 09:33:12AM -0600, Greg KH wrote:
> On Mon, Apr 27, 2026 at 05:24:06PM +0200, Willy Tarreau wrote:
> > On Mon, Apr 27, 2026 at 07:49:08AM -0600, Greg KH wrote:
> > > On Sun, Apr 26, 2026 at 06:39:12PM +0200, Willy Tarreau wrote:
> > > > 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, to cover the
> > > > risk of lost messages (spam, vacation etc) but to avoid it for larger
> > > > teams.
> > > >
> > > > Cc: Greg KH <gregkh@linuxfoundation.org>
> > > > Cc: Leon Romanovsky <leon@kernel.org>
> > > > Signed-off-by: Willy Tarreau <w@1wt.eu>
> > >
> > > This is going to cut down on emails to us a bunch, which might be good,
> > > or not, as now we'll not have a way to know what's going on overall.
> > > But hey, let's try it and see what happens!
> >
> > Or maybe we could suggest that first reports from a reporter should
> > always Cc the list ? After all, every time we asked to drop the list
> > was for senders at their 5th or 10th submission. Maybe we could just
> > say that the list members prefer not being repetitively CCed by the
> > same submitters to invest more time on newcomers ?
>
> Yes, that might be better, otherwise maintainers are going to get some
> pretty foolish reports with out the context of howing to properly at
> least push back on them, like we have gotten good at doing :)
Yes, and more importantly, we know how to react while some maintainers
getting their first report are stressed. Let me try to rework it.
Thanks!
Willy
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Greg KH @ 2026-04-27 15:35 UTC (permalink / raw)
To: Willy Tarreau
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <ae-Acm2XJ3sR34Il@1wt.eu>
On Mon, Apr 27, 2026 at 05:27:46PM +0200, Willy Tarreau wrote:
> On Mon, Apr 27, 2026 at 07:48:23AM -0600, Greg KH wrote:
> > On Sun, Apr 26, 2026 at 06:39:13PM +0200, Willy Tarreau wrote:
> > > +In the Linux kernel's threat model, an issue is **not** a security bug, and
> > > +should not be reported to the security list, when triggering it requires the
> > > +reporter to first undermine the system they are attacking. This includes, but
> > > +is not limited to, behavior that only manifests after the administrator has
> > > +explicitly enabled it (loading a module, setting a sysctl, writing to a debugfs
> > > +knob, or otherwise using an interface documented as privileged or unsafe); bugs
> > > +reachable only through root or CAP_SYS_ADMIN or CAP_NET_ADMIN on a machine the
> > > +actor already fully controls, with no further privilege boundary being crossed;
> > > +prediction of random numbers that only works in a totally silent environment
> > > +(such as IP ID, TCP ports or sequence numbers that can only be guessed in a
> > > +lab), issues that appear only in debug, lockdep, KASAN, fault-injection,
> > > +CONFIG_NOMMU, or other developer-oriented kernel builds that are not intended
> > > +for production use; problems seen only under development simulators, emulators,
> > > +or fuzzing harnesses that present hardware or input states which cannot occur
> > > +on real systems; bugs that require modified or emulated hardware; missing
> > > +hardening or defence-in-depth suggestions with no demonstrable exploit path
> > > +(including local ASLR bypass); mounting file systems that would be fixed or
> > > +rejected by fsck; and bugs in out-of-tree modules or vendor forks, which should
> > > +be reported to the relevant vendor. Functional and performance regressions,
> > > +and disagreements with documented kernel policy (for example, "root can load
> > > +modules"), are likewise ordinary bugs or feature requests rather than security
> > > +issues, and should be reported via the usual channels.
> >
> > This is a great list to start with, but perhaps we should put it in list
> > form so that it's easier to read?
>
> In fact that's what I tried first and it was super long with many short
> lines, making it possibly worse. But maybe aggregating several short
> entries on a line by similarities could work, I can give it a try.
>
> > Also, I can see this turning into a separate document eventually as
> > different subsystems should have a chance to weigh in on what they
> > consider the threat model to be
>
> My fear if we redirect to other files is that it won't be read again.
> However, we could possibly suggest to always look for the subsystem's
> specific rules in this subsytem's doc, leaving enough freedom to
> maintainers to reject more things.
AI tools are good at following links, so I wouldn't worry about that.
We can point at other files, as this list is going to get long over
time, which is a good thing.
> > (like what the IB subsystem does which I
> > don't think you listed above, or the USB subsystem.)
>
> Indeed I didn't list IB (I'm never sure about it, I seem to remember
> we simply trust any peer, is that right?), nor did I make specific
> mentions for USB which is implicitly covered by "hardware emulation
> or modification".
Ah, but USB does cover "some" modification of devices, so this is going
to be something that is good to document over time, if for no other
reason to keep these scanning tools in check from hallucinating crazy
situations that are obviously not a valid thing we care about.
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH 1/3] Documentation: security-bugs: do not systematically Cc the security team
From: Greg KH @ 2026-04-27 15:33 UTC (permalink / raw)
To: Willy Tarreau
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <ae9_ljvxw5I9arzQ@1wt.eu>
On Mon, Apr 27, 2026 at 05:24:06PM +0200, Willy Tarreau wrote:
> On Mon, Apr 27, 2026 at 07:49:08AM -0600, Greg KH wrote:
> > On Sun, Apr 26, 2026 at 06:39:12PM +0200, Willy Tarreau wrote:
> > > 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, to cover the
> > > risk of lost messages (spam, vacation etc) but to avoid it for larger
> > > teams.
> > >
> > > Cc: Greg KH <gregkh@linuxfoundation.org>
> > > Cc: Leon Romanovsky <leon@kernel.org>
> > > Signed-off-by: Willy Tarreau <w@1wt.eu>
> >
> > This is going to cut down on emails to us a bunch, which might be good,
> > or not, as now we'll not have a way to know what's going on overall.
> > But hey, let's try it and see what happens!
>
> Or maybe we could suggest that first reports from a reporter should
> always Cc the list ? After all, every time we asked to drop the list
> was for senders at their 5th or 10th submission. Maybe we could just
> say that the list members prefer not being repetitively CCed by the
> same submitters to invest more time on newcomers ?
Yes, that might be better, otherwise maintainers are going to get some
pretty foolish reports with out the context of howing to properly at
least push back on them, like we have gotten good at doing :)
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-04-27 15:27 UTC (permalink / raw)
To: Greg KH
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <2026042753-ozone-jigsaw-4ad5@gregkh>
On Mon, Apr 27, 2026 at 07:48:23AM -0600, Greg KH wrote:
> On Sun, Apr 26, 2026 at 06:39:13PM +0200, Willy Tarreau wrote:
> > +In the Linux kernel's threat model, an issue is **not** a security bug, and
> > +should not be reported to the security list, when triggering it requires the
> > +reporter to first undermine the system they are attacking. This includes, but
> > +is not limited to, behavior that only manifests after the administrator has
> > +explicitly enabled it (loading a module, setting a sysctl, writing to a debugfs
> > +knob, or otherwise using an interface documented as privileged or unsafe); bugs
> > +reachable only through root or CAP_SYS_ADMIN or CAP_NET_ADMIN on a machine the
> > +actor already fully controls, with no further privilege boundary being crossed;
> > +prediction of random numbers that only works in a totally silent environment
> > +(such as IP ID, TCP ports or sequence numbers that can only be guessed in a
> > +lab), issues that appear only in debug, lockdep, KASAN, fault-injection,
> > +CONFIG_NOMMU, or other developer-oriented kernel builds that are not intended
> > +for production use; problems seen only under development simulators, emulators,
> > +or fuzzing harnesses that present hardware or input states which cannot occur
> > +on real systems; bugs that require modified or emulated hardware; missing
> > +hardening or defence-in-depth suggestions with no demonstrable exploit path
> > +(including local ASLR bypass); mounting file systems that would be fixed or
> > +rejected by fsck; and bugs in out-of-tree modules or vendor forks, which should
> > +be reported to the relevant vendor. Functional and performance regressions,
> > +and disagreements with documented kernel policy (for example, "root can load
> > +modules"), are likewise ordinary bugs or feature requests rather than security
> > +issues, and should be reported via the usual channels.
>
> This is a great list to start with, but perhaps we should put it in list
> form so that it's easier to read?
In fact that's what I tried first and it was super long with many short
lines, making it possibly worse. But maybe aggregating several short
entries on a line by similarities could work, I can give it a try.
> Also, I can see this turning into a separate document eventually as
> different subsystems should have a chance to weigh in on what they
> consider the threat model to be
My fear if we redirect to other files is that it won't be read again.
However, we could possibly suggest to always look for the subsystem's
specific rules in this subsytem's doc, leaving enough freedom to
maintainers to reject more things.
> (like what the IB subsystem does which I
> don't think you listed above, or the USB subsystem.)
Indeed I didn't list IB (I'm never sure about it, I seem to remember
we simply trust any peer, is that right?), nor did I make specific
mentions for USB which is implicitly covered by "hardware emulation
or modification".
thanks!
Willy
^ permalink raw reply
* Re: [PATCH 1/3] Documentation: security-bugs: do not systematically Cc the security team
From: Willy Tarreau @ 2026-04-27 15:24 UTC (permalink / raw)
To: Greg KH
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel
In-Reply-To: <2026042727-recital-twiddling-eb22@gregkh>
On Mon, Apr 27, 2026 at 07:49:08AM -0600, Greg KH wrote:
> On Sun, Apr 26, 2026 at 06:39:12PM +0200, Willy Tarreau wrote:
> > 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, to cover the
> > risk of lost messages (spam, vacation etc) but to avoid it for larger
> > teams.
> >
> > Cc: Greg KH <gregkh@linuxfoundation.org>
> > Cc: Leon Romanovsky <leon@kernel.org>
> > Signed-off-by: Willy Tarreau <w@1wt.eu>
>
> This is going to cut down on emails to us a bunch, which might be good,
> or not, as now we'll not have a way to know what's going on overall.
> But hey, let's try it and see what happens!
Or maybe we could suggest that first reports from a reporter should
always Cc the list ? After all, every time we asked to drop the list
was for senders at their 5th or 10th submission. Maybe we could just
say that the list members prefer not being repetitively CCed by the
same submitters to invest more time on newcomers ?
> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Thanks!
willy
^ permalink raw reply
* [PATCH v4 09/10] docs: maintainers_include: fix support for O=dir
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
os.path.relpath() will do the wrong thing with O=dir, as the build
system uses "cd <dir>" internally.
Solve it by using app.srcdir, which, on normal cases, point to
Documentation/, or, when SPHINXDIRS=process, it will be set with
Documentation/process.
While here, remove a dead code while writing maintainer profiles,
as now all entries should have both profile and entry.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 71 +++++++++++++++------
1 file changed, 50 insertions(+), 21 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5413c1350bba..ae52e8198750 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -27,15 +27,24 @@ from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
+#
+# Base URL for intersphinx-like links to maintainer profiles
+#
+KERNELDOC_URL = "https://docs.kernel.org/"
+
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
__version__ = '1.0'
+app_dir = "."
+
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, base_path, path):
+ def __init__(self, path):
+ global app_dir
+
self.profile_toc = set()
self.profile_entries = {}
@@ -57,6 +66,9 @@ class MaintainersParser:
field_content = ""
subsystem_name = None
+ base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
+ print("BASE DIR", base_dir)
+
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
if descriptions and line.startswith('Maintainers'):
@@ -76,9 +88,25 @@ class MaintainersParser:
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ match = re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line)
if match:
- entry = os.path.relpath(match.group(1), base_path)
+ name = "".join(match.groups())
+ entry = os.path.relpath(base_dir + name, app_dir)
+
+ full_name = os.path.join(base_dir, name)
+ path = os.path.relpath(full_name, app_dir)
+ #
+ # When SPHINXDIRS is used, it will try to reference files
+ # outside srctree, causing warnings. To avoid that, point
+ # to the latest official documentation
+ #
+ if path.startswith("../"):
+ entry = KERNELDOC_URL + match.group(2) + ".html"
+ else:
+ entry = "/" + entry
+
+ print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
+
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -189,10 +217,10 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- output = MaintainersParser(base_path, path).output
+ output = MaintainersParser(path).output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -213,11 +241,10 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -227,27 +254,20 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- maint = MaintainersParser(base_path, path)
+ maint = MaintainersParser(path)
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
-
- for profile, entry in maint.profile_entries.items():
+ for profile, entry in sorted(maint.profile_entries.items()):
if entry.startswith("http"):
- if profile:
- output += f"- `{profile} <{entry}>`_\n"
- else:
- output += f"- `<{entry}>_`\n"
+ output += f"- `{profile} <{entry}>`_\n"
else:
- if profile:
- output += f"- :doc:`{profile} <{entry}>`\n"
- else:
- output += f"- :doc:`<{entry}>`\n"
+ output += f"- :doc:`{profile} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
@@ -261,6 +281,8 @@ class MaintainersProfile(Include):
output += "\n"
+ print(output)
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -277,11 +299,10 @@ class MaintainersProfile(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -289,6 +310,14 @@ class MaintainersProfile(Include):
return []
def setup(app):
+ global app_dir
+
+ #
+ # NOTE: we're using os.fspath() here because of a Sphinx warning:
+ # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
+ #
+ app_dir = os.fspath(app.srcdir)
+
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
return dict(
--
2.53.0
^ permalink raw reply related
* [PATCH v4 10/10] docs: maintainers_include: parse MAINTAINERS just once
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
Change the logic to parse MAINTAINERS file content just once,
while still allowing using it multiple times.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 61 +++++++--------------
1 file changed, 21 insertions(+), 40 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index ae52e8198750..436e7ac42ffc 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,14 +37,13 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-app_dir = "."
+maint_parser = None
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, path):
- global app_dir
-
+ def __init__(self, app_dir, path):
+ self.path = path
self.profile_toc = set()
self.profile_entries = {}
@@ -67,7 +66,6 @@ class MaintainersParser:
subsystem_name = None
base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
- print("BASE DIR", base_dir)
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -105,8 +103,6 @@ class MaintainersParser:
else:
entry = "/" + entry
- print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
-
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -217,14 +213,17 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
+ global maint_parser
- output = MaintainersParser(path).output
+ path = maint_parser.path
+ output = maint_parser.output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -232,19 +231,8 @@ class MaintainersInclude(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -254,16 +242,17 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
+ global maint_parser
- maint = MaintainersParser(path)
+ path = maint_parser.path
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
- for profile, entry in sorted(maint.profile_entries.items()):
+ for profile, entry in sorted(maint_parser.profile_entries.items()):
if entry.startswith("http"):
output += f"- `{profile} <{entry}>`_\n"
else:
@@ -276,13 +265,12 @@ class MaintainersProfile(Include):
output += "\n.. toctree::\n"
output += " :hidden:\n\n"
- for fname in maint.profile_toc:
+ for fname in maint_parser.profile_toc:
output += f" {fname}\n"
output += "\n"
- print(output)
-
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -290,19 +278,8 @@ class MaintainersProfile(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -310,13 +287,17 @@ class MaintainersProfile(Include):
return []
def setup(app):
- global app_dir
+ global maint_parser
#
# NOTE: we're using os.fspath() here because of a Sphinx warning:
# RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
#
app_dir = os.fspath(app.srcdir)
+ srctree = os.path.abspath(os.environ["srctree"])
+ path = os.path.join(srctree, "MAINTAINERS")
+
+ maint_parser = MaintainersParser(app_dir, path)
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
--
2.53.0
^ permalink raw reply related
* [PATCH v4 08/10] docs: maintainers_include: improve its output
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
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>
---
Documentation/sphinx/maintainers_include.py | 76 +++++++++++----------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 7ab921820612..5413c1350bba 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,7 +21,7 @@ import sys
import re
import os.path
-from textwrap import indent
+from glob import glob
from docutils import statemachine
from docutils.parsers.rst import Directive
@@ -36,8 +36,8 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = {}
- self.profile_urls = {}
+ self.profile_toc = set()
+ self.profile_entries = {}
result = list()
result.append(".. _maintainers:")
@@ -73,26 +73,24 @@ class MaintainersParser:
# Drop needless input whitespace.
line = line.rstrip()
+ #
+ # Handle profile entries - either as files or as https refs
+ #
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
- fname = os.path.relpath(match.group(1), base_path)
- if fname.startswith("../"):
- if self.profiles.get(fname) is None:
- self.profiles[fname] = subsystem_name
- else:
- self.profiles[fname] += f", {subsystem_name}"
+ entry = os.path.relpath(match.group(1), base_path)
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[subsystem_name] = e
else:
- self.profiles[fname] = None
-
- match = re.match(r"P:\s*(https?://.*)", line)
- if match:
- url = match.group(1).strip()
- if url not in self.profile_urls:
- if self.profile_urls.get(url) is None:
- self.profile_urls[url] = subsystem_name
- else:
- self.profile_urls[url] += f", {subsystem_name}"
-
+ self.profile_toc.add(entry)
+ self.profile_entries[subsystem_name] = entry
+ else:
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[subsystem_name] = entry
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -234,26 +232,32 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
- output = ".. toctree::\n"
- output += " :maxdepth: 1\n\n"
+ #
+ # Produce a list with all maintainer profiles, sorted by subsystem name
+ #
+ output = ""
- items = sorted(maint.profiles.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for fname, profile in items:
- if profile:
- output += f" {profile} <{fname}>\n"
+ for profile, entry in maint.profile_entries.items():
+ if entry.startswith("http"):
+ if profile:
+ output += f"- `{profile} <{entry}>`_\n"
+ else:
+ output += f"- `<{entry}>_`\n"
else:
- output += f" {fname}\n"
+ if profile:
+ output += f"- :doc:`{profile} <{entry}>`\n"
+ else:
+ output += f"- :doc:`<{entry}>`\n"
- output += "\n**External profiles**\n\n"
+ #
+ # Create a hidden TOC table with all profiles. That allows adding
+ # profiles without needing to add them on any index.rst file.
+ #
+ output += "\n.. toctree::\n"
+ output += " :hidden:\n\n"
- items = sorted(maint.profile_urls.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for url, profile in items:
- if profile:
- output += f"- {profile} <{url}>\n"
- else:
- output += f"- {url}\n"
+ for fname in maint.profile_toc:
+ output += f" {fname}\n"
output += "\n"
--
2.53.0
^ permalink raw reply related
* [PATCH v4 07/10] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Mauro Carvalho Chehab, Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* [PATCH v4 06/10] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.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>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
* [PATCH v4 05/10] docs: maintainers_include: add external profile URLs
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
Some subsystem profiles are maintained elsewhere. Add them to
the output.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index cf428db7599c..f1b8d4b00c2a 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,6 +37,7 @@ class MaintainersParser:
def __init__(self, base_path, path):
self.profiles = {}
+ self.profile_urls = {}
result = list()
result.append(".. _maintainers:")
@@ -81,6 +82,16 @@ class MaintainersParser:
else:
self.profiles[fname] += f", {subsystem_name}"
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ url = match.group(1).strip()
+ if url not in self.profile_urls:
+ if self.profile_urls.get(url) is None:
+ self.profile_urls[url] = subsystem_name
+ else:
+ self.profile_urls[url] += f", {subsystem_name}"
+
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -219,18 +230,31 @@ class MaintainersProfile(Include):
def emit(self, base_path, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- profiles = MaintainersParser(base_path, path).profiles
+ maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ items = sorted(maint.profiles.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
for fname, profile in items:
if profile:
output += f" {profile} <{fname}>\n"
else:
output += f" {fname}\n"
+ output += "\n**External profiles**\n\n"
+
+ items = sorted(maint.profile_urls.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
+ for url, profile in items:
+ if profile:
+ output += f"- {profile} <{url}>\n"
+ else:
+ output += f"- {url}\n"
+
+ output += "\n"
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
--
2.53.0
^ permalink raw reply related
* [PATCH v4 04/10] docs: maintainers_include: use a better title for profiles
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
As we're picking the name of the subsystem from MAINTAINERS,
also use its subsystem name for the titles.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1dac83bf1a65..cf428db7599c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -36,7 +36,7 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = list()
+ self.profiles = {}
result = list()
result.append(".. _maintainers:")
@@ -54,6 +54,7 @@ class MaintainersParser:
prev = None
field_prev = ""
field_content = ""
+ subsystem_name = None
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -75,7 +76,10 @@ class MaintainersParser:
if match:
fname = os.path.relpath(match.group(1), base_path)
if fname not in self.profiles:
- self.profiles.append(fname)
+ if self.profiles.get(fname) is None:
+ self.profiles[fname] = subsystem_name
+ else:
+ self.profiles[fname] += f", {subsystem_name}"
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -112,6 +116,8 @@ class MaintainersParser:
output = field_content + "\n\n"
field_content = ""
+ subsystem_name = line.title()
+
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
@@ -217,7 +223,13 @@ class MaintainersProfile(Include):
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- output += indent("\n".join(profiles), " ")
+
+ items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ for fname, profile in items:
+ if profile:
+ output += f" {profile} <{fname}>\n"
+ else:
+ output += f" {fname}\n"
self.state_machine.insert_input(statemachine.string2lines(output), path)
--
2.53.0
^ permalink raw reply related
* [PATCH v4 03/10] docs: auto-generate maintainer entry profile links
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Albert Ou, Alexandre Ghiti, Palmer Dabbelt, Paul Walmsley,
Shuah Khan, Dan Williams, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
Instead of manually creating a TOC tree for them, use the new
tag to auto-generate its TOC.
Co-developed-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Dan Williams <djbw@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mchehab+huawei@kernel.org>
---
.../maintainer/maintainer-entry-profile.rst | 24 ++++---------------
.../process/maintainer-handbooks.rst | 19 ++++++++-------
2 files changed, 14 insertions(+), 29 deletions(-)
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
-Existing profiles
------------------
+Maintainer Handbooks
+--------------------
-For now, existing maintainer profiles are listed here; we will likely want
-to do something different in the near future.
-
-.. toctree::
- :maxdepth: 1
-
- ../doc-guide/maintainer-profile
- ../nvdimm/maintainer-entry-profile
- ../arch/riscv/patch-acceptance
- ../process/maintainer-soc
- ../process/maintainer-soc-clean-dts
- ../driver-api/media/maintainer-entry-profile
- ../process/maintainer-netdev
- ../driver-api/vfio-pci-device-specific-driver-acceptance
- ../nvme/feature-and-quirk-policy
- ../filesystems/nfs/nfsd-maintainer-entry-profile
- ../filesystems/xfs/xfs-maintainer-entry-profile
- ../mm/damon/maintainer-profile
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 3d72ad25fc6a..531985a0fae8 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
Contents:
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- maintainer-netdev
- maintainer-soc
- maintainer-soc-clean-dts
- maintainer-tip
- maintainer-kvm-x86
+.. maintainers-profile-toc::
--
2.53.0
^ permalink raw reply related
* [PATCH v4 02/10] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Dan Williams, Randy Dunlap
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # Append "MAINTAINERS"
+ path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
+
+ try:
+ self.state.document.settings.record_dependencies.add(path)
+ lines = self.emit(base_path, path)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH v4 01/10] docs: maintainers: add SPDX license to the file
From: Mauro Carvalho Chehab @ 2026-04-27 14:22 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan
In-Reply-To: <cover.1777295258.git.mchehab+huawei@kernel.org>
While this file is really trivial, add a SPDX license line on it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainers.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst
index 6174cfb4138f..5d1b1464c3ae 100644
--- a/Documentation/process/maintainers.rst
+++ b/Documentation/process/maintainers.rst
@@ -1 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
.. maintainers-include::
--
2.53.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox