From:   Jonathan Corbet <corbet@lwn.net>
To:     Shuah Khan <skhan@linuxfoundation.org>
Cc:     Shuah Khan <skhan@linuxfoundation.org>, sshefali021@gmail.com,
        kstewart@linuxfoundation.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3] docs: add workload-tracing document to admin-guide
In-Reply-To: <20230131221105.39216-1-skhan@linuxfoundation.org>
References: <20230131221105.39216-1-skhan@linuxfoundation.org>
Date:   Thu, 02 Feb 2023 10:43:01 -0700
Message-ID: <87edr8vu8q.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Shuah Khan <skhan@linuxfoundation.org> writes:

> Add a new section to the admin-guide with information of interest to
> application developers and system integrators doing analysis of the
> Linux kernel for safety critical applications.
>
> This section will contain documents supporting analysis of kernel
> interactions with applications, and key kernel subsystems expectations.
>
> Add a new workload-tracing document to this new section.
>
> Signed-off-by: Shefali Sharma <sshefali021@gmail.com>
> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
> ---
> Changes since v2: Addressed review comments on v2
>
>  Documentation/admin-guide/index.rst           |  11 +
>  .../admin-guide/workload-tracing.rst          | 605 ++++++++++++++++++
>  2 files changed, 616 insertions(+)
>  create mode 100644 Documentation/admin-guide/workload-tracing.rst

I've applied this with a couple of sphinx tweaks, including:

> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 5bfafcbb9562..f475554382e2 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -56,6 +56,17 @@ ABI will be found here.
>  
>     sysfs-rules
>  
> +This is the beginning of a section with information of interest to
> +application developers and system integrators doing analysis of the
> +Linux kernel for safety critical applications. Documents supporting
> +analysis of kernel interactions with applications, and key kernel
> +subsystems expectations will be found here.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   workload-tracing
> +
>  The rest of this manual consists of various unordered guides on how to
>  configure specific aspects of kernel behavior to your liking.
>  
> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> new file mode 100644
> index 000000000000..5fad64b4ebd6
> --- /dev/null
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -0,0 +1,605 @@
> +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
> +
> +Discovering Linux kernel subsystems used by a workload
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++

This doesn't follow our normal conventions, so I made it:

> ======================================================
> Discovering Linux kernel subsystems used by a workload
> ======================================================

Instead.

Thanks,

jon