2
0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-09-04 20:19:47 +08:00
linux/tools/perf/Documentation
Linus Torvalds 7685b334d1 perf-tools changes for v6.14
There are a lot of changes in the perf tools in this cycle.
 
 build
 -----
 * Use generic syscall table to generate syscall numbers on supported archs.
 * This also enables to get rid of libaudit which was used for syscall numbers.
 * Remove python2 support as it's deprecated for years.
 * Fix issues on static build with libzstd.
 
 perf record
 -----------
 * Intel-PT supports "aux-action" config term to pause or resume tracing in
   the aux-buffer.  Users can start the intel_pt event as "started-paused" and
   configure other events to control the Intel-PT tracing.
 
     # perf record --kcore -e intel_pt/aux-action=start-paused/   \
         -e syscalls:sys_enter_newuname/aux-action=resume/        \
         -e syscalls:sys_exit_newuname/aux-action=pause/ -- uname
 
   This requires the kernel support (which was added in v6.13).
 
 perf lock
 ---------
 * 'perf lock contention' command has an ability to symbolize locks in
   dynamically allocated objects using slab cache name when it runs with BPF.
   Those dynamic locks would have "&" prefix in the name to distinguish them
   from ordinary (static) locks.
 
     # perf lock con -abl -E 5 sleep 1
        contended   total wait     max wait     avg wait            address   symbol
 
                2      1.95 us      1.77 us       975 ns   ffff9d5e852d3498   &task_struct (mutex)
                1      1.18 us      1.18 us      1.18 us   ffff9d5e852d3538   &task_struct (mutex)
                4      1.12 us       354 ns       279 ns   ffff9d5e841ca800   &kmalloc-cg-512 (mutex)
                2       859 ns       617 ns       429 ns   ffffffffa41c3620   delayed_uprobe_lock (mutex)
                3       691 ns       388 ns       230 ns   ffffffffa41c0940   pack_mutex (mutex)
 
   This also requires the kernel/BPF support (which was added in v6.13).
 
 perf ftrace
 -----------
 * 'perf ftrace latency' command gets a couple of options to support linear
   buckets instead of exponential.  Also it's possible to specify max and
   min latency for the linear buckets.
 
     # perf ftrace latency -abn -T switch_mm_irqs_off --bucket-range=100   \
         --min-latency=200 --max-latency=800 -- sleep 1
     #   DURATION     |      COUNT | GRAPH                                  |
          0 -  200 ns |        186 | ###                                    |
        200 -  300 ns |        256 | #####                                  |
        300 -  400 ns |        364 | #######                                |
        400 -  500 ns |        223 | ####                                   |
        500 -  600 ns |        111 | ##                                     |
        600 -  700 ns |         41 |                                        |
        700 -  800 ns |        141 | ##                                     |
        800 -  ... ns |        169 | ###                                    |
 
     # statistics  (in nsec)
       total time:              2162212
         avg time:                  967
         max time:                16817
         min time:                  132
            count:                 2236
 
 * As you can see in the above example, it nows shows the statistics at the
   end so that users can see the avg/max/min latencies easily.
 
 * 'perf ftrace profile' command has --graph-opts option like 'perf ftrace
   trace' so that it can control the tracing behaviors in the same way.
   For example, it can limit the function call depth or threshold.
 
 perf script
 -----------
 * Improve physical memory resolution in 'mem-phys-addr' script by parsing
   /proc/iomem file.
 
     # perf script mem-phys-addr -- find /
     ...
     Event: mem_inst_retired.all_loads:P
     Memory type                                    count  percentage
     ----------------------------------------  ----------  ----------
     100000000-85f7fffff : System RAM                8929        69.7
       547600000-54785d23f : Kernel data             1240         9.7
       546a00000-5474bdfff : Kernel rodata            490         3.8
       5480ce000-5485fffff : Kernel bss               121         0.9
     0-fff : Reserved                                3860        30.1
     100000-89c01fff : System RAM                      18         0.1
     8a22c000-8df6efff : System RAM                     5         0.0
 
 Others
 ------
 * 'perf test' gets --runs-per-test option to run the test cases repeatedly.
   This would be helpful to see if it's flaky.
 
 * Add 'parse_events' method to Python perf extension module, so that users
   can use the same event parsing logic in the python code.  One more step
   towards implementing perf tools in Python. :)
 
 * Support opening tracepoint events without libtraceevent.  This will be
   helpful if it won't use the tracing data like in 'perf stat'.
 
 * Update ARM Neoverse N2/V2 JSON events and metrics
 
 Signed-off-by: Namhyung Kim <namhyung@kernel.org>
 -----BEGIN PGP SIGNATURE-----
 
 iHUEABYIAB0WIQSo2x5BnqMqsoHtzsmMstVUGiXMgwUCZ5AgiQAKCRCMstVUGiXM
 g0WhAP43Dpfatrm1jicTyAogk5D/JrIMOgjGtrJJi5RXG/r0gwD8DSWFzLppS9xy
 KGtjLHrN6v6BqR4DCubdlZmRfh9Qjgg=
 =M0Kz
 -----END PGP SIGNATURE-----

