code:
**-c**, **--cpus** *cpu-list*

        Set the osnoise tracer to run the sample threads in the cpu-list.

**-d**, **--duration** *time[s|m|h|d]*

        Set the duration of the session.

**-D**, **--debug**

        Print debug info.

**-t**, **--trace**\[*=file*]

        Save the stopped trace to [*file|osnoise_trace.txt*].

**-e**, **--event** *sys:event*

        Enable an event in the trace (**-t**) session. The argument can be a specific event, e.g., **-e** *sched:sched_switch*, or all events of a system group, e.g., **-e** *sched*. Multiple **-e** are allowed. It is only active when **-t** or **-a** are set.

**--filter** *<filter>*

        Filter the previous **-e** *sys:event* event with *<filter>*. For further information about event filtering see https://www.kernel.org/doc/html/latest/trace/events.html#event-filtering.

**--trigger** *<trigger>*
        Enable a trace event trigger to the previous **-e** *sys:event*.
        If the *hist:* trigger is activated, the output histogram will be automatically saved to a file named *system_event_hist.txt*.
        For example, the command:

        rtla <command> <mode> -t -e osnoise:irq_noise --trigger="hist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount"

        Will automatically save the content of the histogram associated to *osnoise:irq_noise* event in *osnoise_irq_noise_hist.txt*.

        For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers.

**-P**, **--priority** *o:prio|r:prio|f:prio|d:runtime:period*

        Set scheduling parameters to the osnoise tracer threads, the format to set the priority are:

        - *o:prio* - use SCHED_OTHER with *prio*;
        - *r:prio* - use SCHED_RR with *prio*;
        - *f:prio* - use SCHED_FIFO with *prio*;
        - *d:runtime[us|ms|s]:period[us|ms|s]* - use SCHED_DEADLINE with *runtime* and *period* in nanoseconds.

**-h**, **--help**

        Print help menu.


code:
The **rtla osnoise** tool is an interface for the *osnoise* tracer. The
*osnoise* tracer dispatches a kernel thread per-cpu. These threads read the
time in a loop while with preemption, softirq and IRQs enabled, thus
allowing all the sources of operating system noise during its execution.
The *osnoise*'s tracer threads take note of the delta between each time
read, along with an interference counter of all sources of interference.
At the end of each period, the *osnoise* tracer displays a summary of
the results.

repo_name: angery/linux


code:
**-a**, **--auto** *us*

        Set the automatic trace mode. This mode sets some commonly used options
        while debugging the system. It is equivalent to use **-s** *us* **-T 1 -t**.

**-p**, **--period** *us*

        Set the *osnoise* tracer period in microseconds.

**-r**, **--runtime** *us*

        Set the *osnoise* tracer runtime in microseconds.

**-s**, **--stop** *us*

        Stop the trace if a single sample is higher than the argument in microseconds.
        If **-T** is set, it will also save the trace to the output.

**-S**, **--stop-total** *us*

        Stop the trace if the total sample is higher than the argument in microseconds.
        If **-T** is set, it will also save the trace to the output.

**-T**, **--threshold** *us*

        Specify the minimum delta between two time reads to be considered noise.
        The default threshold is *5 us*.


code:
The **rtla timerlat** tool is an interface for the *timerlat* tracer. The
*timerlat* tracer dispatches a kernel thread per-cpu. These threads
set a periodic timer to wake themselves up and go back to sleep. After
the wakeup, they collect and generate useful information for the
debugging of operating system timer latency.

The *timerlat* tracer outputs information in two ways. It periodically
prints the timer latency at the timer *IRQ* handler and the *Thread*
handler. It also enable the trace of the most relevant information via
**osnoise:** tracepoints.


code:
**-a**, **--auto** *us*

        Set the automatic trace mode. This mode sets some commonly used options
        while debugging the system. It is equivalent to use **-T** *us* **-s** *us*
        **-t**. By default, *timerlat* tracer uses FIFO:95 for *timerlat* threads,
        thus equilavent to **-P** *f:95*.

**-p**, **--period** *us*

        Set the *timerlat* tracer period in microseconds.

**-i**, **--irq** *us*

        Stop trace if the *IRQ* latency is higher than the argument in us.

**-T**, **--thread** *us*

        Stop trace if the *Thread* latency is higher than the argument in us.

**-s**, **--stack** *us*

        Save the stack trace at the *IRQ* if a *Thread* latency is higher than the
        argument in us.

**--dma-latency** *us*
        Set the /dev/cpu_dma_latency to *us*, aiming to bound exit from idle latencies.
        *cyclictest* sets this value to *0* by default, use **--dma-latency** *0* to have
        similar results.


code:
**-q**, **--quiet**

        Print only a summary at the end of the session.


code:
.. SPDX-License-Identifier: GPL-2.0

================================
The realtime Linux analysis tool
================================

RTLA provides a set of tools for the analysis of the kernel's realtime
behavior on specific hardware.

.. toctree::
   :maxdepth: 1

   rtla
   rtla-osnoise
   rtla-osnoise-hist
   rtla-osnoise-top
   rtla-timerlat
   rtla-timerlat-hist
   rtla-timerlat-top

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
===================
rtla-osnoise-hist
===================
------------------------------------------------------
Display a histogram of the osnoise tracer samples
------------------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla osnoise hist** [*OPTIONS*]

DESCRIPTION
===========
.. include:: common_osnoise_description.rst

The **rtla osnoise hist** tool collects all **osnoise:sample_threshold**
occurrence in a histogram, displaying the results in a user-friendly way.
The tool also allows many configurations of the *osnoise* tracer and the
collection of the tracer output.

OPTIONS
=======
.. include:: common_osnoise_options.rst

.. include:: common_hist_options.rst

.. include:: common_options.rst

EXAMPLE
=======
In the example below, *osnoise* tracer threads are set to run with real-time
priority *FIFO:1*, on CPUs *0-11*, for *900ms* at each period (*1s* by
default). The reason for reducing the runtime is to avoid starving the
**rtla** tool. The tool is also set to run for *one minute*. The output
histogram is set to group outputs in buckets of *10us* and *25* entries::

  [root@f34 ~/]# rtla osnoise hist -P F:1 -c 0-11 -r 900000 -d 1M -b 10 -E 25
  # RTLA osnoise histogram
  # Time unit is microseconds (us)
  # Duration:   0 00:01:00
  Index   CPU-000   CPU-001   CPU-002   CPU-003   CPU-004   CPU-005   CPU-006   CPU-007   CPU-008   CPU-009   CPU-010   CPU-011
  0         42982     46287     51779     53740     52024     44817     49898     36500     50408     50128     49523     52377
  10        12224      8356      2912       878      2667     10155      4573     18894      4214      4836      5708      2413
  20            8         5        12         2        13        24        20        41        29        53        39        39
  30            1         1         0         0        10         3         6        19        15        31        30        38
  40            0         0         0         0         0         4         2         7         2         3         8        11
  50            0         0         0         0         0         0         0         0         0         1         1         2
  over:         0         0         0         0         0         0         0         0         0         0         0         0
  count:    55215     54649     54703     54620     54714     55003     54499     55461     54668     55052     55309     54880
  min:          0         0         0         0         0         0         0         0         0         0         0         0
  avg:          0         0         0         0         0         0         0         0         0         0         0         0
  max:         30        30        20        20        30        40        40        40        40        50        50        50

SEE ALSO
========
**rtla-osnoise**\(1), **rtla-osnoise-top**\(1)

*osnoise* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html>

AUTHOR
======
Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
===================
rtla-osnoise-top
===================
-----------------------------------------------
Display a summary of the operating system noise
-----------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla osnoise top** [*OPTIONS*]

DESCRIPTION
===========
.. include:: common_osnoise_description.rst

**rtla osnoise top** collects the periodic summary from the *osnoise* tracer,
including the counters of the occurrence of the interference source,
displaying the results in a user-friendly format.

The tool also allows many configurations of the *osnoise* tracer and the
collection of the tracer output.

OPTIONS
=======
.. include:: common_osnoise_options.rst

.. include:: common_top_options.rst

.. include:: common_options.rst

EXAMPLE
=======
In the example below, the **rtla osnoise top** tool is set to run with a
real-time priority *FIFO:1*, on CPUs *0-3*, for *900ms* at each period
(*1s* by default). The reason for reducing the runtime is to avoid starving
the rtla tool. The tool is also set to run for *one minute* and to display
a summary of the report at the end of the session::

  [root@f34 ~]# rtla osnoise top -P F:1 -c 0-3 -r 900000 -d 1M -q
                                          Operating System Noise
  duration:   0 00:01:00 | time is in us
  CPU Period       Runtime        Noise  % CPU Aval   Max Noise   Max Single          HW          NMI          IRQ      Softirq       Thread
    0 #59         53100000       304896    99.42580        6978           56         549            0        53111         1590           13
    1 #59         53100000       338339    99.36282        8092           24         399            0        53130         1448           31
    2 #59         53100000       290842    99.45227        6582           39         855            0        53110         1406           12
    3 #59         53100000       204935    99.61405        6251           33         290            0        53156         1460           12

SEE ALSO
========

**rtla-osnoise**\(1), **rtla-osnoise-hist**\(1)

Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html>

AUTHOR
======
Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
===============
rtla-osnoise
===============
------------------------------------------------------------------
Measure the operating system noise
------------------------------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla osnoise** [*MODE*] ...

DESCRIPTION
===========

.. include:: common_osnoise_description.rst

The *osnoise* tracer outputs information in two ways. It periodically prints
a summary of the noise of the operating system, including the counters of
the occurrence of the source of interference. It also provides information
for each noise via the **osnoise:** tracepoints. The **rtla osnoise top**
mode displays information about the periodic summary from the *osnoise* tracer.
The **rtla osnoise hist** mode displays information about the noise using
the **osnoise:** tracepoints. For further details, please refer to the
respective man page.

MODES
=====
**top**

        Prints the summary from osnoise tracer.

**hist**

        Prints a histogram of osnoise samples.

If no MODE is given, the top mode is called, passing the arguments.

OPTIONS
=======

**-h**, **--help**

        Display the help text.

For other options, see the man page for the corresponding mode.

SEE ALSO
========
**rtla-osnoise-top**\(1), **rtla-osnoise-hist**\(1)

Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html>

AUTHOR
======
Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
=====================
rtla-timerlat-hist
=====================
------------------------------------------------
Histograms of the operating system timer latency
------------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla timerlat hist** [*OPTIONS*] ...

DESCRIPTION
===========

.. include:: common_timerlat_description.rst

The **rtla timerlat hist** displays a histogram of each tracer event
occurrence. This tool uses the periodic information, and the
**osnoise:** tracepoints are enabled when using the **-T** option.

OPTIONS
=======

.. include:: common_timerlat_options.rst

.. include:: common_hist_options.rst

.. include:: common_options.rst

