1*288bf522SAndroid Build Coastguard Worker# **torq: AAOS Performance CLI** 2*288bf522SAndroid Build Coastguard Worker 3*288bf522SAndroid Build Coastguard Worker**torq** is a command-line tool designed to streamline and standardize OS 4*288bf522SAndroid Build Coastguard Workerperformance profiling across Android Automotive devices. By providing a flexible 5*288bf522SAndroid Build Coastguard Workerand easy-to-use interface, **torq** enables engineers and OEMs to capture and 6*288bf522SAndroid Build Coastguard Workeranalyze performance data for critical system events such as boot, user switch, 7*288bf522SAndroid Build Coastguard Workerapp startup, or any of their own interactions with their device. This tool helps 8*288bf522SAndroid Build Coastguard Workerensure consistent results amongst different users and helps reduce the time and 9*288bf522SAndroid Build Coastguard Workereffort required for performance analysis, ensuring that developers can focus on 10*288bf522SAndroid Build Coastguard Workeroptimizing their systems and bug detection rather than navigating fragmented 11*288bf522SAndroid Build Coastguard Workertooling solutions. 12*288bf522SAndroid Build Coastguard Worker 13*288bf522SAndroid Build Coastguard Worker 14*288bf522SAndroid Build Coastguard Worker## Getting Started 15*288bf522SAndroid Build Coastguard Worker 16*288bf522SAndroid Build Coastguard Worker- **torq** is an open source Android tool. Run the following commands to get 17*288bf522SAndroid Build Coastguard Workerstarted: 18*288bf522SAndroid Build Coastguard Worker 19*288bf522SAndroid Build Coastguard Worker``` 20*288bf522SAndroid Build Coastguard Workercd $ANDROID_ROOT 21*288bf522SAndroid Build Coastguard Workersource build/envsetup.sh 22*288bf522SAndroid Build Coastguard Workerlunch <target-name> (e.g., lunch sdk_gcar_x86_64-next-userdebug) 23*288bf522SAndroid Build Coastguard Workercd $ANDROID_ROOT/system/extras/torq 24*288bf522SAndroid Build Coastguard Workerm torq 25*288bf522SAndroid Build Coastguard Worker``` 26*288bf522SAndroid Build Coastguard Worker 27*288bf522SAndroid Build Coastguard Worker- Connect to an Android Automotive device or start an emulator. 28*288bf522SAndroid Build Coastguard Worker- Ensure the connected device appears in `adb devices`. 29*288bf522SAndroid Build Coastguard Worker- You can now run `torq` anywhere, followed by any necessary arguments 30*288bf522SAndroid Build Coastguard Worker(e.g., `torq -d 7000`). 31*288bf522SAndroid Build Coastguard Worker 32*288bf522SAndroid Build Coastguard Worker 33*288bf522SAndroid Build Coastguard Worker## Example Usages 34*288bf522SAndroid Build Coastguard Worker 35*288bf522SAndroid Build Coastguard Worker### ./torq -d 7000 36*288bf522SAndroid Build Coastguard Worker- Run a custom event for 7 seconds. 37*288bf522SAndroid Build Coastguard Worker### ./torq -e user-switch --from-user 10 --to-user 11 38*288bf522SAndroid Build Coastguard Worker- Run a user-switch event, switching from user 10 to user 11. 39*288bf522SAndroid Build Coastguard Worker### ./torq -e boot --perfetto-config ./config 40*288bf522SAndroid Build Coastguard Worker- Run a boot event, using the user's local Perfetto config specified in the 41*288bf522SAndroid Build Coastguard Worker./config file path. 42*288bf522SAndroid Build Coastguard Worker### ./torq -e boot -r 5 --between-dur-ms 3000 43*288bf522SAndroid Build Coastguard Worker- Run a boot event 5 times, waiting 3 seconds between each boot run. 44*288bf522SAndroid Build Coastguard Worker### ./torq -e app-startup -a android.google.kitchensink 45*288bf522SAndroid Build Coastguard Worker- Run an app-startup event, starting the android.google.kitchensink package. 46*288bf522SAndroid Build Coastguard Worker### ./torq -e user-switch --to-user 9 --serial emulator-5554 47*288bf522SAndroid Build Coastguard Worker- Run a user-switch event, switching to user 9 on the connected device with 48*288bf522SAndroid Build Coastguard Workerserial, emulator-5554. 49*288bf522SAndroid Build Coastguard Worker### ./torq -p simpleperf -d 10000 50*288bf522SAndroid Build Coastguard Worker- Run a custom event using the Simpleperf profiler for 10 seconds. 51*288bf522SAndroid Build Coastguard Worker### ./torq -p simpleperf -s cpu-cycles -s instructions 52*288bf522SAndroid Build Coastguard Worker- Run a custom event using the Simpleperf profiler, in which the stats, 53*288bf522SAndroid Build Coastguard Workercpu-cycles and instructions, are collected. 54*288bf522SAndroid Build Coastguard Worker### ./torq -d 10000 --perfetto-config lightweight 55*288bf522SAndroid Build Coastguard Worker- Run a custom event for 10 seconds using the "lightweight" predefined Perfetto 56*288bf522SAndroid Build Coastguard Workerconfig. 57*288bf522SAndroid Build Coastguard Worker### ./torq config show memory 58*288bf522SAndroid Build Coastguard Worker- Print the contents of the memory predefined Perfetto config to the terminal. 59*288bf522SAndroid Build Coastguard Worker### ./torq open trace.perfetto-trace 60*288bf522SAndroid Build Coastguard Worker- Open a trace in the perfetto UI. 61*288bf522SAndroid Build Coastguard Worker### ./torq -d 10000 --exclude-ftrace-event power/cpu_idle 62*288bf522SAndroid Build Coastguard Worker- Run a custom event for 10 seconds, using the "default" predefined Perfetto 63*288bf522SAndroid Build Coastguard Workerconfig, in which the ftrace event, power/cpu_idle, is not collected. 64*288bf522SAndroid Build Coastguard Worker 65*288bf522SAndroid Build Coastguard Worker 66*288bf522SAndroid Build Coastguard Worker## CLI Arguments 67*288bf522SAndroid Build Coastguard Worker 68*288bf522SAndroid Build Coastguard Worker| Argument | Description | Currently Supported Arguments | Default | 69*288bf522SAndroid Build Coastguard Worker|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------| 70*288bf522SAndroid Build Coastguard Worker| `-e, --event` | The event to trace/profile. | `boot`, `user-switch`,`app-startup`, `custom` | `custom` | 71*288bf522SAndroid Build Coastguard Worker| `-p, --profiler` | The performance data profiler. | `perfetto`, (`simpleperf` coming soon) | `perfetto` | 72*288bf522SAndroid Build Coastguard Worker| `-o, --out-dir` | The path to the output directory. | Any local path | Current directory: `.` | 73*288bf522SAndroid Build Coastguard Worker| `-d, --dur-ms` | The duration (ms) of the event. Determines when to stop collecting performance data. | Float >= `3000` | `10000` | 74*288bf522SAndroid Build Coastguard Worker| `-a, --app` | The package name of the app to start.<br/>(Requires use of `-e app-startup`) | Any package on connected device | | 75*288bf522SAndroid Build Coastguard Worker| `-r, --runs` | The amount of times to run the event and capture the performance data. | Integer >= `1` | `1` | 76*288bf522SAndroid Build Coastguard Worker| `--serial` | The serial of the connected device that you want to use.<br/>(If not provided, the ANDROID_SERIAL environment variable is used. If ANDROID_SERIAL is also not set and there is only one device connected, the device is chosen.) | | | 77*288bf522SAndroid Build Coastguard Worker| `--perfetto-config` | The local file path of the user's Perfetto config or used to specify a predefined Perfetto configs. | `default`, any local perfetto config,<br/>(`lightweight`, `memory` coming soon) | `default` | 78*288bf522SAndroid Build Coastguard Worker| `--between-dur-ms` | The amount of time (ms) to wait between different runs.<br/>(Requires that `--r` is set to a value greater than 1) | Float >= `3000` | `10000` | 79*288bf522SAndroid Build Coastguard Worker| `--ui` | Specifies opening of UI visualization tool after profiling is complete.<br/>(Requires that `-r` is not set to a value greater than 1) | `--ui`, `--no-ui`, | `ui` if `runs` is `1` | 80*288bf522SAndroid Build Coastguard Worker| `--exclude-ftrace-event` | Excludes the ftrace event from the Perfetto config. Can be defined multiple times in a command.<br/>(Requires use of `-p perfetto`)<br/>(Currently only works with `--perfetto-config default`,<br/>support for local Perfetto configs, `lightweight`, and `memory` coming soon) | Any supported perfetto ftrace event<br/>(e.g., `power/cpu_idle`, `sched/sched_process_exit`) | Empty list | 81*288bf522SAndroid Build Coastguard Worker| `--include-ftrace-event` | Includes the ftrace event in the Perfetto config. Can be defined multiple times in a command.<br/>(Requires use of `-p perfetto`)<br/>(Currently only works with `--perfetto-config default`,<br/>support for any local Perfetto configs, `lightweight`, and `memory` coming soon) | Any supported perfetto ftrace event<br/>(e.g., `power/cpu_idle`, `sched/sched_process_exit`) | Empty list | 82*288bf522SAndroid Build Coastguard Worker| `--from-user` | The user ID from which to start the user switch. (Requires use of `-e user-switch`) | ID of any user on connected device | Current user on the device | 83*288bf522SAndroid Build Coastguard Worker| `--to-user` | The user ID of user that device is switching to. (Requires use of `-e user-switch`). | ID of any user on connected device | | 84*288bf522SAndroid Build Coastguard Worker| `config list` | Subcommand to list the predefined Perfetto configs (`default`, `lightweight`, `memory`). | | | 85*288bf522SAndroid Build Coastguard Worker| `config show <config-name>` | Subcommand to print the contents of a predefined Perfetto config to the terminal. | `default`, `lightweight`, `memory` | | 86*288bf522SAndroid Build Coastguard Worker| `config pull <config-name> [file-path]` | Subcommand to download a predefined Perfetto config to a specified local file path. | <config-name>: `default`, `lightweight`, `memory`<br/> [file-path]: Any local file path | [file-path]: `./<config-name>.pbtxt` | 87*288bf522SAndroid Build Coastguard Worker| `open <file-path>` | Subcommand to open a Perfetto or Simpleperf trace in the Perfetto UI. | Any local path to a Perfetto or Simpleperf trace file | | 88*288bf522SAndroid Build Coastguard Worker 89*288bf522SAndroid Build Coastguard Worker## Functionality Coming Soon 90*288bf522SAndroid Build Coastguard Worker 91*288bf522SAndroid Build Coastguard Worker| Argument | Description | Accepted Values | Default | 92*288bf522SAndroid Build Coastguard Worker|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|---------------------------------------| 93*288bf522SAndroid Build Coastguard Worker| `-s, --simpleperf-event` | Simpleperf supported events that should be collected. Can be defined multiple times in a command. | Any supported simpleperf event<br/>(e.g., `cpu-cycles`, `instructions`) | Empty list | 94