Merge tag 'perf-tools-for-v6.14-2025-01-21' of git://git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools

Pull perf-tools updates from Namhyung Kim:
 "There are a lot of changes in the perf tools in this cycle.

  build:

   - Use generic syscall table to generate syscall numbers on supported
     archs

   - This also enables to get rid of libaudit which was used for syscall
     numbers

   - Remove python2 support as it's deprecated for years

   - Fix issues on static build with libzstd

  perf record:

   - Intel-PT supports "aux-action" config term to pause or resume
     tracing in the aux-buffer. Users can start the intel_pt event as
     "started-paused" and configure other events to control the Intel-PT
     tracing:

         # perf record --kcore -e intel_pt/aux-action=start-paused/   \
             -e syscalls:sys_enter_newuname/aux-action=resume/        \
             -e syscalls:sys_exit_newuname/aux-action=pause/ -- uname

     This requires kernel support (which was added in v6.13)

  perf lock:

   - 'perf lock contention' command has an ability to symbolize locks in
     dynamically allocated objects using slab cache name when it runs
     with BPF. Those dynamic locks would have "&" prefix in the name to
     distinguish them from ordinary (static) locks

        # perf lock con -abl -E 5 sleep 1
           contended   total wait     max wait     avg wait            address   symbol

                   2      1.95 us      1.77 us       975 ns   ffff9d5e852d3498   &task_struct (mutex)
                   1      1.18 us      1.18 us      1.18 us   ffff9d5e852d3538   &task_struct (mutex)
                   4      1.12 us       354 ns       279 ns   ffff9d5e841ca800   &kmalloc-cg-512 (mutex)
                   2       859 ns       617 ns       429 ns   ffffffffa41c3620   delayed_uprobe_lock (mutex)
                   3       691 ns       388 ns       230 ns   ffffffffa41c0940   pack_mutex (mutex)

     This also requires kernel/BPF support (which was added in v6.13)

  perf ftrace:

   - 'perf ftrace latency' command gets a couple of options to support
     linear buckets instead of exponential. Also it's possible to
     specify max and min latency for the linear buckets:

        # perf ftrace latency -abn -T switch_mm_irqs_off --bucket-range=100   \
            --min-latency=200 --max-latency=800 -- sleep 1
        #   DURATION     |      COUNT | GRAPH                                  |
             0 -  200 ns |        186 | ###                                    |
           200 -  300 ns |        256 | #####                                  |
           300 -  400 ns |        364 | #######                                |
           400 -  500 ns |        223 | ####                                   |
           500 -  600 ns |        111 | ##                                     |
           600 -  700 ns |         41 |                                        |
           700 -  800 ns |        141 | ##                                     |
           800 -  ... ns |        169 | ###                                    |

        # statistics  (in nsec)
          total time:              2162212
            avg time:                  967
            max time:                16817
            min time:                  132
               count:                 2236

   - As you can see in the above example, it nows shows the statistics
     at the end so that users can see the avg/max/min latencies easily

   - 'perf ftrace profile' command has --graph-opts option like 'perf
     ftrace trace' so that it can control the tracing behaviors in the
     same way. For example, it can limit the function call depth or
     threshold

  perf script:

   - Improve physical memory resolution in 'mem-phys-addr' script by
     parsing /proc/iomem file

        # perf script mem-phys-addr -- find /
        ...
        Event: mem_inst_retired.all_loads:P
        Memory type                                    count  percentage
        ----------------------------------------  ----------  ----------
        100000000-85f7fffff : System RAM                8929        69.7
          547600000-54785d23f : Kernel data             1240         9.7
          546a00000-5474bdfff : Kernel rodata            490         3.8
          5480ce000-5485fffff : Kernel bss               121         0.9
        0-fff : Reserved                                3860        30.1
        100000-89c01fff : System RAM                      18         0.1
        8a22c000-8df6efff : System RAM                     5         0.0

  Others:

   - 'perf test' gets --runs-per-test option to run the test cases
     repeatedly. This would be helpful to see if it's flaky

   - Add 'parse_events' method to Python perf extension module, so that
     users can use the same event parsing logic in the python code. One
     more step towards implementing perf tools in Python. :)

   - Support opening tracepoint events without libtraceevent. This will
     be helpful if it won't use the tracing data like in 'perf stat'

   - Update ARM Neoverse N2/V2 JSON events and metrics"