EXAMPLE
=======
In the example below, **rtla timerlat hist** is set to run for *10* minutes,
in the cpus *0-4*, *skipping zero* only lines. Moreover, **rtla timerlat
hist** will change the priority of the *timerlat* threads to run under
*SCHED_DEADLINE* priority, with a *10us* runtime every *1ms* period. The
*1ms* period is also passed to the *timerlat* tracer::

  [root@alien ~]# timerlat hist -d 10m -c 0-4 -P d:100us:1ms -p 1ms
  # RTLA timerlat histogram
  # Time unit is microseconds (us)
  # Duration:   0 00:10:00
  Index   IRQ-000   Thr-000   IRQ-001   Thr-001   IRQ-002   Thr-002   IRQ-003   Thr-003   IRQ-004   Thr-004
  0        276489         0    206089         0    466018         0    481102         0    205546         0
  1        318327     35487    388149     30024     94531     48382     83082     71078    388026     55730
  2          3282    122584      4019    126527     28231    109012     23311     89309      4568     98739
  3           940     11815       837      9863      6209     16227      6895     17196       910      9780
  4           444     17287       424     11574      2097     38443      2169     36736       462     13476
  5           206     43291       255     25581      1223    101908      1304    101137       236     28913
  6           132    101501        96     64584       635    213774       757    215471        99     73453
  7            74    169347        65    124758       350     57466       441     53639        69    148573
  8            53     85183        31    156751       229      9052       306      9026        39    139907
  9            22     10387        12     42762       161      2554       225      2689        19     26192
  10           13      1898         8      5770       114      1247       128      1405        13      3772
  11            9       560         9       924        71       686        76       765         8       713
  12            4       256         2       360        50       411        64       474         3       278
  13            2       167         2       172        43       256        53       350         4       180
  14            1        88         1       116        15       198        42       223         0       115
  15            2        63         3        94        11       139        20       150         0        58
  16            2        37         0        56         5        78        10       102         0        39
  17            0        18         0        28         4        57         8        80         0        15
  18            0         8         0        17         2        50         6        56         0        12
  19            0         9         0         5         0        19         0        48         0        18
  20            0         4         0         8         0        11         2        27         0         4
  21            0         2         0         3         1         9         1        18         0         6
  22            0         1         0         3         1         7         0         3         0         5
  23            0         2         0         4         0         2         0         7         0         2
  24            0         2         0         2         1         3         0         3         0         5
  25            0         0         0         1         0         1         0         1         0         3
  26            0         1         0         0         0         2         0         2         0         0
  27            0         0         0         3         0         1         0         0         0         1
  28            0         0         0         3         0         0         0         1         0         0
  29            0         0         0         2         0         2         0         1         0         3
  30            0         1         0         0         0         0         0         0         0         0
  31            0         1         0         0         0         0         0         2         0         2
  32            0         0         0         1         0         2         0         0         0         0
  33            0         0         0         2         0         0         0         0         0         1
  34            0         0         0         0         0         0         0         0         0         2
  35            0         1         0         1         0         0         0         0         0         1
  36            0         1         0         0         0         1         0         1         0         0
  37            0         0         0         1         0         0         0         0         0         0
  40            0         0         0         0         0         1         0         1         0         0
  41            0         0         0         0         0         0         0         0         0         1
  42            0         0         0         0         0         0         0         0         0         1
  44            0         0         0         0         0         1         0         0         0         0
  46            0         0         0         0         0         0         0         1         0         0
  47            0         0         0         0         0         0         0         0         0         1
  50            0         0         0         0         0         0         0         0         0         1
  54            0         0         0         1         0         0         0         0         0         0
  58            0         0         0         1         0         0         0         0         0         0
  over:         0         0         0         0         0         0         0         0         0         0
  count:   600002    600002    600002    600002    600002    600002    600002    600002    600002    600002
  min:          0         1         0         1         0         1         0         1         0         1
  avg:          0         5         0         5         0         4         0         4         0         5
  max:         16        36        15        58        24        44        21        46        13        50

SEE ALSO
========
**rtla-timerlat**\(1), **rtla-timerlat-top**\(1)

*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html>

AUTHOR
======
Written by Daniel Bristot de Oliveira <bristot@kernel.org>


code:
====================
rtla-timerlat-top
====================
-------------------------------------------
Measures the operating system timer latency
-------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla timerlat top** [*OPTIONS*] ...

DESCRIPTION
===========

.. include:: common_timerlat_description.rst

The **rtla timerlat top** displays a summary of the periodic output
from the *timerlat* tracer. It also provides information for each
operating system noise via the **osnoise:** tracepoints that can be
seem with the option **-T**.

OPTIONS
=======

.. include:: common_timerlat_options.rst

.. include:: common_top_options.rst

.. include:: common_options.rst

EXAMPLE
=======

In the example below, the *timerlat* tracer is set to capture the stack trace at
the IRQ handler, printing it to the buffer if the *Thread* timer latency is
higher than *30 us*. It is also set to stop the session if a *Thread* timer
latency higher than *30 us* is hit. Finally, it is set to save the trace
buffer if the stop condition is hit::

  [root@alien ~]# rtla timerlat top -s 30 -T 30 -t
                   Timer Latency
    0 00:00:59   |          IRQ Timer Latency (us)        |         Thread Timer Latency (us)
  CPU COUNT      |      cur       min       avg       max |      cur       min       avg       max
    0 #58634     |        1         0         1        10 |       11         2        10        23
    1 #58634     |        1         0         1         9 |       12         2         9        23
    2 #58634     |        0         0         1        11 |       10         2         9        23
    3 #58634     |        1         0         1        11 |       11         2         9        24
    4 #58634     |        1         0         1        10 |       11         2         9        26
    5 #58634     |        1         0         1         8 |       10         2         9        25
    6 #58634     |       12         0         1        12 |       30         2        10        30 <--- CPU with spike
    7 #58634     |        1         0         1         9 |       11         2         9        23
    8 #58633     |        1         0         1         9 |       11         2         9        26
    9 #58633     |        1         0         1         9 |       10         2         9        26
   10 #58633     |        1         0         1        13 |       11         2         9        28
   11 #58633     |        1         0         1        13 |       12         2         9        24
   12 #58633     |        1         0         1         8 |       10         2         9        23
   13 #58633     |        1         0         1        10 |       10         2         9        22
   14 #58633     |        1         0         1        18 |       12         2         9        27
   15 #58633     |        1         0         1        10 |       11         2         9        28
   16 #58633     |        0         0         1        11 |        7         2         9        26
   17 #58633     |        1         0         1        13 |       10         2         9        24
   18 #58633     |        1         0         1         9 |       13         2         9        22
   19 #58633     |        1         0         1        10 |       11         2         9        23
   20 #58633     |        1         0         1        12 |       11         2         9        28
   21 #58633     |        1         0         1        14 |       11         2         9        24
   22 #58633     |        1         0         1         8 |       11         2         9        22
   23 #58633     |        1         0         1        10 |       11         2         9        27
  timerlat hit stop tracing
  saving trace to timerlat_trace.txt
  [root@alien bristot]# tail -60 timerlat_trace.txt
  [...]
      timerlat/5-79755   [005] .......   426.271226: #58634 context thread timer_latency     10823 ns
              sh-109404  [006] dnLh213   426.271247: #58634 context    irq timer_latency     12505 ns
              sh-109404  [006] dNLh313   426.271258: irq_noise: local_timer:236 start 426.271245463 duration 12553 ns
              sh-109404  [006] d...313   426.271263: thread_noise:       sh:109404 start 426.271245853 duration 4769 ns
      timerlat/6-79756   [006] .......   426.271264: #58634 context thread timer_latency     30328 ns
      timerlat/6-79756   [006] ....1..   426.271265: <stack trace>
  => timerlat_irq
  => __hrtimer_run_queues
  => hrtimer_interrupt
  => __sysvec_apic_timer_interrupt
  => sysvec_apic_timer_interrupt
  => asm_sysvec_apic_timer_interrupt
  => _raw_spin_unlock_irqrestore			<---- spinlock that disabled interrupt.
  => try_to_wake_up
  => autoremove_wake_function
  => __wake_up_common
  => __wake_up_common_lock
  => ep_poll_callback
  => __wake_up_common
  => __wake_up_common_lock
  => fsnotify_add_event
  => inotify_handle_inode_event
  => fsnotify
  => __fsnotify_parent
  => __fput
  => task_work_run
  => exit_to_user_mode_prepare
  => syscall_exit_to_user_mode
  => do_syscall_64
  => entry_SYSCALL_64_after_hwframe
  => 0x7265000001378c
  => 0x10000cea7
  => 0x25a00000204a
  => 0x12e302d00000000
  => 0x19b51010901b6
  => 0x283ce00726500
  => 0x61ea308872
  => 0x00000fe3
            bash-109109  [007] d..h...   426.271265: #58634 context    irq timer_latency      1211 ns
      timerlat/6-79756   [006] .......   426.271267: timerlat_main: stop tracing hit on cpu 6

In the trace, it is possible the notice that the *IRQ* timer latency was
already high, accounting *12505 ns*. The IRQ delay was caused by the
*bash-109109* process that disabled IRQs in the wake-up path
(*_try_to_wake_up()* function). The duration of the IRQ handler that woke
up the timerlat thread, informed with the **osnoise:irq_noise** event, was
also high and added more *12553 ns* to the Thread latency. Finally, the
**osnoise:thread_noise** added by the currently running thread (including
the scheduling overhead) added more *4769 ns*. Summing up these values,
the *Thread* timer latency accounted for *30328 ns*.

The primary reason for this high value is the wake-up path that was hit
twice during this case: when the *bash-109109* was waking up a thread
and then when the *timerlat* thread was awakened. This information can
then be used as the starting point of a more fine-grained analysis.

Note that **rtla timerlat** was dispatched without changing *timerlat* tracer
threads' priority. That is generally not needed because these threads hava
priority *FIFO:95* by default, which is a common priority used by real-time
kernel developers to analyze scheduling delays.

SEE ALSO
--------
**rtla-timerlat**\(1), **rtla-timerlat-hist**\(1)

*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html>

AUTHOR
------
Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
================
rtla-timerlat
================
-------------------------------------------
Measures the operating system timer latency
-------------------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla timerlat** [*MODE*] ...

DESCRIPTION
===========

.. include:: common_timerlat_description.rst

The *timerlat* tracer outputs information in two ways. It periodically
prints the timer latency at the timer *IRQ* handler and the *Thread* handler.
It also provides information for each noise via the **osnoise:** tracepoints.
The **rtla timerlat top** mode displays a summary of the periodic output
from the *timerlat* tracer. The **rtla hist hist** mode displays a histogram
of each tracer event occurrence. For further details, please refer to the
respective man page.

MODES
=====
**top**

        Prints the summary from *timerlat* tracer.

**hist**

        Prints a histogram of timerlat samples.

