gatord command-line options

gatord must be running before you can capture trace data. The command-line options configure how gatord captures events and how it communicates with Streamline running on your host.

gatord has two modes of operation:

Daemon mode (the default mode)

Sends captured events to a host running Streamline.

Local capture mode

Writes the capture to a file then exits.

To enable this mode, specify an output directory with the --output flag.

Arguments available to all modes:

gatord arguments available to all modes
Option	Description
`-h, --help`	Lists all the available `gatord` command-line options.
`-c, --config-xml <config_xml>`	Specify the path and filename of the `configuration.xml` file that defines the capture options. In daemon mode, the list of counters is written to this file. In local capture mode, the list of counters is read from this file.
`-e, --events-xml <events_xml>`	Specify the path and filename of the `events.xml` file. `events.xml` defines all the counters that Streamline collects during the capture session.
`-E, --append-events-xml <events_xml>`	Specify the path and filename of the `events.xml` file to append.
`-P, --pmus-xml <pmu_xml>`	Specify the path and filename of the `pmu.xml` file to append.
`-v, --version`	Print version information.
`-d, --debug`	Enable debug messages.
`-A, --app <cmd> <args...>`	Specify the command to execute when the capture starts. This argument must be the last argument that is passed to `gatord`. All subsequent arguments are passed to the launched application.
`-D, --disable-kernel-annotations`	Disable collection of kernel annotations
`-k, --exclude-kernel <yes\|no>`	Specify whether to filter out kernel events from the perf results.
`-S, --system-wide <yes\|no>`	Specify whether to capture the whole system. In daemon mode, `no` is only applicable when `--allow-command` is specified. In this mode, you must enter a command in the Start view. Defaults to `yes`, unless `--app`, `--pid`, or `--wait-process` is specified.
`-u, --call-stack-unwinding <yes\|no>`	Enable or disable call stack unwinding. Defaults to `yes`.
`-r, --sample-rate <none\|low\|normal\|high>`	Specify the sample rate for the capture. The frequencies for each sample rate are: `high` = 10kHz `normal` = 1kHz for CPU events, or 2kHz for GPU events `low` = 100Hz `none` = the lowest possible rate Defaults to `normal`. Note For older GPUs, such as Bifrost and earlier, GPU sampling rate in `normal` mode is set to 1kHz.
`-t, --max-duration <s>`	Specify the maximum duration that the capture can run for in seconds. Defaults to `0`, which means unlimited.
`-f, --use-efficient-ftrace <yes\|no>`	Enable efficient ftrace data collection mode. Defaults to `yes`.
`-w, --app-cwd <path>`	Specify the working directory for the application that `gatord` launches. Defaults to the current directory.
`-x, --stop-on-exit <yes\|no>`	Stop the capture when the launched application exits. Defaults to `no`, unless `--app`, `--pid`, or `--wait-process` is specified.
`-Q, --wait-process <command>`	Wait for a process that matches the specified command to launch before starting the capture. Attach to the specified process and profile it.
`-Z, --mmap-pages <n>`	The maximum number of pages to map per mmaped perf buffer is equal to `<n+1>`. `n` must be a power of two.
`-O, --disable-cpu-onlining <yes\|no>`	To not switch on CPU cores that are offline to read their information. This option is useful for kernels that fail to handle this action correctly, for example they reboot the system. Defaults to `no`.
`-F, --spe-sample-rate <n>`	Specify the SPE periodic sampling rate. The rate, `<n>`, is the number of operations between each sample, and must be a nonzero positive integer. The hardware specifies the minimum rate. Values below this threshold are ignored and the hardware minimum is used instead.
`-L, --capture-log`	Enable to generate a log file for the capture in the capture's directory, as well as sending the logs to `stderr`.
`--smmuv3-model <model_id>\|<iidr>`	Specify the SMMUv3 model. You can specify the model ID string directly, such as `mmu-600`, or the hex value representation for the model's IIDR number either fully, such as `4832243b`, or partially, such as `483_43b`.
`-Y, --off-cpu-time <yes\|no>`	Collect Off-CPU time statistics. Detailed statistics require `root` permission.
`-I, --inherit <yes\|no\|poll>`	When profiling an application, gatord monitors all subsequent threads and child processes. Specify `no` to monitor only the initial thread of the application. Specify `poll` to periodically look for new processes or threads. Note Per-function metrics are only supported in system-wide mode, or when `--inherit` is set to `no` or `poll`. The default is `yes`.
`-N, --num-pmu-counters <n>`	Override the number of programmable PMU counters that are available. This option reduces the number of programmable PMU counters available for profiling. Use this option when the default is incorrect, or because some programmable counters are unavailable because they are consumed by the OS, or other processes, or by a hypervisor. Note The Arm PMU typically exposes 6 programmable counters, and one fixed function cycle counter. This argument assumes the fixed cycle counter is not part of the reduced set of counters. If your target exposes 2 programmable counters and the fixed cycle counter, then `2` is passed for the value of `<n>`. However, if your target exposes 2 programmable counters and no fixed cycle counter, then `1` is passed for the value of `<n>`.