* tag 'perf-tools-for-v6.14-2025-01-21' of git://git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools: (176 commits)
  perf test: Update event_groups test to use instructions
  perf bench: Fix undefined behavior in cmpworker()
  perf annotate: Prefer passing evsel to evsel->core.idx
  perf lock: Rename fields in lock_type_table
  perf lock: Add percpu-rwsem for type filter
  perf lock: Fix parse_lock_type which only retrieve one lock flag
  perf lock: Fix return code for functions in __cmd_contention
  perf hist: Fix width calculation in hpp__fmt()
  perf hist: Fix bogus profiles when filters are enabled
  perf hist: Deduplicate cmp/sort/collapse code
  perf test: Improve verbose documentation
  perf test: Add a runs-per-test flag
  perf test: Fix parallel/sequential option documentation
  perf test: Send list output to stdout rather than stderr
  perf test: Rename functions and variables for better clarity
  perf tools: Expose quiet/verbose variables in Makefile.perf
  perf config: Add a function to set one variable in .perfconfig
  perf test perftool_testsuite: Return correct value for skipping
  perf test perftool_testsuite: Add missing description
  perf test record+probe_libc_inet_pton: Make test resilient
  ...
2025-01-24 05:45:40 -08:00
..
android.txt
arm-coresight.txt perf docs: Fix man page build wrt perf-arm-coresight.txt 2022-10-25 17:40:48 -03:00
asciidoc.conf perf docs: Allow man page date to be specified 2019-09-27 09:26:14 -03:00
asciidoctor-extensions.rb perf Documentation: Support for asciidoctor 2018-04-26 13:47:10 -03:00
build-docdep.perl perf doc: Fix doc.dep 2021-08-02 09:56:17 -03:00
build-xed.txt perf script: Add --insn-trace for instruction decoding 2018-10-24 15:29:50 -03:00
Build.txt perf docs: Document cross compilation 2024-07-26 11:15:55 -07:00
callchain-overhead-calculation.txt
cat-texi.perl perf doc: Fix perfman.info build 2021-08-02 09:56:17 -03:00
db-export.txt perf db-export: Add brief documentation 2019-06-05 09:47:57 -03:00
examples.txt perf tools: Replace lkml.org links with lore 2021-02-11 12:54:27 -03:00
guest-files.txt perf tools: Tidy guest option documentation 2022-08-11 18:50:17 -03:00
guestmount.txt perf tools: Tidy guest option documentation 2022-08-11 18:50:17 -03:00
intel-bts.txt
intel-hybrid.txt perf record: Fix manpage formatting of description of support to hybrid systems 2022-08-27 11:55:17 -03:00
intel-pt.txt perf intel-pt: Update intel-pt.txt file with new location of the documentation 2020-03-11 11:00:33 -03:00
itrace.txt perf arm-spe: Update --itrace help text 2024-10-29 16:10:17 -07:00
jit-interface.txt
jitdump-specification.txt perf doc: Fix typos all over the place 2021-09-27 09:32:28 -03:00
Makefile perf doc: Add support for KBUILD_BUILD_TIMESTAMP 2023-05-15 17:49:01 -03:00
manpage-1.72.xsl
manpage-base.xsl
manpage-bold-literal.xsl
manpage-normal.xsl
manpage-suppress-sp.xsl
perf-amd-ibs.txt perf doc: Add AMD IBS usage document 2024-06-20 16:51:55 -07:00
perf-annotate.txt perf annotate: Add --skip-empty option 2024-08-05 16:14:01 -03:00
perf-archive.txt
perf-arm-spe.txt perf docs: arm_spe: Document new discard mode 2025-01-10 14:50:55 +00:00
perf-bench.txt perf bench sched pipe: Add -G/--cgroups option 2023-10-25 10:02:10 -07:00
perf-buildid-cache.txt perf record: Disable debuginfod by default 2022-01-15 17:41:25 -03:00
perf-buildid-list.txt perf buildid-list: Add a "-m" option to show kernel and modules build-ids 2022-07-18 16:35:34 -03:00
perf-c2c.txt perf c2c: Add report option to show false sharing in adjacent cachelines 2023-02-16 09:33:45 -03:00
perf-check.txt perf tools: Remove dependency on libaudit 2025-01-10 10:59:42 -03:00
perf-config.txt perf config: Fix trival typo 'an' -> 'can' 2024-12-09 17:51:53 -03:00
perf-daemon.txt perf daemon: Add examples to man page 2021-02-11 10:19:52 -03:00
perf-data.txt perf data: Add JSON export 2021-04-29 10:30:58 -03:00
perf-diff.txt perf tools: Make quiet mode consistent between tools 2022-10-27 16:37:26 -03:00
perf-dlfilter.txt perf dlfilter: Add al_cleanup() 2023-08-15 16:41:49 -03:00
perf-evlist.txt perf tools: Fix documentation of verbose options 2021-03-06 16:54:26 -03:00
perf-ftrace.txt perf ftrace profile: Add --graph-opts option 2025-01-08 17:20:42 -03:00
perf-help.txt
perf-inject.txt perf inject: Clarify build-id options a little bit 2022-10-04 08:55:22 -03:00
perf-intel-pt.txt perf intel-pt: Add documentation for pause / resume 2024-12-18 16:24:32 -03:00
perf-iostat.txt perf docs: Fix accidental em-dashes 2021-08-10 11:05:21 -03:00
perf-kallsyms.txt perf tools: Fix documentation of verbose options 2021-03-06 16:54:26 -03:00
perf-kmem.txt perf kmem: Improve man page for record options 2021-10-08 16:10:02 -03:00
perf-kvm.txt perf docs: Refine the description for the buffer size 2024-08-12 13:59:22 -03:00
perf-kwork.txt perf docs: Fix typos 2024-05-28 22:52:28 -07:00
perf-list.txt perf docs: Document tool and hwmon events 2024-11-09 08:28:03 -08:00
perf-lock.txt perf lock: Add percpu-rwsem for type filter 2025-01-17 10:12:40 -08:00
perf-mem.txt perf mem: Update documentation for new options 2024-08-05 11:40:20 -03:00
perf-probe.txt perf docs: Fix a typo in 'perf probe' man page: l20th -> 120th 2023-01-19 09:49:59 -03:00
perf-record.txt perf tools: Parse aux-action 2024-12-18 16:24:32 -03:00
perf-report.txt perf report: Display columns Predicted/Abort/Cycles in --branch-history 2024-10-10 23:41:23 -07:00
perf-sched.txt perf sched timehist: Add pre-migration wait time option 2024-10-14 12:04:31 -07:00
perf-script-perl.txt perf tools docs: Use canonical ftrace path 2023-02-02 16:32:19 -03:00
perf-script-python.txt perf scripting python: Add function to get a config value 2024-09-24 11:47:03 -07:00
perf-script.txt perf script: Add branch counters 2024-08-14 10:20:40 -03:00
perf-stat.txt perf stat: Add command line option for enabling TPEBS recording 2024-08-13 15:25:32 -03:00
perf-test.txt perf test: Improve verbose documentation 2025-01-16 11:01:03 -08:00
perf-timechart.txt perf timechart: Document missing --force option 2017-11-16 14:50:06 -03:00
perf-top.txt perf docs: Refine the description for the buffer size 2024-08-12 13:59:22 -03:00
perf-trace.txt perf docs: Add documentation for --force-btf option 2024-12-26 12:19:26 -03:00
perf-version.txt perf version: Add man page 2018-04-02 13:52:23 -03:00
perf.data-directory-format.txt perf record: Put a copy of kcore into the perf.data directory 2019-11-06 15:43:05 -03:00
perf.data-file-format.txt perf doc: Fix typo in perf.data-file-format.txt 2023-07-28 19:01:16 -03:00
perf.txt perf doc: Add AMD IBS usage document 2024-06-20 16:51:55 -07:00
perfconfig.example
security.txt perf docs: Introduce security.txt file to document related issues 2020-05-28 10:03:26 -03:00
tips.txt perf Documentation: Add some more hints to tips.txt 2024-02-01 22:18:18 -08:00
topdown.txt perf Document: Add TPEBS (Timed PEBS(Precise Event-Based Sampling)) to Documents 2024-08-13 15:25:33 -03:00