If no *MODE* is given, the top mode is called, passing the arguments.

OPTIONS
=======
**-h**, **--help**

        Display the help text.

For other options, see the man page for the corresponding mode.

SEE ALSO
========
**rtla-timerlat-top**\(1), **rtla-timerlat-hist**\(1)

*timerlat* tracer documentation: <https://www.kernel.org/doc/html/latest/trace/timerlat-tracer.html>

AUTHOR
======
Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
=========
rtla
=========
--------------------------------
Real-time Linux Analysis tool
--------------------------------

:Manual section: 1

SYNOPSIS
========
**rtla** *COMMAND* [*OPTIONS*]

DESCRIPTION
===========
The **rtla** is a meta-tool that includes a set of commands that aims to
analyze the real-time properties of Linux. But instead of testing Linux
as a black box, **rtla** leverages kernel tracing capabilities to provide
precise information about the properties and root causes of unexpected
results.

COMMANDS
========
**osnoise**

        Gives information about the operating system noise (osnoise).

**timerlat**

        Measures the IRQ and thread timer latency.

OPTIONS
=======
**-h**, **--help**

        Display the help text.

For other options, see the man page for the corresponding command.

SEE ALSO
========
**rtla-osnoise**\(1), **rtla-timerlat**\(1)

AUTHOR
======
Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
# SPDX-License-Identifier: GPL-2.0-only

INSTALL		?= install
RM		?= rm -f
RMDIR		?= rmdir --ignore-fail-on-non-empty

PREFIX		?= /usr/share
MANDIR		?= $(PREFIX)/man
MAN1DIR		= $(MANDIR)/man1

MAN1_RST	= $(wildcard rv*.rst)

_DOC_MAN1	= $(patsubst %.rst,%.1,$(MAN1_RST))
DOC_MAN1	= $(addprefix $(OUTPUT),$(_DOC_MAN1))

RST2MAN_DEP	:= $(shell command -v rst2man 2>/dev/null)
RST2MAN_OPTS	+= --verbose

TEST_RST2MAN = $(shell sh -c "rst2man --version > /dev/null 2>&1 || echo n")

$(OUTPUT)%.1: %.rst
ifndef RST2MAN_DEP
	$(info ********************************************)
	$(info ** NOTICE: rst2man not found)
	$(info **)
	$(info ** Consider installing the latest rst2man from your)
	$(info ** distribution, e.g., 'dnf install python3-docutils' on Fedora,)
	$(info ** or from source:)
	$(info **)
	$(info **  https://docutils.sourceforge.io/docs/dev/repository.html )
	$(info **)
	$(info ********************************************)
	$(error NOTICE: rst2man required to generate man pages)
endif
	rst2man $(RST2MAN_OPTS) $< > $@

man1: $(DOC_MAN1)
man: man1

clean:
	$(RM) $(DOC_MAN1)

install: man
	$(INSTALL) -d -m 755 $(DESTDIR)$(MAN1DIR)
	$(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(MAN1DIR)

uninstall:
	$(RM) $(addprefix $(DESTDIR)$(MAN1DIR)/,$(_DOC_MAN1))
	$(RMDIR) $(DESTDIR)$(MAN1DIR)

.PHONY: man man1 clean install uninstall
.DEFAULT_GOAL := man

path: Documentation/tools/rv/Makefile


code:
REPORTING BUGS
==============

Report bugs to <linux-kernel@vger.kernel.org>
and <linux-trace-devel@vger.kernel.org>

LICENSE
=======

**rv** is Free Software licensed under the GNU GPLv2

COPYING
=======

Copyright \(C) 2022 Red Hat, Inc. Free use of this software is granted under
the terms of the GNU Public License (GPL).


code:
**-h**, **--help**

        Print the monitor's options and the available reactors list.

**-r**, **--reactor** *reactor*

        Enables the *reactor*. See **-h** for a list of available reactors.

**-s**, **--self**

        When tracing (**-t**), also print the events that happened during the **rv**
        command itself. If the **rv** command itself generates too many events,
        the tool might get busy processing its own events only.

**-t**, **--trace**

        Trace monitor's events and error.

**-v**, **--verbose**

        Print debug messages.


code:
.. SPDX-License-Identifier: GPL-2.0

==============================
Runtime verification (rv) tool
==============================

**rv** tool provides the interface for a collection of runtime verification
(rv) monitors.

.. toctree::
   :maxdepth: 1

   rv
   rv-list
   rv-mon
   rv-mon-wip
   rv-mon-wwnr

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`


code:
.. SPDX-License-Identifier: GPL-2.0

=======
rv-list
=======
-----------------------
List available monitors
-----------------------

:Manual section: 1

SYNOPSIS
========

**rv list** [*OPTIONS*]

DESCRIPTION
===========

The **rv list** command prints all available monitors. These monitors
can be enabled using the **rv mon** command.

OPTIONS
=======

**-h**, **--help**

        Print help menu.

SEE ALSO
========

**rv**\(1), **rv-mon**\(1)

Linux kernel *RV* documentation:
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>

AUTHOR
======

Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
.. SPDX-License-Identifier: GPL-2.0

==========
rv-mon-wip
==========
----------------------------
Wakeup In Preemptive monitor
----------------------------

:Manual section: 1

SYNOPSIS
========

**rv mon wip** [*OPTIONS*]

DESCRIPTION
===========

The wakeup in preemptive (**wip**) monitor is a sample per-cpu monitor that
checks if the wakeup events always take place with preemption disabled.

See kernel documentation for further information about this monitor:
<https://docs.kernel.org/trace/rv/monitor_wip.html>

OPTIONS
=======

.. include:: common_ikm.rst

SEE ALSO
========

**rv**\(1), **rv-mon**\(1)

Linux kernel *RV* documentation:
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>

AUTHOR
======

Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
.. SPDX-License-Identifier: GPL-2.0

===========
rv-mon-wwnr
===========
--------------------------------
Wakeup While Not Running monitor
--------------------------------

:Manual section: 1

SYNOPSIS
========

**rv mon wip** [*OPTIONS*]

DESCRIPTION
===========

The wakeup while not running (**wwnr**) is a per-task sample monitor.

See kernel documentation for further information about this monitor:
<https://docs.kernel.org/trace/rv/monitor_wwnr.html>

OPTIONS
=======

.. include:: common_ikm.rst

SEE ALSO
========

**rv**\(1), **rv-mon**\(1)

Linux kernel *RV* documentation:
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>

AUTHOR
======

Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
.. SPDX-License-Identifier: GPL-2.0

=======
rv-list
=======
-----------------------
List available monitors
-----------------------

:Manual section: 1

SYNOPSIS
========

**rv mon** [*-h*] **monitor_name** [*-h*] [*MONITOR OPTIONS*]

DESCRIPTION
===========

The **rv mon** command runs the monitor named *monitor_name*. Each monitor
has its own set of options. The **rv list** command shows all available
monitors.

OPTIONS
=======

**-h**, **--help**

        Print help menu.

AVAILABLE MONITORS
==================

The **rv** tool provides the interface for a set of monitors. Use the
**rv list** command to list all available monitors.

Each monitor has its own set of options. See man **rv-mon**-*monitor_name*
for details about each specific monitor. Also, running **rv mon**
**monitor_name** **-h** display the help menu with the available
options.

SEE ALSO
========

**rv**\(1), **rv-mon**\(1)

Linux kernel *RV* documentation:
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>

AUTHOR
======

Written by Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
.. SPDX-License-Identifier: GPL-2.0

==
rv
==
--------------------
Runtime Verification
--------------------

:Manual section: 1

SYNOPSIS
========

**rv** *COMMAND* [*OPTIONS*]

DESCRIPTION
===========

Runtime Verification (**RV**) is a lightweight (yet rigorous) method
for formal verification with a practical approach for complex systems.
Instead of relying on a fine-grained model of a system (e.g., a
re-implementation a instruction level), RV works by analyzing the trace
of the system's actual execution, comparing it against a formal
specification of the system behavior.

The **rv** tool provides the interface for a collection of runtime
verification (rv) monitors.

COMMANDS
========

**list**

        List all available monitors.

**mon**

        Run monitor.

OPTIONS
=======

**-h**, **--help**

        Display the help text.

For other options, see the man page for the corresponding command.

SEE ALSO
========

**rv-list**\(1), **rv-mon**\(1)

Linux kernel *RV* documentation:
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>

AUTHOR
======

Daniel Bristot de Oliveira <bristot@kernel.org>

.. include:: common_appendix.rst


code:
.. SPDX-License-Identifier: GPL-2.0

=================
Boot-time tracing
=================

:Author: Masami Hiramatsu <mhiramat@kernel.org>

Overview
========

Boot-time tracing allows users to trace boot-time process including
device initialization with full features of ftrace including per-event
filter and actions, histograms, kprobe-events and synthetic-events,
and trace instances.
Since kernel command line is not enough to control these complex features,
this uses bootconfig file to describe tracing feature programming.

Options in the Boot Config
==========================

Here is the list of available options list for boot time tracing in
boot config file [1]_. All options are under "ftrace." or "kernel."
prefix. See kernel parameters for the options which starts
with "kernel." prefix [2]_.

.. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
.. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`

Ftrace Global Options
---------------------

Ftrace global options have "kernel." prefix in boot config, which means
these options are passed as a part of kernel legacy command line.

kernel.tp_printk
   Output trace-event data on printk buffer too.

kernel.dump_on_oops [= MODE]
   Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
   on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.

kernel.traceoff_on_warning
   Stop tracing if WARN_ON() occurs.

kernel.fgraph_max_depth = MAX_DEPTH
   Set MAX_DEPTH to maximum depth of fgraph tracer.

kernel.fgraph_filters = FILTER[, FILTER2...]
   Add fgraph tracing function filters.

kernel.fgraph_notraces = FILTER[, FILTER2...]
   Add fgraph non-tracing function filters.

Ftrace Per-instance Options
---------------------------

These options can be used for each instance including global ftrace node.

ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
   Enable given ftrace options.

ftrace.[instance.INSTANCE.]tracing_on = 0|1
   Enable/Disable tracing on this instance when starting boot-time tracing.
   (you can enable it by the "traceon" event trigger action)

ftrace.[instance.INSTANCE.]trace_clock = CLOCK
   Set given CLOCK to ftrace's trace_clock.

ftrace.[instance.INSTANCE.]buffer_size = SIZE
   Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
   for that SIZE.

ftrace.[instance.INSTANCE.]alloc_snapshot
   Allocate snapshot buffer.

ftrace.[instance.INSTANCE.]cpumask = CPUMASK
   Set CPUMASK as trace cpu-mask.

ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
   Enable given events on boot. You can use a wild card in EVENT.

ftrace.[instance.INSTANCE.]tracer = TRACER
   Set TRACER to current tracer on boot. (e.g. function)

ftrace.[instance.INSTANCE.]ftrace.filters
   This will take an array of tracing function filter rules.

ftrace.[instance.INSTANCE.]ftrace.notraces
   This will take an array of NON-tracing function filter rules.

Ftrace Per-Event Options
------------------------

These options are setting per-event options.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
   Enable GROUP:EVENT tracing.

ftrace.[instance.INSTANCE.]event.GROUP.enable
   Enable all event tracing within GROUP.

ftrace.[instance.INSTANCE.]event.enable
   Enable all event tracing.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
   Set FILTER rule to the GROUP:EVENT.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
   Set ACTIONs to the GROUP:EVENT.

ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
   Defines new kprobe event based on PROBEs. It is able to define
   multiple probes on one event, but those must have same type of
   arguments. This option is available only for the event which
   group name is "kprobes".

ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
   Defines new synthetic event with FIELDs. Each field should be
   "type varname".

Note that kprobe and synthetic event definitions can be written under
instance node, but those are also visible from other instances. So please
take care for event name conflict.

Ftrace Histogram Options
------------------------

Since it is too long to write a histogram action as a string for per-event
action option, there are tree-style options under per-event 'hist' subkey
for the histogram actions. For the detail of the each parameter,
please read the event histogram document (Documentation/trace/histogram.rst)

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]keys = KEY1[, KEY2[...]]
  Set histogram key parameters. (Mandatory)
  The 'N' is a digit string for the multiple histogram. You can omit it
  if there is one histogram on the event.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]values = VAL1[, VAL2[...]]
  Set histogram value parameters.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]sort = SORT1[, SORT2[...]]
  Set histogram sort parameter options.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]size = NR_ENTRIES
  Set histogram size (number of entries).

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]name = NAME
  Set histogram name.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]var.VARIABLE = EXPR
  Define a new VARIABLE by EXPR expression.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<pause|continue|clear>
  Set histogram control parameter. You can set one of them.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]event = GROUP.EVENT
  Set histogram 'onmatch' handler matching event parameter.
  The 'M' is a digit string for the multiple 'onmatch' handler. You can omit it
  if there is one 'onmatch' handler on this histogram.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmatch.[M.]trace = EVENT[, ARG1[...]]
  Set histogram 'trace' action for 'onmatch'.
  EVENT must be a synthetic event name, and ARG1... are parameters
  for that event. Mandatory if 'onmatch.event' option is set.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onmax.[M.]var = VAR
  Set histogram 'onmax' handler variable parameter.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]onchange.[M.]var = VAR
  Set histogram 'onchange' handler variable parameter.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]save = ARG1[, ARG2[...]]
  Set histogram 'save' action parameters for 'onmax' or 'onchange' handler.
  This option or below 'snapshot' option is mandatory if 'onmax.var' or
  'onchange.var' option is set.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.[N.]<onmax|onchange>.[M.]snapshot
  Set histogram 'snapshot' action for 'onmax' or 'onchange' handler.
  This option or above 'save' option is mandatory if 'onmax.var' or
  'onchange.var' option is set.

