Re: [PATCH] docs: sysctl: Add documentation for crypto and debug sysctls

[Jonathan Corbet]

Shubham Chakraborty <chakrabortyshubham66@xxxxxxxxx> writes:

> The /proc/sys/crypto and /proc/sys/debug directories lacked documentation in the admin-guide. Add RST files covering fips_enabled, fips_name, fips_version, exception-trace, and kprobes-optimization sysctls.

Thanks for working to improve our documentation!  There are a few things
to fix there, though.

- Please wrap your changelog below the 80-column limit.

- You need to included a Signed-off-by line

> ---
>  Documentation/admin-guide/sysctl/crypto.rst | 59 +++++++++++++++++++
>  Documentation/admin-guide/sysctl/debug.rst  | 63 +++++++++++++++++++++
>  Documentation/admin-guide/sysctl/index.rst  |  8 ++-
>  3 files changed, 128 insertions(+), 2 deletions(-)
>  create mode 100644 Documentation/admin-guide/sysctl/crypto.rst
>  create mode 100644 Documentation/admin-guide/sysctl/debug.rst
>
> diff --git a/Documentation/admin-guide/sysctl/crypto.rst b/Documentation/admin-guide/sysctl/crypto.rst
> new file mode 100644
> index 000000000..f44a50f68
> --- /dev/null
> +++ b/Documentation/admin-guide/sysctl/crypto.rst
> @@ -0,0 +1,59 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===================================
> +Documentation for /proc/sys/crypto/
> +===================================

I'd take out "Documentation for" - readers know that this is
documentation. 

> +.. See scripts/check-sysctl-docs to keep this up to date:
> +.. scripts/check-sysctl-docs -vtable="crypto" \
> +..         Documentation/admin-guide/sysctl/crypto.rst \
> +..         $(git grep -l register_sysctl_)
> +
> +Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@xxxxxxxxx>
> +
> +For general info and legal blurb, please look in
> +Documentation/admin-guide/sysctl/index.rst.
> +
> +------------------------------------------------------------------------------

Why the "----------------..." line?

Honestly, this stuff might be better placed at the bottom of the file;
it's not what readers of the file will be most interested in.

> +This file contains documentation for the sysctl files in
> +``/proc/sys/crypto/``.

Here, too, the "this file contains" signposting doesn't really need to
be here.

> +The files in this directory can be used to monitor and configure the
> +Linux kernel's cryptographic subsystem.
> +
> +Currently, these files might (depending on your configuration)
> +show up in ``/proc/sys/crypto/``:
> +
> +.. contents:: :local:
> +
> +fips_enabled
> +============
> +
> +This file contains a read-only flag that indicates whether FIPS mode is
> +enabled.
> +
> +- ``0``: FIPS mode is disabled (default).
> +- ``1``: FIPS mode is enabled.
> +
> +This value is set at boot time via the ``fips=1`` kernel command line
> +parameter. When enabled, the cryptographic API will restrict the use
> +of certain algorithms and perform self-tests to ensure compliance with
> +FIPS (Federal Information Processing Standards) requirements, such as
> +FIPS 140-2 and the newer FIPS 140-3, depending on the kernel
> +configuration and the module in use.
> +
> +fips_name
> +=========
> +
> +This read-only file contains the name of the FIPS module currently in use.
> +The value is typically configured via the ``CONFIG_CRYPTO_FIPS_NAME``
> +kernel configuration option.
> +
> +fips_version
> +============
> +
> +This read-only file contains the version string of the FIPS module.
> +If ``CONFIG_CRYPTO_FIPS_CUSTOM_VERSION`` is set, it uses the value from
> +``CONFIG_CRYPTO_FIPS_VERSION``. Otherwise, it defaults to the kernel
> +release version (``UTS_RELEASE``).
> diff --git a/Documentation/admin-guide/sysctl/debug.rst b/Documentation/admin-guide/sysctl/debug.rst
> new file mode 100644
> index 000000000..1a35042b6
> --- /dev/null
> +++ b/Documentation/admin-guide/sysctl/debug.rst
> @@ -0,0 +1,63 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==================================
> +Documentation for /proc/sys/debug/
> +==================================

Same comments as above apply here.

> +.. See scripts/check-sysctl-docs to keep this up to date:
> +.. scripts/check-sysctl-docs -vtable="debug" \
> +..         Documentation/admin-guide/sysctl/debug.rst \
> +..         $(git grep -l register_sysctl_)
> +
> +Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@xxxxxxxxx>
> +
> +For general info and legal blurb, please look in
> +Documentation/admin-guide/sysctl/index.rst.
> +
> +------------------------------------------------------------------------------
> +
> +This file contains documentation for the sysctl files in
> +``/proc/sys/debug/``.
> +
> +The files in this directory are used to control various debugging
> +features within the Linux kernel.
> +
> +Currently, these files might (depending on your configuration)
> +show up in ``/proc/sys/debug/``:
> +
> +.. contents:: :local:
> +
> +exception-trace
> +===============
> +
> +This flag controls whether the kernel prints information about unhandled
> +signals (like segmentation faults) to the kernel log (``dmesg``).
> +
> +- ``0``: Unhandled signals are not traced.
> +- ``1``: Information about unhandled signals is printed.
> +
> +The default value is ``1`` on most architectures (like x86, MIPS, RISC-V),
> +but it is ``0`` on **arm64**.
> +
> +The actual information printed and the context provided varies
> +significantly depending on the CPU architecture. For example:
> +
> +- On **x86**, it typically prints the instruction pointer (IP), error
> +  code, and address that caused a page fault.
> +- On **PowerPC**, it may print the next instruction pointer (NIP),
> +  link register (LR), and other relevant registers.
> +
> +When enabled, this feature is often rate-limited to prevent the kernel
> +log from being flooded during a crash loop.
> +
> +kprobes-optimization
> +====================
> +
> +This flag enables or disables the optimization of Kprobes on certain
> +architectures (like x86).
> +
> +- ``0``: Kprobes optimization is turned off.
> +- ``1``: Kprobes optimization is turned on (default).
> +
> +For more details on Kprobes and its optimization, please refer to
> +Documentation/trace/kprobes.rst.
> diff --git a/Documentation/admin-guide/sysctl/index.rst b/Documentation/admin-guide/sysctl/index.rst
> index 4dd2c9b5d..8b51edcf8 100644
> --- a/Documentation/admin-guide/sysctl/index.rst
> +++ b/Documentation/admin-guide/sysctl/index.rst
> @@ -1,3 +1,5 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +

We need to be careful about adding SPDX lines to files we didn't write
ourselves.  It's probably OK here, I doubt there's much copyrightable in
this file.  But, in any case, this is an independent change that needs
to be done separately.

>  ===========================
>  Documentation for /proc/sys
>  ===========================
> @@ -67,8 +69,8 @@ This documentation is about:
>  =============== ===============================================================
>  abi/		execution domains & personalities
>  <$ARCH>		tuning controls for various CPU architecture (e.g. csky, s390)
> -crypto/		<undocumented>
> -debug/		<undocumented>
> +crypto/		cryptographic subsystem
> +debug/		debugging features
>  dev/		device specific information (e.g. dev/cdrom/info)
>  fs/		specific filesystems
>  		filehandle, inode, dentry and quota tuning
> @@ -96,6 +98,8 @@ it :-)
>     :maxdepth: 1
>  
>     abi
> +   crypto
> +   debug
>     fs
>     kernel
>     net
> -- 
> 2.53.0

Thanks,

jon