RTLA 공통 command-line option

CPU, duration과 debug

`-c` 또는 `--cpus cpu-list`는 osnoise tracer sample thread를 지정한 CPU 목록에서 실행한다. `-H` 또는 `--house-keeping cpu-list`는 RTLA control thread만 지정 CPU 목록에서 실행한다.

`-d` 또는 `--duration time[s|m|h|d]`는 session 지속 시간을 정한다. `-D` 또는 `--debug`는 debug 정보를 출력한다.

**-c**, **--cpus** *cpu-list*

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

**-H**, **--house-keeping** *cpu-list*

        Run rtla control threads only on the given cpu-list.

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

        Set the duration of the session.

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

        Print debug info.

Trace event, filter와 trigger

`-e` 또는 `--event sys:event`는 `-t` trace session에서 event를 활성화한다. `sched:sched_switch`처럼 특정 event를 지정하거나 `sched`처럼 system group 전체를 지정할 수 있고 option을 여러 번 쓸 수 있다. `-t` 또는 `-a`가 설정된 경우에만 활성화된다.

`--filter <filter>`는 바로 앞의 `-e sys:event`에 filter를 적용한다. 자세한 문법은 kernel event filtering 문서를 따른다.

`--trigger <trigger>`는 바로 앞 event에 trace event trigger를 건다. `hist:` trigger를 활성화하면 histogram이 `system_event_hist.txt` 형식의 파일에 자동 저장된다. 예제의 `osnoise:irq_noise` histogram은 `osnoise_irq_noise_hist.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.

Scheduling, cgroup과 warm-up

`-P` 또는 `--priority`는 tracer thread scheduling을 설정한다. `o:prio`, `r:prio`, `f:prio`는 각각 `SCHED_OTHER`, `SCHED_RR`, `SCHED_FIFO`를 사용하고, `d:runtime:period`는 단위가 붙은 runtime과 period로 `SCHED_DEADLINE`을 사용한다.

`-C` 또는 `--cgroup [cgroup]`은 tracer thread의 cgroup을 정한다. argument가 없으면 RTLA process의 cgroup을 상속하고, argument가 있으면 지정 cgroup에 thread를 배치한다.

`--warm-up s`는 workload 시작 뒤 s초 동안 system을 예열하고 그 사이의 통계를 버린다. `--trace-buffer-size kB`는 tracing 출력용 per-CPU trace buffer 크기를 kB 단위로 설정한다.

**-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.

**-C**, **--cgroup** \[*cgroup*]

        Set a *cgroup* to the tracer's threads. If the **-C** option is passed without arguments, the tracer's thread will inherit **rtla**'s *cgroup*. Otherwise, the threads will be placed on the *cgroup* passed to the option.

**--warm-up** *s*

        After starting the workload, let it run for *s* seconds before starting collecting the data, allowing the system to warm-up. Statistical data generated during warm-up is discarded.

**--trace-buffer-size** *kB*
        Set the per-cpu trace buffer size in kB for the tracing output.

Threshold 도달 시 action

`--on-threshold action`은 `|threshold|`로 지정한 latency threshold 때문에 tracing이 멈출 때 실행할 action을 정의한다. 여러 action을 지정하면 입력 순서대로 실행하며 하나가 실패하면 뒤 action은 실행하지 않는다.

`trace[,file=<filename>]`은 trace를 저장하고 선택적으로 file 이름을 받는다. `-t/--trace`의 대안이며 여러 번 지정하면 trace도 여러 번 저장된다. 원문의 `nlike`는 문맥상 `unlike`를 뜻하지만 원문 표기는 그대로 보존한다.

`signal,num=<sig>,pid=<pid>`는 process에 signal을 보내며 `pid` 대신 `parent`를 써 RTLA parent process를 지정할 수 있다. `shell,command=<command>`는 shell command를 실행하고, `continue`는 action 실행 후 tracing을 중단하지 않고 계속한다.

예제는 기본 이름 `|tracer|_trace.txt`로 trace를 저장하고 `ipi_send`가 포함된 줄을 standard output에 출력한 뒤 parent process에 signal 2(SIGINT)를 보낸다. `|actionsperf|` 자리에는 tool별 action 성능 주의 사항이 삽입된다.

**--on-threshold** *action*

        Defines an action to be executed when tracing is stopped on a latency threshold
        specified by |threshold|.

        Multiple --on-threshold actions may be specified, and they will be executed in
        the order they are provided. If any action fails, subsequent actions in the list
        will not be executed.

        Supported actions are:

        - *trace[,file=<filename>]*

          Saves trace output, optionally taking a filename. Alternative to -t/--trace.
          Note that nlike -t/--trace, specifying this multiple times will result in
          the trace being saved multiple times.

        - *signal,num=<sig>,pid=<pid>*

          Sends signal to process. "parent" might be specified in place of pid to target
          the parent process of rtla.

        - *shell,command=<command>*

          Execute shell command.

        - *continue*

          Continue tracing after actions are executed instead of stopping.

        Example:

        $ rtla |tool| |thresharg| 20 --on-threshold trace
        --on-threshold shell,command="grep ipi_send |tracer|\_trace.txt"
        --on-threshold signal,num=2,pid=parent

        This will save a trace with the default filename "|tracer|\_trace.txt", print its
        lines that contain the text "ipi_send" on standard output, and send signal 2
        (SIGINT) to the parent process.

        Performance Considerations:

        |actionsperf|

Tracing 종료 action과 help

`--on-end action`은 tracing이 끝날 때 실행할 action을 정의한다. 여러 번 지정하면 입력 순서대로 실행하고 하나가 실패하면 뒤 action은 실행하지 않는다.

지원 action은 `--on-threshold`와 같지만 `continue`는 효과가 없다. `rtla |tool| -d 5s --on-end trace`는 기본 option으로 RTLA를 5초 실행한 뒤 종료 시 trace를 저장한다.

`-h` 또는 `--help`는 help menu를 출력한다.

**--on-end** *action*

        Defines an action to be executed at the end of tracing.

        Multiple --on-end actions can be specified, and they will be executed in the order
        they are provided. If any action fails, subsequent actions in the list will not be
        executed.

        See the documentation for **--on-threshold** for the list of supported actions, with
        the exception that *continue* has no effect.

        Example:

        $ rtla |tool| -d 5s --on-end trace

        This runs rtla with the default options, and saves trace output at the end.

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

        Print help menu.