ftrace.[instance.INSTANCE.]event.GROUP.EVENT.hist.filter = FILTER_EXPR
  Set histogram filter expression. You don't need 'if' in the FILTER_EXPR.

Note that this 'hist' option can conflict with the per-event 'actions'
option if the 'actions' option has a histogram action.

When to Start
=============

All boot-time tracing options starting with ``ftrace`` will be enabled at the
end of core_initcall. This means you can trace the events from postcore_initcall.
Most of the subsystems and architecture dependent drivers will be initialized
after that (arch_initcall or subsys_initcall). Thus, you can trace those with
boot-time tracing.
If you want to trace events before core_initcall, you can use the options
starting with ``kernel``. Some of them will be enabled eariler than the initcall
processing (for example,. ``kernel.ftrace=function`` and ``kernel.trace_event``
will start before the initcall.)

Examples
========

For example, to add filter and actions for each event, define kprobe
events, and synthetic events with histogram, write a boot config like
below::

  ftrace.event {
        task.task_newtask {
                filter = "pid < 128"
                enable
        }
        kprobes.vfs_read {
                probes = "vfs_read $arg1 $arg2"
                filter = "common_pid < 200"
                enable
        }
        synthetic.initcall_latency {
                fields = "unsigned long func", "u64 lat"
                hist {
                        keys = func.sym, lat
                        values = lat
                        sort = lat
                }
        }
        initcall.initcall_start.hist {
                keys = func
                var.ts0 = common_timestamp.usecs
        }
        initcall.initcall_finish.hist {
                keys = func
                var.lat = common_timestamp.usecs - $ts0
                onmatch {
                        event = initcall.initcall_start
                        trace = initcall_latency, func, $lat
                }
        }
  }

Also, boot-time tracing supports "instance" node, which allows us to run
several tracers for different purpose at once. For example, one tracer
is for tracing functions starting with "user\_", and others tracing
"kernel\_" functions, you can write boot config as below::

  ftrace.instance {
        foo {
                tracer = "function"
                ftrace.filters = "user_*"
        }
        bar {
                tracer = "function"
                ftrace.filters = "kernel_*"
        }
  }

The instance node also accepts event nodes so that each instance
can customize its event tracing.

With the trigger action and kprobes, you can trace function-graph while
a function is called. For example, this will trace all function calls in
the pci_proc_init()::

  ftrace {
        tracing_on = 0
        tracer = function_graph
        event.kprobes {
                start_event {
                        probes = "pci_proc_init"
                        actions = "traceon"
                }
                end_event {
                        probes = "pci_proc_init%return"
                        actions = "traceoff"
                }
        }
  }

This boot-time tracing also supports ftrace kernel parameters via boot
config.
For example, following kernel parameters::

 trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"

This can be written in boot config like below::

  kernel {
        trace_options = sym-addr
        trace_event = "initcall:*"
        tp_printk
        trace_buf_size = 1M
        ftrace = function
        ftrace_filter = "vfs*"
  }

Note that parameters start with "kernel" prefix instead of "ftrace".


code:
.. SPDX-License-Identifier: GPL-2.0

======================================
CoreSight System Configuration Manager
======================================

    :Author:   Mike Leach <mike.leach@linaro.org>
    :Date:     October 2020

Introduction
============

The CoreSight System Configuration manager is an API that allows the
programming of the CoreSight system with pre-defined configurations that
can then be easily enabled from sysfs or perf.

Many CoreSight components can be programmed in complex ways - especially ETMs.
In addition, components can interact across the CoreSight system, often via
the cross trigger components such as CTI and CTM. These system settings can
be defined and enabled as named configurations.

Basic Concepts
==============

This section introduces the basic concepts of a CoreSight system configuration.

Features
--------

A feature is a named set of programming for a CoreSight device. The programming
is device dependent, and can be defined in terms of absolute register values,
resource usage and parameter values.

The feature is defined using a descriptor. This descriptor is used to load onto
a matching device, either when the feature is loaded into the system, or when the
CoreSight device is registered with the configuration manager.

The load process involves interpreting the descriptor into a set of register
accesses in the driver - the resource usage and parameter descriptions
translated into appropriate register accesses. This interpretation makes it easy
and efficient for the feature to be programmed onto the device when required.

The feature will not be active on the device until the feature is enabled, and
the device itself is enabled. When the device is enabled then enabled features
will be programmed into the device hardware.

A feature is enabled as part of a configuration being enabled on the system.

Parameter Value
~~~~~~~~~~~~~~~

A parameter value is a named value that may be set by the user prior to the
feature being enabled that can adjust the behaviour of the operation programmed
by the feature.

For example, this could be a count value in a programmed operation that repeats
at a given rate. When the feature is enabled then the current value of the
parameter is used in programming the device.

The feature descriptor defines a default value for a parameter, which is used
if the user does not supply a new value.

Users can update parameter values using the configfs API for the CoreSight
system - which is described below.

The current value of the parameter is loaded into the device when the feature
is enabled on that device.

Configurations
--------------

A configuration defines a set of features that are to be used in a trace
session where the configuration is selected. For any trace session only one
configuration may be selected.

The features defined may be on any type of device that is registered
to support system configuration. A configuration may select features to be
enabled on a class of devices - i.e. any ETMv4, or specific devices, e.g. a
specific CTI on the system.

As with the feature, a descriptor is used to define the configuration.
This will define the features that must be enabled as part of the configuration
as well as any preset values that can be used to override default parameter
values.

Preset Values
~~~~~~~~~~~~~

Preset values are easily selectable sets of parameter values for the features
that the configuration uses. The number of values in a single preset set, equals
the sum of parameter values in the features used by the configuration.

e.g. a configuration consists of 3 features, one has 2 parameters, one has
a single parameter, and another has no parameters. A single preset set will
therefore have 3 values.

Presets are optionally defined by the configuration, up to 15 can be defined.
If no preset is selected, then the parameter values defined in the feature
are used as normal.

Operation
~~~~~~~~~

The following steps take place in the operation of a configuration.

1) In this example, the configuration is 'autofdo', which has an
   associated feature 'strobing' that works on ETMv4 CoreSight Devices.

2) The configuration is enabled. For example 'perf' may select the
   configuration as part of its command line::

    perf record -e cs_etm/autofdo/ myapp

   which will enable the 'autofdo' configuration.

3) perf starts tracing on the system. As each ETMv4 that perf uses for
   trace is enabled,  the configuration manager will check if the ETMv4
   has a feature that relates to the currently active configuration.
   In this case 'strobing' is enabled & programmed into the ETMv4.

4) When the ETMv4 is disabled, any registers marked as needing to be
   saved will be read back.

5) At the end of the perf session, the configuration will be disabled.

Viewing Configurations and Features
===================================

The set of configurations and features that are currently loaded into the
system can be viewed using the configfs API.

Mount configfs as normal and the 'cs-syscfg' subsystem will appear::

    $ ls /config
    cs-syscfg  stp-policy

This has two sub-directories::

    $ cd cs-syscfg/
    $ ls
    configurations  features

The system has the configuration 'autofdo' built in. It may be examined as
follows::

    $ cd configurations/
    $ ls
    autofdo
    $ cd autofdo/
    $ ls
    description  feature_refs  preset1  preset3  preset5  preset7  preset9
    enable       preset        preset2  preset4  preset6  preset8
    $ cat description
    Setup ETMs with strobing for autofdo
    $ cat feature_refs
    strobing

Each preset declared has a 'preset<n>' subdirectory declared. The values for
the preset can be examined::

    $ cat preset1/values
    strobing.window = 0x1388 strobing.period = 0x2
    $ cat preset2/values
    strobing.window = 0x1388 strobing.period = 0x4

The 'enable' and 'preset' files allow the control of a configuration when
using CoreSight with sysfs.

The features referenced by the configuration can be examined in the features
directory::

    $ cd ../../features/strobing/
    $ ls
    description  matches  nr_params  params
    $ cat description
    Generate periodic trace capture windows.
    parameter 'window': a number of CPU cycles (W)
    parameter 'period': trace enabled for W cycles every period x W cycles
    $ cat matches
    SRC_ETMV4
    $ cat nr_params
    2

