profiling: doc: clean up grammar/spelling

Clean up documentation pages for the new perf tool
as they contained several typos, grammar errors, and
duplicated content between main doc page and sample
page

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>

doc/services/profiling/perf.rst

@@ -1,91 +1,38 @@
 .. _profiling-perf:
 
-
 Perf
 ####
 
+Perf is a profiler tool based on stack tracing. It can be used for lightweight profiling
+with minimal code overhead.
 
-Perf is a profiler tool, based on stack tracing. It can be used to light weight profiling
+Work Principle
-almost without any code overhead.
+**************
 
-Work principe
+The ``perf record`` shell command starts a timer with the perf tracer function.
-*************
+Timers are driven by interrupts, so the perf tracer function is called during an interruption.
+The Zephyr core saves the return address and frame pointer in the interrupt stack or ``callee_saved``
+structure before calling the interrupt handler. Thus, the perf trace function makes stack traces by
+using the return address and frame pointer.
 
-``perf record`` shell-command starts timer with perf tracer function.
+The :zephyr_file:`scripts/profiling/stackcollapse.py` script can be used to convert return addresses
-Timers are driven by inerrupts, so perf tracer function is calling during interruption.
+in the stack trace to function names using symbols from the ELF file, and to prints them in the
-Zephyr core save return address and frame pointer in interrupt stack or ``callee_saved``
+format expected by `FlameGraph`_.
-struture before caling interrupt hundler. So perf trace function makes stack traces by
-using return address and frame pointer.
-
-Then stackcollapse.py script convert return addresses in stack trace to function names
-by elf file and print them in required for FlameGraph format.
 
 Configuration
 *************
 
-Configure this module using the following options.
+You can configure this module using the following options:
 
-* :kconfig:option:`CONFIG_PROFILING_PERF`: enable the module. This opion add
+* :kconfig:option:`CONFIG_PROFILING_PERF`: Enables the module. This option adds
-  perf command in shell.
+  the ``perf`` command to the shell.
 
-* :kconfig:option:`CONFIG_PROFILING_PERF_BUFFER_SIZE`: sets size of perf buffer,
+* :kconfig:option:`CONFIG_PROFILING_PERF_BUFFER_SIZE`: Sets the size of the perf buffer
   where samples are saved before printing.
 
 Usage
 *****
 
-More specific example can be found in :zephyr:code-sample:`profiling-perf`.
+Refer to the :zephyr:code-sample:`profiling-perf` sample for an example of how to use the perf tool.
 
-#. Build with perf enabled and run.
+ .. _FlameGraph: https://github.com/brendangregg/FlameGraph/
-
-#. Begin perf sampling by shell-command
-
-   .. code-block:: text
-
-      perf record <period> <frequency>
-
-   This command will start timer with perf sampler for *period* in seconds and
-   with *frequency* in hertz.
-
-   Wait for the completion message ``perf done!`` or ``perf buf override!``
-   (if perf buffer size is smaller than required).
-
-#. Print made by perf samles in terminal by shell-command
-
-   .. code-block:: text
-
-      perf printbuf
-
-   Output exaple:
-
-   .. code-block:: text
-
-      Perf buf length 1985
-      0000000000000004
-      0000000080004e58
-      00000000800071ca
-      0000000080000964
-      aaaaaaaaaaaaaaaa
-      0000000000000002
-      ....
-      00000000800163e0
-
-   Copy gotten output in some file, for example *perf_buf*.
-
-#. Translate perf samples by stackcollapse script to format, required by FlameGraph
-
-   .. code-block:: bash
-
-      python zephyr/scripts/perf/stackcollapse.py perf_buf <build_dir>/zephyr/zephyr.elf > perf_buf.folded
-
-   And turn into .svg FlameGraph (for example *graph.svg*)
-
-   .. code-block:: bash
-
-      ./FlameGraph/flamegraph.pl perf_buf.folded > graph.svg
-
-   All this step can be done by one command
-
-   .. code-block:: bash
-
-      python zephyr/scripts/perf/stackcollapse.py perf_buf <build_dir>/zephyr/zephyr.elf | ./FlameGraph/flamegraph.pl > graph.svg

samples/subsys/profiling/perf/README.rst

@@ -3,40 +3,43 @@
 
     Send perf samples to the host with console support
 
-This application can be used to demonstrate :ref:`profiling-perf` work.
+This application can be used to understand how to use the :ref:`profiling-perf`
+tool.
 
 Requirements
 ************
 
-Perf tool so far implemente only for riscv and x86_64 architectures.
+The Perf tool is currently implemented only for RISC-V and x86_64 architectures.
 
 Usage example
 *************
 
-Build an image with:
+* Build and run the sample with:
 
   .. zephyr-app-commands::
      :zephyr-app: samples/subsys/profiling/perf
      :board: qemu_riscv64
-    :goals: build
+     :goals: run
      :compact:
 
-After the sample starts, enter shell command:
+* After the sample has started, enter the shell command:
 
   .. code-block:: console
 
-  uart:~$ perf record <period> <frequency>
+     uart:~$ perf record <duration> <frequency>
 
-Wait for the completion message ``perf done!`` or ``perf buf override!``
+  This command will start a timer for *duration* milliseconds at *frequency* Hz.
-(if perf buffer size is smaller than required).
 
-Print made by perf samles in terminal by shell-command:
+* Wait for the completion message ``perf done!``, or ``perf buf override!`` if
+  the perf buffer size is smaller than required.
+
+* Print the samples captured by perf in the terminal with the shell command:
 
   .. code-block:: console
 
      uart:~$ perf printbuf
 
-Output exaple:
+  The output should be similar to:
 
   .. code-block:: console
 
@@ -50,10 +53,10 @@ Output exaple:
      000000000010052f
      0000000000000000
 
-Copy gotten output in some file, for example *perf_buf*.
+* Copy the output into a file, for example :file:`perf_buf`.
 
-Make graph.svg with :zephyr_file:`scripts/perf/stackcollapse.py` and
+* Generate :file:`graph.svg` with
-`FlameGraph`_:
+  :zephyr_file:`scripts/profiling/stackcollapse.py` and `FlameGraph`_:
 
   .. _FlameGraph: https://github.com/brendangregg/FlameGraph/
 

subsys/profiling/perf/Kconfig

@@ -18,6 +18,6 @@ config PROFILING_PERF_BUFFER_SIZE
 	int "Perf buffer size"
 	default 2048
 	help
-	  Size of buffer, that used by perf to save samples from stack tracing.
+	  Size of buffer used by perf to save stack trace samples.
 
 endif