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

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

[Cheng-Han Wu]

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(-)

-- 
2.52.0

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

[Cheng-Han Wu]

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()             |
 +-------------------+-----------+-----------------+-------------------------+
-- 
2.52.0

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

[Cheng-Han Wu]

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
 
-- 
2.52.0

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

[Cheng-Han Wu]

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?
 =======================================
-- 
2.52.0

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

[Cheng-Han Wu]

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?
 ==================================
 
-- 
2.52.0

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