Move to the params directory to examine and adjust parameters::

    cd params
    $ ls
    period  window
    $ cd period
    $ ls
    value
    $ cat value
    0x2710
    # echo 15000 > value
    # cat value
    0x3a98

Parameters adjusted in this way are reflected in all device instances that have
loaded the feature.

Using Configurations in perf
============================

The configurations loaded into the CoreSight configuration management are
also declared in the perf 'cs_etm' event infrastructure so that they can
be selected when running trace under perf::

    $ ls /sys/devices/cs_etm
    cpu0  cpu2  events  nr_addr_filters		power  subsystem  uevent
    cpu1  cpu3  format  perf_event_mux_interval_ms	sinks  type

The key directory here is 'events' - a generic perf directory which allows
selection on the perf command line. As with the sinks entries, this provides
a hash of the configuration name.

The entry in the 'events' directory uses perfs built in syntax generator
to substitute the syntax for the name when evaluating the command::

    $ ls events/
    autofdo
    $ cat events/autofdo
    configid=0xa7c3dddd

The 'autofdo' configuration may be selected on the perf command line::

    $ perf record -e cs_etm/autofdo/u --per-thread <application>

A preset to override the current parameter values can also be selected::

    $ perf record -e cs_etm/autofdo,preset=1/u --per-thread <application>

When configurations are selected in this way, then the trace sink used is
automatically selected.

Using Configurations in sysfs
=============================

Coresight can be controlled using sysfs. When this is in use then a configuration
can be made active for the devices that are used in the sysfs session.

In a configuration there are 'enable' and 'preset' files.

To enable a configuration for use with sysfs::

    $ cd configurations/autofdo
    $ echo 1 > enable

This will then use any default parameter values in the features - which can be
adjusted as described above.

To use a preset<n> set of parameter values::

    $ echo 3 > preset

This will select preset3 for the configuration.
The valid values for preset are 0 - to deselect presets, and any value of
<n> where a preset<n> sub-directory is present.

Note that the active sysfs configuration is a global parameter, therefore
only a single configuration can be active for sysfs at any one time.
Attempting to enable a second configuration will result in an error.
Additionally, attempting to disable the configuration while in use will
also result in an error.

The use of the active configuration by sysfs is independent of the configuration
used in perf.

Creating and Loading Custom Configurations
==========================================

Custom configurations and / or features can be dynamically loaded into the
system by using a loadable module.

An example of a custom configuration is found in ./samples/coresight.

This creates a new configuration that uses the existing built in
strobing feature, but provides a different set of presets.

When the module is loaded, then the configuration appears in the configfs
file system and is selectable in the same way as the built in configuration
described above.

Configurations can use previously loaded features. The system will ensure
that it is not possible to unload a feature that is currently in use, by
enforcing the unload order as the strict reverse of the load order.


code:
==========================
Coresight CPU Debug Module
==========================

   :Author:   Leo Yan <leo.yan@linaro.org>
   :Date:     April 5th, 2017

Introduction
------------

Coresight CPU debug module is defined in ARMv8-a architecture reference manual
(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate
debug module and it is mainly used for two modes: self-hosted debug and
external debug. Usually the external debug mode is well known as the external
debugger connects with SoC from JTAG port; on the other hand the program can
explore debugging method which rely on self-hosted debug mode, this document
is to focus on this part.

The debug module provides sample-based profiling extension, which can be used
to sample CPU program counter, secure state and exception level, etc; usually
every CPU has one dedicated debug module to be connected. Based on self-hosted
debug mechanism, Linux kernel can access these related registers from mmio
region when the kernel panic happens. The callback notifier for kernel panic
will dump related registers for every CPU; finally this is good for assistant
analysis for panic.

Implementation
--------------

- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID
  registers to decide if sample-based profiling is implemented or not. On some
  platforms this hardware feature is fully or partially implemented; and if
  this feature is not supported then registration will fail.

- At the time this documentation was written, the debug driver mainly relies on
  information gathered by the kernel panic callback notifier from three
  sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get
  program counter; EDVIDSR has information for secure state, exception level,
  bit width, etc; EDCIDSR is context ID value which contains the sampled value
  of CONTEXTIDR_EL1.

- The driver supports a CPU running in either AArch64 or AArch32 mode. The
  registers naming convention is a bit different between them, AArch64 uses
  'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses
  'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to
  use AArch64 naming convention.

- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different
  register bits definition. So the driver consolidates two difference:

  If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented;
  but ARMv7-a defines "PCSR samples are offset by a value that depends on the
  instruction set state". For ARMv7-a, the driver checks furthermore if CPU
  runs with ARM or thumb instruction set and calibrate PCSR value, the
  detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter
  C11.11.34 "DBGPCSR, Program Counter Sampling Register".

  If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have
  no offset applied and do not sample the instruction set state in AArch32
  state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates
  in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64
  state EDPCSR is sampled and no offset are applied.

Clock and power domain
----------------------

Before accessing debug registers, we should ensure the clock and power domain
have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
Debug registers', the debug registers are spread into two domains: the debug
domain and the CPU domain.
::

                                +---------------+
                                |               |
                                |               |
                     +----------+--+            |
        dbg_clock -->|          |**|            |<-- cpu_clock
                     |    Debug |**|   CPU      |
 dbg_power_domain -->|          |**|            |<-- cpu_power_domain
                     +----------+--+            |
                                |               |
                                |               |
                                +---------------+

For debug domain, the user uses DT binding "clocks" and "power-domains" to
specify the corresponding clock source and power supply for the debug logic.
The driver calls the pm_runtime_{put|get} operations as needed to handle the
debug power domain.

For CPU domain, the different SoC designs have different power management
schemes and finally this heavily impacts external debug module. So we can
divide into below cases:

- On systems with a sane power controller which can behave correctly with
  respect to CPU power domain, the CPU power domain can be controlled by
  register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ
  to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation
  of CPU power down. As result, this can ensure the CPU power domain is
  powered on properly during the period when access debug related registers;

- Some designs will power down an entire cluster if all CPUs on the cluster
  are powered down - including the parts of the debug registers that should
  remain powered in the debug power domain. The bits in EDPRCR are not
  respected in these cases, so these designs do not support debug over
  power down in the way that the CoreSight / Debug designers anticipated.
  This means that even checking EDPRSR has the potential to cause a bus hang
  if the target register is unpowered.

  In this case, accessing to the debug registers while they are not powered
  is a recipe for disaster; so we need preventing CPU low power states at boot
  time or when user enable module at the run time. Please see chapter
  "How to use the module" for detailed usage info for this.

Device Tree Bindings
--------------------

See Documentation/devicetree/bindings/arm/arm,coresight-cpu-debug.yaml for
details.

How to use the module
---------------------

If you want to enable debugging functionality at boot time, you can add
"coresight_cpu_debug.enable=1" to the kernel command line parameter.

The driver also can work as module, so can enable the debugging when insmod
module::

  # insmod coresight_cpu_debug.ko debug=1

When boot time or insmod module you have not enabled the debugging, the driver
uses the debugfs file system to provide a knob to dynamically enable or disable
debugging:

To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::

  # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable

To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::

  # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one
platform which has idle states to power off debug logic and the power
controller cannot work well for the request from EDPRCR, then you should
firstly constraint CPU idle states before enable CPU debugging feature; so can
ensure the accessing to debug logic.

If you want to limit idle states at boot time, you can use "nohlt" or
"cpuidle.off=1" in the kernel command line.

At the runtime you can disable idle states with below methods:

It is possible to disable CPU idle states by way of the PM QoS
subsystem, more specifically by using the "/dev/cpu_dma_latency"
interface (see Documentation/power/pm_qos_interface.rst for more
details).  As specified in the PM QoS documentation the requested
parameter will stay in effect until the file descriptor is released.
For example::

  # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
  ...
  Do some work...
  ...
  # exec 3<>-

The same can also be done from an application program.

Disable specific CPU's specific idle state from cpuidle sysfs (see
Documentation/admin-guide/pm/cpuidle.rst)::

  # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable

Output format
-------------

Here is an example of the debugging output format::

  ARM external debug module:
  coresight-cpu-debug 850000.debug: CPU[0]:
  coresight-cpu-debug 850000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
  coresight-cpu-debug 850000.debug:  EDPCSR:  handle_IPI+0x174/0x1d8
  coresight-cpu-debug 850000.debug:  EDCIDSR: 00000000
  coresight-cpu-debug 850000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
  coresight-cpu-debug 852000.debug: CPU[1]:
  coresight-cpu-debug 852000.debug:  EDPRSR:  00000001 (Power:On DLK:Unlock)
  coresight-cpu-debug 852000.debug:  EDPCSR:  debug_notifier_call+0x23c/0x358
  coresight-cpu-debug 852000.debug:  EDCIDSR: 00000000
  coresight-cpu-debug 852000.debug:  EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)


code:
.. SPDX-License-Identifier: GPL-2.0

=============================================
CoreSight Embedded Cross Trigger (CTI & CTM).
=============================================

    :Author:   Mike Leach <mike.leach@linaro.org>
    :Date:     November 2019

Hardware Description
--------------------

The CoreSight Cross Trigger Interface (CTI) is a hardware device that takes
individual input and output hardware signals known as triggers to and from
devices and interconnects them via the Cross Trigger Matrix (CTM) to other
devices via numbered channels, in order to propagate events between devices.

e.g.::

 0000000  in_trigs  :::::::
 0 C   0----------->:     :             +======>(other CTI channel IO)
 0  P  0<-----------:     :             v
 0   U 0  out_trigs :     : Channels  *****      :::::::
 0000000            : CTI :<=========>*CTM*<====>: CTI :---+
 #######  in_trigs  :     : (id 0-3)  *****      :::::::   v
 # ETM #----------->:     :                         ^   #######
 #     #<-----------:     :                         +---# ETR #
 ####### out_trigs  :::::::                             #######

The CTI driver enables the programming of the CTI to attach triggers to
channels. When an input trigger becomes active, the attached channel will
become active. Any output trigger attached to that channel will also
become active. The active channel is propagated to other CTIs via the CTM,
activating connected output triggers there, unless filtered by the CTI
channel gate.

It is also possible to activate a channel using system software directly
programming registers in the CTI.

The CTIs are registered by the system to be associated with CPUs and/or other
CoreSight devices on the trace data path. When these devices are enabled the
attached CTIs will also be enabled. By default/on power up the CTIs have
no programmed trigger/channel attachments, so will not affect the system
until explicitly programmed.

The hardware trigger connections between CTIs and devices is implementation
defined, unless the CPU/ETM combination is a v8 architecture, in which case
the connections have an architecturally defined standard layout.

