docs: ABI: sysfs-module: list all taint flags

[PATCH] docs: ABI: sysfs-module: list all taint flags

Posted by Randy Dunlap 2 months ago

The list of module taint flags has not been updated lately as the
taint flags list grows. Instead of trying to keep multiple lists
updated, just refer to the list of kernel taint flags since they are
the same.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Luis Chamberlain <mcgrof@kernel.org>
Cc: Petr Pavlu <petr.pavlu@suse.com>
Cc: Daniel Gomez <da.gomez@kernel.org>
Cc: Sami Tolvanen <samitolvanen@google.com>
Cc: linux-modules@vger.kernel.org
---
 Documentation/ABI/testing/sysfs-module        |   10 ++--------
 Documentation/admin-guide/tainted-kernels.rst |    2 ++
 2 files changed, 4 insertions(+), 8 deletions(-)

--- linux-next-20251014.orig/Documentation/ABI/testing/sysfs-module
+++ linux-next-20251014/Documentation/ABI/testing/sysfs-module
@@ -52,14 +52,8 @@ What:		/sys/module/*/taint
 Date:		Jan 2012
 KernelVersion:	3.3
 Contact:	Kay Sievers <kay.sievers@vrfy.org>
-Description:	Module taint flags:
-			==  =====================
-			P   proprietary module
-			O   out-of-tree module
-			F   force-loaded module
-			C   staging driver module
-			E   unsigned module
-			==  =====================
+Description:	Module taint flags: same as the kernel taint flags.
+		See: :ref:`taint_flags` in Documentation/admin-guide/tainted-kernels.rst
 
 What:		/sys/module/grant_table/parameters/free_per_iteration
 Date:		July 2023
--- linux-next-20251014.orig/Documentation/admin-guide/tainted-kernels.rst
+++ linux-next-20251014/Documentation/admin-guide/tainted-kernels.rst
@@ -76,6 +76,8 @@ which bits are set::
 
 	$ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done
 
+.. _taint_flags:
+
 Table for decoding tainted state
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Re: [PATCH] docs: ABI: sysfs-module: list all taint flags

Posted by Petr Pavlu 2 months ago

On 10/16/25 12:13 AM, Randy Dunlap wrote:
> The list of module taint flags has not been updated lately as the
> taint flags list grows. Instead of trying to keep multiple lists
> updated, just refer to the list of kernel taint flags since they are
> the same.
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Luis Chamberlain <mcgrof@kernel.org>
> Cc: Petr Pavlu <petr.pavlu@suse.com>
> Cc: Daniel Gomez <da.gomez@kernel.org>
> Cc: Sami Tolvanen <samitolvanen@google.com>
> Cc: linux-modules@vger.kernel.org
> ---
>  Documentation/ABI/testing/sysfs-module        |   10 ++--------
>  Documentation/admin-guide/tainted-kernels.rst |    2 ++
>  2 files changed, 4 insertions(+), 8 deletions(-)
> 
> --- linux-next-20251014.orig/Documentation/ABI/testing/sysfs-module
> +++ linux-next-20251014/Documentation/ABI/testing/sysfs-module
> @@ -52,14 +52,8 @@ What:		/sys/module/*/taint
>  Date:		Jan 2012
>  KernelVersion:	3.3
>  Contact:	Kay Sievers <kay.sievers@vrfy.org>
> -Description:	Module taint flags:
> -			==  =====================
> -			P   proprietary module
> -			O   out-of-tree module
> -			F   force-loaded module
> -			C   staging driver module
> -			E   unsigned module
> -			==  =====================
> +Description:	Module taint flags: same as the kernel taint flags.
> +		See: :ref:`taint_flags` in Documentation/admin-guide/tainted-kernels.rst

The module taint flags that can appear in /sys/module/*/taint are
a subset of the kernel taint flags. By looking at the calls to
add_taint_module(), they are as follows:

Present:
TAINT_PROPRIETARY_MODULE
TAINT_OOT_MODULE
TAINT_FORCED_MODULE
TAINT_CRAP
TAINT_UNSIGNED_MODULE

Missing:
TAINT_LIVEPATCH
TAINT_TEST

+ potentially TEST_AUX.

Since this text specifically documents what can appear in
/sys/module/*/taint, I think we should still maintain a list of these
flags for accuracy.

Additionally, Documentation/admin-guide/tainted-kernels.rst provides
taint descriptions for the kernel as a whole, which can be misleading
for individual modules. For instance, for TAINT_LIVEPATCH, the document
says "kernel has been live patched", but in the context of
/sys/module/*/taint, it means "this is a livepatch module".

-- 
Thanks,
Petr

Re: [PATCH] docs: ABI: sysfs-module: list all taint flags

Posted by Randy Dunlap 2 months ago


On 10/17/25 4:38 AM, Petr Pavlu wrote:
> On 10/16/25 12:13 AM, Randy Dunlap wrote:
>> The list of module taint flags has not been updated lately as the
>> taint flags list grows. Instead of trying to keep multiple lists
>> updated, just refer to the list of kernel taint flags since they are
>> the same.
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: linux-doc@vger.kernel.org
>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>> Cc: Luis Chamberlain <mcgrof@kernel.org>
>> Cc: Petr Pavlu <petr.pavlu@suse.com>
>> Cc: Daniel Gomez <da.gomez@kernel.org>
>> Cc: Sami Tolvanen <samitolvanen@google.com>
>> Cc: linux-modules@vger.kernel.org
>> ---
>>  Documentation/ABI/testing/sysfs-module        |   10 ++--------
>>  Documentation/admin-guide/tainted-kernels.rst |    2 ++
>>  2 files changed, 4 insertions(+), 8 deletions(-)
>>
>> --- linux-next-20251014.orig/Documentation/ABI/testing/sysfs-module
>> +++ linux-next-20251014/Documentation/ABI/testing/sysfs-module
>> @@ -52,14 +52,8 @@ What:		/sys/module/*/taint
>>  Date:		Jan 2012
>>  KernelVersion:	3.3
>>  Contact:	Kay Sievers <kay.sievers@vrfy.org>
>> -Description:	Module taint flags:
>> -			==  =====================
>> -			P   proprietary module
>> -			O   out-of-tree module
>> -			F   force-loaded module
>> -			C   staging driver module
>> -			E   unsigned module
>> -			==  =====================
>> +Description:	Module taint flags: same as the kernel taint flags.
>> +		See: :ref:`taint_flags` in Documentation/admin-guide/tainted-kernels.rst
> 
> The module taint flags that can appear in /sys/module/*/taint are
> a subset of the kernel taint flags. By looking at the calls to
> add_taint_module(), they are as follows:
> 
> Present:
> TAINT_PROPRIETARY_MODULE
> TAINT_OOT_MODULE
> TAINT_FORCED_MODULE
> TAINT_CRAP
> TAINT_UNSIGNED_MODULE
> 
> Missing:
> TAINT_LIVEPATCH
> TAINT_TEST
> 
> + potentially TEST_AUX.
> 
> Since this text specifically documents what can appear in
> /sys/module/*/taint, I think we should still maintain a list of these
> flags for accuracy.
> 
> Additionally, Documentation/admin-guide/tainted-kernels.rst provides
> taint descriptions for the kernel as a whole, which can be misleading
> for individual modules. For instance, for TAINT_LIVEPATCH, the document
> says "kernel has been live patched", but in the context of
> /sys/module/*/taint, it means "this is a livepatch module".


Hi Petr,

Thank you for your comments and corrections.

I'll drop this patch.

-- 
~Randy