Re: [PATCH 4/4] docs: admin-guide: add IGNORE_DIRS example for cscope

Re: [PATCH 4/4] docs: admin-guide: add IGNORE_DIRS example for cscope

[Shuah Khan]

On 5/3/26 04:14, Cheng-Han Wu wrote:
> The workload tracing guide shows how to build a cscope database by
> running cscope command directly. The kernel build system also provides
> a cscope target, which supports IGNORE_DIRS for excluding directories
> from the generated database.
> 
> Mention make cscope and show how to exclude Documentation/ as an example.
> 
> Signed-off-by: Cheng-Han Wu <hank20010209@gmail.com>
> ---
>   Documentation/admin-guide/workload-tracing.rst | 9 +++++++++
>   1 file changed, 9 insertions(+)
> 
> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> index c49c2a00a8b8..314e5f03474e 100644
> --- a/Documentation/admin-guide/workload-tracing.rst
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -202,6 +202,15 @@ database. To get out of this mode press ctrl+d. -p option is used to
>   specify the number of file path components to display. -p10 is optimal
>   for browsing kernel sources.
>   
> +Alternatively, the kernel build system can generate the cscope database::
> +
> +  make cscope
> +
> +To exclude directories from the generated database, pass IGNORE_DIRS to
> +the cscope target. For example, to exclude Documentation/, run::
> +
> +  make IGNORE_DIRS="Documentation" cscope
> +
>   What is perf and how do we use it?
>   ==================================
>   

Looks good to me.

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

thanks,
-- Shuah

Re: [PATCH 1/4] docs: admin-guide: fix typos in workload tracing guide

[Shuah Khan]

On 5/3/26 04:14, Cheng-Han Wu wrote:
> Fix several typos in the workload tracing guide:
> 
>    - sys_opennat() -> sys_openat()
>    - annotate the to view -> annotate the output to view
>    - sys_getegid -> sys_getegid()
> 
> Signed-off-by: Cheng-Han Wu <hank20010209@gmail.com>
> ---
>   Documentation/admin-guide/workload-tracing.rst | 8 ++++----
>   1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> index 35963491b9f1..22cb05025ffc 100644
> --- a/Documentation/admin-guide/workload-tracing.rst
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -278,8 +278,8 @@ associated with a process. This command records the profiling data in the
>   perf.data file in the same directory.
>   
>   Using the following commands you can record the events associated with the
> -netdev stressor, view the generated report perf.data and annotate the to
> -view the statistics of each instruction of the program::
> +netdev stressor, view the generated report perf.data and annotate the output
> +to view the statistics of each instruction of the program::
>   
>     perf record stress-ng --netdev 1 -t 60 --metrics command.
>     perf report
> @@ -349,13 +349,13 @@ times each system call is invoked, and the corresponding Linux subsystem.
>   +-------------------+-----------+-----------------+-------------------------+
>   | geteuid           | 1         | Process Mgmt.   | sys_geteuid()           |
>   +-------------------+-----------+-----------------+-------------------------+
> -| getegid           | 1         | Process Mgmt.   | sys_getegid             |
> +| getegid           | 1         | Process Mgmt.   | sys_getegid()           |
>   +-------------------+-----------+-----------------+-------------------------+
>   | close             | 49951     | Filesystem      | sys_close()             |
>   +-------------------+-----------+-----------------+-------------------------+
>   | pipe              | 604       | Filesystem      | sys_pipe()              |
>   +-------------------+-----------+-----------------+-------------------------+
> -| openat            | 48560     | Filesystem      | sys_opennat()           |
> +| openat            | 48560     | Filesystem      | sys_openat()            |
>   +-------------------+-----------+-----------------+-------------------------+
>   | fstat             | 8338      | Filesystem      | sys_fstat()             |
>   +-------------------+-----------+-----------------+-------------------------+

Looks to good to me.

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

thanks,
-- Shuah

Re: [PATCH 2/4] docs: admin-guide: fix stress-ng command examples

[Shuah Khan]