The hardware trigger signals can also be connected to non-CoreSight devices
(e.g. UART), or be propagated off chip as hardware IO lines.

All the CTI devices are associated with a CTM. On many systems there will be a
single effective CTM (one CTM, or multiple CTMs all interconnected), but it is
possible that systems can have nets of CTIs+CTM that are not interconnected by
a CTM to each other. On these systems a CTM index is declared to associate
CTI devices that are interconnected via a given CTM.

Sysfs files and directories
---------------------------

The CTI devices appear on the existing CoreSight bus alongside the other
CoreSight devices::

    >$ ls /sys/bus/coresight/devices
     cti_cpu0  cti_cpu2  cti_sys0  etm0  etm2  funnel0  replicator0  tmc_etr0
     cti_cpu1  cti_cpu3  cti_sys1  etm1  etm3  funnel1  tmc_etf0     tpiu0

The ``cti_cpu<N>`` named CTIs are associated with a CPU, and any ETM used by
that core. The ``cti_sys<N>`` CTIs are general system infrastructure CTIs that
can be associated with other CoreSight devices, or other system hardware
capable of generating or using trigger signals.::

  >$ ls /sys/bus/coresight/devices/etm0/cti_cpu0
  channels  ctmid  enable  nr_trigger_cons mgmt  power powered  regs
  connections subsystem triggers0 triggers1  uevent

*Key file items are:-*
   * ``enable``: enables/disables the CTI. Read to determine current state.
     If this shows as enabled (1), but ``powered`` shows unpowered (0), then
     the enable indicates a request to enabled when the device is powered.
   * ``ctmid`` : associated CTM - only relevant if system has multiple CTI+CTM
     clusters that are not interconnected.
   * ``nr_trigger_cons`` : total connections - triggers<N> directories.
   * ``powered`` : Read to determine if the CTI is currently powered.

*Sub-directories:-*
   * ``triggers<N>``: contains list of triggers for an individual connection.
   * ``channels``: Contains the channel API - CTI main programming interface.
   * ``regs``: Gives access to the raw programmable CTI regs.
   * ``mgmt``: the standard CoreSight management registers.
   * ``connections``: Links to connected *CoreSight* devices. The number of
     links can be 0 to ``nr_trigger_cons``. Actual number given by ``nr_links``
     in this directory.

triggers<N> directories
~~~~~~~~~~~~~~~~~~~~~~~

Individual trigger connection information. This describes trigger signals for
CoreSight and non-CoreSight connections.

Each triggers directory has a set of parameters describing the triggers for
the connection.

   * ``name`` : name of connection
   * ``in_signals`` : input trigger signal indexes used in this connection.
   * ``in_types`` : functional types for in signals.
   * ``out_signals`` : output trigger signals for this connection.
   * ``out_types`` : functional types for out signals.

e.g::

    >$ ls ./cti_cpu0/triggers0/
    in_signals  in_types  name  out_signals  out_types
    >$ cat ./cti_cpu0/triggers0/name
    cpu0
    >$ cat ./cti_cpu0/triggers0/out_signals
    0-2
    >$ cat ./cti_cpu0/triggers0/out_types
    pe_edbgreq pe_dbgrestart pe_ctiirq
    >$ cat ./cti_cpu0/triggers0/in_signals
    0-1
    >$ cat ./cti_cpu0/triggers0/in_types
    pe_dbgtrigger pe_pmuirq

If a connection has zero signals in either the 'in' or 'out' triggers then
those parameters will be omitted.

Channels API Directory
~~~~~~~~~~~~~~~~~~~~~~

This provides an easy way to attach triggers to channels, without needing
the multiple register operations that are required if manipulating the
'regs' sub-directory elements directly.

A number of files provide this API::

   >$ ls ./cti_sys0/channels/
   chan_clear         chan_inuse      chan_xtrigs_out     trigin_attach
   chan_free          chan_pulse      chan_xtrigs_reset   trigin_detach
   chan_gate_disable  chan_set        chan_xtrigs_sel     trigout_attach
   chan_gate_enable   chan_xtrigs_in  trig_filter_enable  trigout_detach
   trigout_filtered

Most access to these elements take the form::

  echo <chan> [<trigger>] > /<device_path>/<operation>

where the optional <trigger> is only needed for trigXX_attach | detach
operations.

e.g.::

   >$ echo 0 1 > ./cti_sys0/channels/trigout_attach
   >$ echo 0 > ./cti_sys0/channels/chan_set

Attaches trigout(1) to channel(0), then activates channel(0) generating a
set state on cti_sys0.trigout(1)

*API operations*

   * ``trigin_attach, trigout_attach``: Attach a channel to a trigger signal.
   * ``trigin_detach, trigout_detach``: Detach a channel from a trigger signal.
   * ``chan_set``: Set the channel - the set state will be propagated around
     the CTM to other connected devices.
   * ``chan_clear``: Clear the channel.
   * ``chan_pulse``: Set the channel for a single CoreSight clock cycle.
   * ``chan_gate_enable``: Write operation sets the CTI gate to propagate
     (enable) the channel to other devices. This operation takes a channel
     number. CTI gate is enabled for all channels by default at power up. Read
     to list the currently enabled channels on the gate.
   * ``chan_gate_disable``: Write channel number to disable gate for that
     channel.
   * ``chan_inuse``: Show the current channels attached to any signal
   * ``chan_free``: Show channels with no attached signals.
   * ``chan_xtrigs_sel``: write a channel number to select a channel to view,
     read to show the selected channel number.
   * ``chan_xtrigs_in``: Read to show the input triggers attached to
     the selected view channel.
   * ``chan_xtrigs_out``:Read to show the output triggers attached to
     the selected view channel.
   * ``trig_filter_enable``: Defaults to enabled, disable to allow potentially
     dangerous output signals to be set.
   * ``trigout_filtered``: Trigger out signals that are prevented from being
     set if filtering ``trig_filter_enable`` is enabled. One use is to prevent
     accidental ``EDBGREQ`` signals stopping a core.
   * ``chan_xtrigs_reset``: Write 1 to clear all channel / trigger programming.
     Resets device hardware to default state.

The example below attaches input trigger index 1 to channel 2, and output
trigger index 6 to the same channel. It then examines the state of the
channel / trigger connections using the appropriate sysfs attributes.

The settings mean that if either input trigger 1, or channel 2 go active then
trigger out 6 will go active. We then enable the CTI, and use the software
channel control to activate channel 2. We see the active channel on the
``choutstatus`` register and the active signal on the ``trigoutstatus``
register. Finally clearing the channel removes this.

e.g.::

   .../cti_sys0/channels# echo 2 1 > trigin_attach
   .../cti_sys0/channels# echo 2 6 > trigout_attach
   .../cti_sys0/channels# cat chan_free
   0-1,3
   .../cti_sys0/channels# cat chan_inuse
   2
   .../cti_sys0/channels# echo 2 > chan_xtrigs_sel
   .../cti_sys0/channels# cat chan_xtrigs_trigin
   1
   .../cti_sys0/channels# cat chan_xtrigs_trigout
   6
   .../cti_sys0/# echo 1 > enable
   .../cti_sys0/channels# echo 2 > chan_set
   .../cti_sys0/channels# cat ../regs/choutstatus
   0x4
   .../cti_sys0/channels# cat ../regs/trigoutstatus
   0x40
   .../cti_sys0/channels# echo 2 > chan_clear
   .../cti_sys0/channels# cat ../regs/trigoutstatus
   0x0
   .../cti_sys0/channels# cat ../regs/choutstatus
   0x0


code:
===============================================
ETMv4 sysfs linux driver programming reference.
===============================================

    :Author:   Mike Leach <mike.leach@linaro.org>
    :Date:     October 11th, 2019

Supplement to existing ETMv4 driver documentation.

Sysfs files and directories
---------------------------

Root: ``/sys/bus/coresight/devices/etm<N>``

The following paragraphs explain the association between sysfs files and the
ETMv4 registers that they effect. Note the register names are given without
the ‘TRC’ prefix.

----

:File:            ``mode`` (rw)
:Trace Registers: {CONFIGR + others}
:Notes:
    Bit select trace features. See ‘mode’ section below. Bits
    in this will cause equivalent programming of trace config and
    other registers to enable the features requested.

:Syntax & eg:
    ``echo bitfield > mode``

    bitfield up to 32 bits setting trace features.

:Example:
    ``$> echo 0x012 > mode``

----

:File:            ``reset`` (wo)
:Trace Registers: All
:Notes:
    Reset all programming to trace nothing / no logic programmed.

:Syntax:
    ``echo 1 > reset``

----

:File:            ``enable_source`` (wo)
:Trace Registers: PRGCTLR, All hardware regs.
:Notes:
    - > 0 : Programs up the hardware with the current values held in the driver
      and enables trace.

    - = 0 : disable trace hardware.

:Syntax:
    ``echo 1 > enable_source``

----

:File:            ``cpu`` (ro)
:Trace Registers: None.
:Notes:
    CPU ID that this ETM is attached to.

:Example:
    ``$> cat cpu``

    ``$> 0``

----

:File:            ``ts_source`` (ro)
:Trace Registers: None.
:Notes:
    When FEAT_TRF is implemented, value of TRFCR_ELx.TS used for trace session. Otherwise -1
    indicates an unknown time source. Check trcidr0.tssize to see if a global timestamp is
    available.

:Example:
    ``$> cat ts_source``

    ``$> 1``

----

:File:            ``addr_idx`` (rw)
:Trace Registers: None.
:Notes:
    Virtual register to index address comparator and range
    features. Set index for first of the pair in a range.

:Syntax:
    ``echo idx > addr_idx``

    Where idx < nr_addr_cmp x 2

----

:File:            ``addr_range`` (rw)
:Trace Registers: ACVR[idx, idx+1], VIIECTLR
:Notes:
    Pair of addresses for a range selected by addr_idx. Include
    / exclude according to the optional parameter, or if omitted
    uses the current ‘mode’ setting. Select comparator range in
    control register. Error if index is odd value.

:Depends: ``mode, addr_idx``
:Syntax:
   ``echo addr1 addr2 [exclude] > addr_range``

   Where addr1 and addr2 define the range and addr1 < addr2.

   Optional exclude value:-

   - 0 for include
   - 1 for exclude.
:Example:
   ``$> echo 0x0000 0x2000 0 > addr_range``

----

:File:            ``addr_single`` (rw)
:Trace Registers: ACVR[idx]
:Notes:
    Set a single address comparator according to addr_idx. This
    is used if the address comparator is used as part of event
    generation logic etc.

:Depends: ``addr_idx``
:Syntax:
   ``echo addr1 > addr_single``

----

:File:           ``addr_start`` (rw)
:Trace Registers: ACVR[idx], VISSCTLR
:Notes:
    Set a trace start address comparator according to addr_idx.
    Select comparator in control register.