Arguments available in daemon mode only:

gatord arguments available in daemon mode only
Option	Description
`-p, --port <port_number>\|uds`	Set the port number that `gatord` uses to communicate with the host. The default is 8080. If you use the argument `uds`, the TCP socket is disabled and an abstract Unix domain socket is created. This socket is named `streamline-data`. If you use Android, creating a Unix domain socket is useful because `gatord` is usually prevented from creating a TCP server socket. Alternatively, you can connect to `localhost:<local_port>` in Streamline using: `adb forward tcp:<local_port> localabstract:streamline-data`
`-a, --allow-command`	Allows you to run a command on the target during profiling. The command is specified in the Start view. Note If you use this option, an unauthenticated user could run arbitrary commands on the target using Streamline.

Arguments available to local capture mode only:

gatord arguments available to local capture mode only
Option	Description
`-s, --session-xml <session_xml>`	Specify the `session.xml` file that the configuration is taken from. Any additional arguments override values that are specified in this file.
`-o, --output <apc_dir>`	Specify the path and filename of the output directory for a local capture. The directory path will be appended with the extension `.apc` if it is not already the case.
`-i, --pid <pids...>`	A comma-separated list of process IDs to profile.
`-C, --counters <counters>`	A comma-separated list of counters to enable. You can specify this option multiple times. An event code and a slot identify most hardware counters. To specify the counter for a particular slot, pass: `--counters <device>_cnt<s>:<e>` Where: `<device>` is the prefix that identifies the device type. `<s>` is the slot number. `<e>` is the event code.
`-X, --spe <id>[:events=<indexes>][:ops=<types>][:min_latency=<lat>]`	Enable the Statistical Profiling Extension (SPE). Where: `<id>` is the name of the SPE properties that are specified in the `events.xml` or `pmus.xml` file. It uniquely identifies the available events and counters for the SPE hardware. `<indexes>` is a comma-separated list of event indexes to filter the sampling by. A sample is only recorded if all events are present. `<types>` is a comma-separated list of operation types to filter the sampling by. If a sample is any of the types in `<types>`, it is recorded. Valid types are `LD` for load, `ST` for store and `B` for branch. `<lat>` is the minimum latency. A sample is only recorded if its latency is greater than or equal to this value. The valid range is [0,4096].

Argument usage examples

Use --pmus-xml and --append-events-xml to add support for a new PMU without having to rebuild gatord.

--pmus-xml specifies an XML file that defines a new PMU to add to the list of PMUs that gatord has built-in support for. The list of built-in PMUs is defined in pmus.xml, which is in the gatord source directory.

--append-events-xml specifies an XML file that defines one or more event counters to append to the events.xml file. This option allows you to add new events to gatord without having to rebuild gatord or to entirely replace events.xml.

The events.xml file must include the XML header and elements that are shown in the following example:
```
<?xml version="1.0" encoding="UTF-8"?>
<events>
    <category name="Filesystem">
        <event counter="filesystem_loginuid" path="/proc/self/loginuid" title="loginuid" name="loginuid" description="loginuid"/>
    </category>
</events>
```
The Instructions Executed counter is configured in slot 0 as:
```
--counters ARMv8_Cortex_A53_cnt0:0x08
```
To configure the cycle counter, specify --counters <device>_ccnt. For example:
```
--counters ARMv8_Cortex_A53_ccnt
```
Other counters do not have event codes and are identified only by name. For example:
```
--counters PERF_COUNT_SW_PAGE_FAULTS
```