On 5/3/26 04:14, Cheng-Han Wu wrote:
> The workload tracing guide includes stress-ng command examples with a
> stray "command." word at the end. This makes the examples invalid if they
> are copied and run directly.
> 
> Remove the stray word from the stress-ng example. Also use "--" in the
> perf record example to clearly separate perf record options from the
> workload command being recorded.
> 
> Signed-off-by: Cheng-Han Wu <hank20010209@gmail.com>
> ---
>   Documentation/admin-guide/workload-tracing.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> index 22cb05025ffc..43a3c8098654 100644
> --- a/Documentation/admin-guide/workload-tracing.rst
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -271,7 +271,7 @@ exercised:
>   
>   The following command runs the stressor::
>   
> -  stress-ng --netdev 1 -t 60 --metrics command.
> +  stress-ng --netdev 1 -t 60 --metrics
>   
>   We can use the perf record command to record the events and information
>   associated with a process. This command records the profiling data in the
> @@ -281,7 +281,7 @@ Using the following commands you can record the events associated with the
>   netdev stressor, view the generated report perf.data and annotate the output
>   to view the statistics of each instruction of the program::
>   
> -  perf record stress-ng --netdev 1 -t 60 --metrics command.
> +  perf record -- stress-ng --netdev 1 -t 60 --metrics
>     perf report
>     perf annotate
>   

Looks to good to me.

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

thanks,
-- Shuah

Re: [PATCH 3/4] docs: admin-guide: clarify perf bench all behavior

[Shuah Khan]

On 5/3/26 04:14, Cheng-Han Wu wrote:
> The workload tracing guide lists a fixed set of benchmarks for
> "perf bench all". This list is stale and can become outdated when
> perf adds, removes, or renames benchmark collections or individual
> benchmarks.
> 
> Describe "perf bench all" as running all available benchmarks in the perf
> bench framework instead. Also document how to list the collections and
> benchmarks available on a given system.
> 
> Signed-off-by: Cheng-Han Wu <hank20010209@gmail.com>
> ---
>   .../admin-guide/workload-tracing.rst          | 20 +++++++++++++------
>   1 file changed, 14 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst
> index 43a3c8098654..c49c2a00a8b8 100644
> --- a/Documentation/admin-guide/workload-tracing.rst
> +++ b/Documentation/admin-guide/workload-tracing.rst
> @@ -243,13 +243,21 @@ which can help mitigate performance regressions. It also acts as a common
>   benchmarking framework, enabling developers to easily create test cases,
>   integrate transparently, and use performance-rich tooling.
>   
> -"perf bench all" command runs the following benchmarks:
> +"perf bench all" runs all available benchmarks in the perf bench
> +framework. The exact set of benchmarks depends on the perf version and on
> +the features enabled when perf was built.
>   
> - * sched/messaging
> - * sched/pipe
> - * syscall/basic
> - * mem/memcpy
> - * mem/memset
> +To list the benchmark collections available on the current system, run::
> +
> +  perf bench
> +
> +To list benchmarks in a collection, run::
> +
> +  perf bench <collection>
> +
> +For example, to list the benchmarks in the mem collection, run::
> +
> +  perf bench mem
>   
>   What is stress-ng and how do we use it?
>   =======================================

Looks to good to me.

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

thanks,
-- Shuah

Re: [PATCH 0/4] docs: admin-guide: improve workload tracing guide

[Jonathan Corbet]

Cheng-Han Wu <hank20010209@gmail.com> writes:

> This series updates Documentation/admin-guide/workload-tracing.rst
>
>   - Patch 1 fixes several typos.
>   - Patch 2 fixes stress-ng and perf record command examples.
>   - Patch 3 replaces a stale fixed "perf bench all" benchmark list with a
> description of the command behavior and how to query available benchmarks.
>   - Patch 4 mentions the kernel build system's cscope target and shows how 
> to exclude directories with IGNORE_DIRS.
>
> Built test with:
>   make SPHINXDIRS=admin-guide htmldocs
>
> Cheng-Han Wu (4):
>   docs: admin-guide: fix typos in workload tracing guide
>   docs: admin-guide: fix stress-ng command examples
>   docs: admin-guide: clarify perf bench all behavior
>   docs: admin-guide: add IGNORE_DIRS example for cscope
>
>  .../admin-guide/workload-tracing.rst          | 41 +++++++++++++------
>  1 file changed, 29 insertions(+), 12 deletions(-)

Series applied, thanks.

jon