:Depends: ``addr_idx``
:Syntax:
    ``echo addr1 > addr_start``

----

:File:            ``addr_stop`` (rw)
:Trace Registers: ACVR[idx], VISSCTLR
:Notes:
    Set a trace stop address comparator according to addr_idx.
    Select comparator in control register.

:Depends: ``addr_idx``
:Syntax:
    ``echo addr1 > addr_stop``

----

:File:            ``addr_context`` (rw)
:Trace Registers: ACATR[idx,{6:4}]
:Notes:
    Link context ID comparator to address comparator addr_idx

:Depends: ``addr_idx``
:Syntax:
    ``echo ctxt_idx > addr_context``

    Where ctxt_idx is the index of the linked context id / vmid
    comparator.

----

:File:            ``addr_ctxtype`` (rw)
:Trace Registers: ACATR[idx,{3:2}]
:Notes:
    Input value string. Set type for linked context ID comparator

:Depends: ``addr_idx``
:Syntax:
    ``echo type > addr_ctxtype``

    Type one of {all, vmid, ctxid, none}
:Example:
    ``$> echo ctxid > addr_ctxtype``

----

:File:            ``addr_exlevel_s_ns`` (rw)
:Trace Registers: ACATR[idx,{14:8}]
:Notes:
    Set the ELx secure and non-secure matching bits for the
    selected address comparator

:Depends: ``addr_idx``
:Syntax:
    ``echo val > addr_exlevel_s_ns``

    val is a 7 bit value for exception levels to exclude. Input
    value shifted to correct bits in register.
:Example:
    ``$> echo 0x4F > addr_exlevel_s_ns``

----

:File:            ``addr_instdatatype`` (rw)
:Trace Registers: ACATR[idx,{1:0}]
:Notes:
    Set the comparator address type for matching. Driver only
    supports setting instruction address type.

:Depends: ``addr_idx``

----

:File:            ``addr_cmp_view`` (ro)
:Trace Registers: ACVR[idx, idx+1], ACATR[idx], VIIECTLR
:Notes:
    Read the currently selected address comparator. If part of
    address range then display both addresses.

:Depends: ``addr_idx``
:Syntax:
    ``cat addr_cmp_view``
:Example:
    ``$> cat addr_cmp_view``

   ``addr_cmp[0] range 0x0 0xffffffffffffffff include ctrl(0x4b00)``

----

:File:            ``nr_addr_cmp`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of address comparator pairs

----

:File:            ``sshot_idx`` (rw)
:Trace Registers: None
:Notes:
    Select single shot register set.

----

:File:            ``sshot_ctrl`` (rw)
:Trace Registers: SSCCR[idx]
:Notes:
    Access a single shot comparator control register.

:Depends: ``sshot_idx``
:Syntax:
    ``echo val > sshot_ctrl``

    Writes val into the selected control register.

----

:File:            ``sshot_status`` (ro)
:Trace Registers: SSCSR[idx]
:Notes:
    Read a single shot comparator status register

:Depends: ``sshot_idx``
:Syntax:
    ``cat sshot_status``

    Read status.
:Example:
    ``$> cat sshot_status``

    ``0x1``

----

:File:            ``sshot_pe_ctrl`` (rw)
:Trace Registers: SSPCICR[idx]
:Notes:
    Access a single shot PE comparator input control register.

:Depends: ``sshot_idx``
:Syntax:
    ``echo val > sshot_pe_ctrl``

    Writes val into the selected control register.

----

:File:            ``ns_exlevel_vinst`` (rw)
:Trace Registers: VICTLR{23:20}
:Notes:
    Program non-secure exception level filters. Set / clear NS
    exception filter bits. Setting ‘1’ excludes trace from the
    exception level.

:Syntax:
    ``echo bitfield > ns_exlevel_viinst``

    Where bitfield contains bits to set clear for EL0 to EL2
:Example:
    ``%> echo 0x4 > ns_exlevel_viinst``

    Excludes EL2 NS trace.

----

:File:            ``vinst_pe_cmp_start_stop`` (rw)
:Trace Registers: VIPCSSCTLR
:Notes:
    Access PE start stop comparator input control registers

----

:File:            ``bb_ctrl`` (rw)
:Trace Registers: BBCTLR
:Notes:
    Define ranges that Branch Broadcast will operate in.
    Default (0x0) is all addresses.

:Depends: BB enabled.

----

:File:            ``cyc_threshold`` (rw)
:Trace Registers: CCCTLR
:Notes:
    Set the threshold for which cycle counts will be emitted.
    Error if attempt to set below minimum defined in IDR3, masked
    to width of valid bits.

:Depends: CC enabled.

----

:File:            ``syncfreq`` (rw)
:Trace Registers: SYNCPR
:Notes:
    Set trace synchronisation period. Power of 2 value, 0 (off)
    or 8-20. Driver defaults to 12 (every 4096 bytes).

----

:File:            ``cntr_idx`` (rw)
:Trace Registers: none
:Notes:
    Select the counter to access

:Syntax:
    ``echo idx > cntr_idx``

    Where idx < nr_cntr

----

:File:            ``cntr_ctrl`` (rw)
:Trace Registers: CNTCTLR[idx]
:Notes:
    Set counter control value.

:Depends: ``cntr_idx``
:Syntax:
    ``echo val > cntr_ctrl``

    Where val is per ETMv4 spec.

----

:File:            ``cntrldvr`` (rw)
:Trace Registers: CNTRLDVR[idx]
:Notes:
    Set counter reload value.

:Depends: ``cntr_idx``
:Syntax:
    ``echo val > cntrldvr``

    Where val is per ETMv4 spec.

----

:File:            ``nr_cntr`` (ro)
:Trace Registers: From IDR5

:Notes:
    Number of counters implemented.

----

:File:            ``ctxid_idx`` (rw)
:Trace Registers: None
:Notes:
    Select the context ID comparator to access

:Syntax:
    ``echo idx > ctxid_idx``

    Where idx < numcidc

----

:File:            ``ctxid_pid`` (rw)
:Trace Registers: CIDCVR[idx]
:Notes:
   Set the context ID comparator value

:Depends: ``ctxid_idx``

----

:File: ``ctxid_masks`` (rw)
:Trace Registers: CIDCCTLR0, CIDCCTLR1, CIDCVR<0-7>
:Notes:
    Pair of values to set the byte masks for 1-8 context ID
    comparators. Automatically clears masked bytes to 0 in CID
    value registers.

:Syntax:
    ``echo m3m2m1m0 [m7m6m5m4] > ctxid_masks``

    32 bit values made up of mask bytes, where mN represents a
    byte mask value for Context ID comparator N.

    Second value not required on systems that have fewer than 4
    context ID comparators

----

:File:            ``numcidc`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of Context ID comparators

----

:File:            ``vmid_idx`` (rw)
:Trace Registers: None
:Notes:
    Select the VM ID comparator to access.

:Syntax:
    ``echo idx > vmid_idx``

    Where idx <  numvmidc

----

:File:            ``vmid_val`` (rw)
:Trace Registers: VMIDCVR[idx]
:Notes:
    Set the VM ID comparator value

:Depends: ``vmid_idx``

----

:File:            ``vmid_masks`` (rw)
:Trace Registers: VMIDCCTLR0, VMIDCCTLR1, VMIDCVR<0-7>
:Notes:
    Pair of values to set the byte masks for 1-8 VM ID comparators.
    Automatically clears masked bytes to 0 in VMID value registers.

:Syntax:
    ``echo m3m2m1m0 [m7m6m5m4] > vmid_masks``

    Where mN represents a byte mask value for VMID comparator N.
    Second value not required on systems that have fewer than 4
    VMID comparators.

----

:File:            ``numvmidc`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of VMID comparators

----

:File:            ``res_idx`` (rw)
:Trace Registers: None.
:Notes:
    Select the resource selector control to access. Must be 2 or
    higher as selectors 0 and 1 are hardwired.

:Syntax:
    ``echo idx > res_idx``

    Where 2 <= idx < nr_resource x 2

----

:File:            ``res_ctrl`` (rw)
:Trace Registers: RSCTLR[idx]
:Notes:
    Set resource selector control value. Value per ETMv4 spec.

:Depends: ``res_idx``
:Syntax:
    ``echo val > res_cntr``

    Where val is per ETMv4 spec.

----

:File:            ``nr_resource`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of resource selector pairs

----

:File:            ``event`` (rw)
:Trace Registers: EVENTCTRL0R
:Notes:
    Set up to 4 implemented event fields.

:Syntax:
    ``echo ev3ev2ev1ev0 > event``

    Where evN is an 8 bit event field. Up to 4 event fields make up the
    32-bit input value. Number of valid fields is implementation dependent,
    defined in IDR0.

----

:File: ``event_instren`` (rw)
:Trace Registers: EVENTCTRL1R
:Notes:
    Choose events which insert event packets into trace stream.

:Depends: EVENTCTRL0R
:Syntax:
    ``echo bitfield > event_instren``

    Where bitfield is up to 4 bits according to number of event fields.

----

:File:            ``event_ts`` (rw)
:Trace Registers: TSCTLR
:Notes:
    Set the event that will generate timestamp requests.

:Depends: ``TS activated``
:Syntax:
    ``echo evfield > event_ts``

    Where evfield is an 8 bit event selector.

----

:File:            ``seq_idx`` (rw)
:Trace Registers: None
:Notes:
    Sequencer event register select - 0 to 2

----

:File:            ``seq_state`` (rw)
:Trace Registers: SEQSTR
:Notes:
    Sequencer current state - 0 to 3.

----

:File:            ``seq_event`` (rw)
:Trace Registers: SEQEVR[idx]
:Notes:
    State transition event registers

:Depends: ``seq_idx``
:Syntax:
    ``echo evBevF > seq_event``

    Where evBevF is a 16 bit value made up of two event selectors,

    - evB : back
    - evF : forwards.

----

:File:            ``seq_reset_event`` (rw)
:Trace Registers: SEQRSTEVR
:Notes:
    Sequencer reset event

:Syntax:
    ``echo evfield > seq_reset_event``

    Where evfield is an 8 bit event selector.

----

:File:            ``nrseqstate`` (ro)
:Trace Registers: From IDR5
:Notes:
    Number of sequencer states (0 or 4)

----

:File:            ``nr_pe_cmp`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of PE comparator inputs

----

:File:            ``nr_ext_inp`` (ro)
:Trace Registers: From IDR5
:Notes:
    Number of external inputs

----

:File:            ``nr_ss_cmp`` (ro)
:Trace Registers: From IDR4
:Notes:
    Number of Single Shot control registers

----

*Note:* When programming any address comparator the driver will tag the
comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag
is set, then only the values can be changed using the same sysfs file / type
used to program it.

Thus::

  % echo 0 > addr_idx		; select address comparator 0
  % echo 0x1000 0x5000 0 > addr_range ; set address range on comparators 0, 1.
  % echo 0x2000 > addr_start    ; error as comparator 0 is a range comparator
  % echo 2 > addr_idx		; select address comparator 2
  % echo 0x2000 > addr_start	; this is OK as comparator 2 is unused.
  % echo 0x3000 > addr_stop	; error as comparator 2 set as start address.
  % echo 2 > addr_idx		; select address comparator 3
  % echo 0x3000 > addr_stop	; this is OK

To remove programming on all the comparators (and all the other hardware) use
the reset parameter::

  % echo 1 > reset

The ‘mode’ sysfs parameter.
---------------------------

This is a bitfield selection parameter that sets the overall trace mode for the
ETM. The table below describes the bits, using the defines from the driver
source file, along with a description of the feature these represent. Many
features are optional and therefore dependent on implementation in the
hardware.

Bit assignments shown below:-

----

**bit (0):**
    ETM_MODE_EXCLUDE

**description:**
    This is the default value for the include / exclude function when
    setting address ranges. Set 1 for exclude range. When the mode
    parameter is set this value is applied to the currently indexed
    address range.

.. _coresight-branch-broadcast:

**bit (4):**
    ETM_MODE_BB

**description:**
    Set to enable branch broadcast if supported in hardware [IDR0]. The primary use for this feature
    is when code is patched dynamically at run time and the full program flow may not be able to be
    reconstructed using only conditional branches.

    There is currently no support in Perf for supplying modified binaries to the decoder, so this
    feature is only inteded to be used for debugging purposes or with a 3rd party tool.

    Choosing this option will result in a significant increase in the amount of trace generated -
    possible danger of overflows, or fewer instructions covered. Note, that this option also
    overrides any setting of :ref:`ETM_MODE_RETURNSTACK <coresight-return-stack>`, so where a branch
    broadcast range overlaps a return stack range, return stacks will not be available for that
    range.

.. _coresight-cycle-accurate:

**bit (5):**
    ETMv4_MODE_CYCACC

**description:**
    Set to enable cycle accurate trace if supported [IDR0].

**bit (6):**
    ETMv4_MODE_CTXID

**description:**
    Set to enable context ID tracing if supported in hardware [IDR2].

**bit (7):**
    ETM_MODE_VMID

**description:**
    Set to enable virtual machine ID tracing if supported [IDR2].

.. _coresight-timestamp:

**bit (11):**
    ETMv4_MODE_TIMESTAMP

**description:**
    Set to enable timestamp generation if supported [IDR0].

.. _coresight-return-stack:

**bit (12):**
    ETM_MODE_RETURNSTACK
**description:**
    Set to enable trace return stack use if supported [IDR0].

**bit (13-14):**
    ETM_MODE_QELEM(val)

**description:**
    ‘val’ determines level of Q element support enabled if
    implemented by the ETM [IDR0]

**bit (19):**
    ETM_MODE_ATB_TRIGGER

**description:**
    Set to enable the ATBTRIGGER bit in the event control register
    [EVENTCTLR1] if supported [IDR5].

**bit (20):**
    ETM_MODE_LPOVERRIDE

**description:**
    Set to enable the LPOVERRIDE bit in the event control register
    [EVENTCTLR1], if supported [IDR5].

**bit (21):**
    ETM_MODE_ISTALL_EN

**description:**
    Set to enable the ISTALL bit in the stall control register
    [STALLCTLR]

**bit (23):**
    ETM_MODE_INSTPRIO

**description:**
	      Set to enable the INSTPRIORITY bit in the stall control register
	      [STALLCTLR] , if supported [IDR0].

**bit (24):**
    ETM_MODE_NOOVERFLOW

**description:**
    Set to enable the NOOVERFLOW bit in the stall control register
    [STALLCTLR], if supported [IDR3].

**bit (25):**
    ETM_MODE_TRACE_RESET

**description:**
    Set to enable the TRCRESET bit in the viewinst control register
    [VICTLR] , if supported [IDR3].

**bit (26):**
    ETM_MODE_TRACE_ERR

**description:**
    Set to enable the TRCCTRL bit in the viewinst control register
    [VICTLR].

**bit (27):**
    ETM_MODE_VIEWINST_STARTSTOP

**description:**
    Set the initial state value of the ViewInst start / stop logic
    in the viewinst control register [VICTLR]

**bit (30):**
    ETM_MODE_EXCL_KERN

**description:**
    Set default trace setup to exclude kernel mode trace (see note a)

**bit (31):**
    ETM_MODE_EXCL_USER

**description:**
    Set default trace setup to exclude user space trace (see note a)

----

*Note a)* On startup the ETM is programmed to trace the complete address space
using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to
set EL exclude bits for NS state in either user space (EL0) or kernel space
(EL1) in the address range comparator. (the default setting excludes all
secure EL, and NS EL2)

Once the reset parameter has been used, and/or custom programming has been
implemented - using these bits will result in the EL bits for address
comparator 0 being set in the same way.

*Note b)* Bits 2-3, 8-10, 15-16, 18, 22, control features that only work with
data trace. As A-profile data trace is architecturally prohibited in ETMv4,
these have been omitted here. Possible uses could be where a kernel has
support for control of R or M profile infrastructure as part of a heterogeneous
system.

Bits 17, 28-29 are unused.


code:
.. SPDX-License-Identifier: GPL-2.0

================
CoreSight - Perf
================

    :Author:   Carsten Haitzler <carsten.haitzler@arm.com>
    :Date:     June 29th, 2022

Perf is able to locally access CoreSight trace data and store it to the
output perf data files. This data can then be later decoded to give the
instructions that were traced for debugging or profiling purposes. You
can log such data with a perf record command like::

   perf record -e cs_etm//u testbinary

This would run some test binary (testbinary) until it exits and record
a perf.data trace file. That file would have AUX sections if CoreSight
is working correctly. You can dump the content of this file as
readable text with a command like::

   perf report --stdio --dump -i perf.data

You should find some sections of this file have AUX data blocks like::

   0x1e78 [0x30]: PERF_RECORD_AUXTRACE size: 0x11dd0  offset: 0  ref: 0x1b614fc1061b0ad1  idx: 0  tid: 531230  cpu: -1

   . ... CoreSight ETM Trace data: size 73168 bytes
           Idx:0; ID:10;   I_ASYNC : Alignment Synchronisation.
             Idx:12; ID:10;  I_TRACE_INFO : Trace Info.; INFO=0x0 { CC.0 }
             Idx:17; ID:10;  I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0x0000000000000000;
             Idx:26; ID:10;  I_TRACE_ON : Trace On.
             Idx:27; ID:10;  I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0x0000FFFFB6069140; Ctxt: AArch64,EL0, NS;
             Idx:38; ID:10;  I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
             Idx:39; ID:10;  I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
             Idx:40; ID:10;  I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEEEEEEEEEEEEEE
             Idx:41; ID:10;  I_ATOM_F6 : Atom format 6.; EEEEEEEEEEEN
             ...

If you see these above, then your system is tracing CoreSight data
correctly.

To compile perf with CoreSight support in the tools/perf directory do::

    make CORESIGHT=1

This requires OpenCSD to build. You may install distribution packages
for the support such as libopencsd and libopencsd-dev or download it
and build yourself. Upstream OpenCSD is located at:

  https://github.com/Linaro/OpenCSD

For complete information on building perf with CoreSight support and
more extensive usage look at:

  https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md

Kernel CoreSight Support
------------------------

You will also want CoreSight support enabled in your kernel config.
Ensure it is enabled with::

   CONFIG_CORESIGHT=y

There are various other CoreSight options you probably also want
enabled like::

   CONFIG_CORESIGHT_LINKS_AND_SINKS=y
   CONFIG_CORESIGHT_LINK_AND_SINK_TMC=y
   CONFIG_CORESIGHT_CATU=y
   CONFIG_CORESIGHT_SINK_TPIU=y
   CONFIG_CORESIGHT_SINK_ETBV10=y
   CONFIG_CORESIGHT_SOURCE_ETM4X=y
   CONFIG_CORESIGHT_CTI=y
   CONFIG_CORESIGHT_CTI_INTEGRATION_REGS=y

Please refer to the kernel configuration help for more information.

Perf test - Verify kernel and userspace perf CoreSight work
-----------------------------------------------------------

When you run perf test, it will do a lot of self tests. Some of those
tests will cover CoreSight (only if enabled and on ARM64). You
generally would run perf test from the tools/perf directory in the
kernel tree. Some tests will check some internal perf support like:

   Check Arm CoreSight trace data recording and synthesized samples
   Check Arm SPE trace data recording and synthesized samples

Some others will actually use perf record and some test binaries that
are in tests/shell/coresight and will collect traces to ensure a
minimum level of functionality is met. The scripts that launch these
tests are in the same directory. These will all look like:

   CoreSight / ASM Pure Loop
   CoreSight / Memcpy 16k 10 Threads
   CoreSight / Thread Loop 10 Threads - Check TID
   etc.

These perf record tests will not run if the tool binaries do not exist
in tests/shell/coresight/\*/ and will be skipped. If you do not have
CoreSight support in hardware then either do not build perf with
CoreSight support or remove these binaries in order to not have these
tests fail and have them skip instead.

These tests will log historical results in the current working
directory (e.g. tools/perf) and will be named stats-\*.csv like:

   stats-asm_pure_loop-out.csv
   stats-memcpy_thread-16k_10.csv
   ...

These statistic files log some aspects of the AUX data sections in
the perf data output counting some numbers of certain encodings (a
good way to know that it's working in a very simple way). One problem
with CoreSight is that given a large enough amount of data needing to
be logged, some of it can be lost due to the processor not waking up
in time to read out all the data from buffers etc.. You will notice
that the amount of data collected can vary a lot per run of perf test.
If you wish to see how this changes over time, simply run perf test
multiple times and all these csv files will have more and more data
appended to it that you can later examine, graph and otherwise use to
figure out if things have become worse or better.

This means sometimes these tests fail as they don't capture all the
data needed. This is about tracking quality and amount of data
produced over time and to see when changes to the Linux kernel improve
quality of traces.

Be aware that some of these tests take quite a while to run, specifically
in processing the perf data file and dumping contents to then examine what
is inside.

You can change where these csv logs are stored by setting the
PERF_TEST_CORESIGHT_STATDIR environment variable before running perf
test like::

   export PERF_TEST_CORESIGHT_STATDIR=/var/tmp
   perf test

They will also store resulting perf output data in the current
directory for later inspection like::

   perf-asm_pure_loop-out.data
   perf-memcpy_thread-16k_10.data
   ...

You can alter where the perf data files are stored by setting the
PERF_TEST_CORESIGHT_DATADIR environment variable such as::

   PERF_TEST_CORESIGHT_DATADIR=/var/tmp
   perf test

You may wish to set these above environment variables if you wish to
keep the output of tests outside of the current working directory for
longer term storage and examination.