Merge "ui: Roll HEAD -> canary"
diff --git a/docs/reference/heap_profile-cli.md b/docs/reference/heap_profile-cli.md
index 457b699..18b4f74 100644
--- a/docs/reference/heap_profile-cli.md
+++ b/docs/reference/heap_profile-cli.md
@@ -1,4 +1,6 @@
-# heap_profile
+# heap_profile(1)
+
+## DESCRIPTION
`tools/heap_profile` allows to collect native memory profiles on Android.
See [Recording traces](/docs/data-sources/native-heap-profiler.md) for more
@@ -16,27 +18,78 @@
[--print-config] [-o DIRECTORY]
```
-## Options
-|Option|Description|
-|---|---|
-| -n, --name | Comma-separated list of process names to profile. |
-| -p, --pid | Comma-separated list of PIDs to profile. |
-| -i, --interval | Sampling interval. Default 4096 (4KiB) |
-| -o, --output | Output directory. |
-| -d, --duration | Duration of profile (ms). Default 7 days. |
-| --block-client | When buffer is full, block the client to wait for buffer space. Use with caution as this can significantly slow down the client. This is the default |
-| --no-block-client | When buffer is full, stop the profile early. |
-| --block-client-timeout | If --block-client is given, do not block any allocation for longer than this timeout (us). |
-| -h, --help | Show this help message and exit |
-| --no-start | Do not start heapprofd. |
-| -c, --continuous-dump | Dump interval in ms. 0 to disable continuous dump. |
-| --disable-selinux | Disable SELinux enforcement for duration of profile. |
-| --no-versions | Do not get version information about APKs. |
-| --no-running | Do not target already running processes. Requires Android 11. |
-| --no-startup | Do not target processes that start during the profile. Requires Android 11. |
-| --shmem-size | Size of buffer between client and heapprofd. Default 8MiB. Needs to be a power of two multiple of 4096, at least 8192. |
-| --dump-at-max | Dump the maximum memory usage rather than at the time of the dump. |
-| --disable-fork-teardown | Do not tear down client in forks. This can be useful for programs that use vfork. Android 11+ only. |
-| --simpleperf | Get simpleperf profile of heapprofd. This is only for heapprofd development. |
-| --trace-to-text-binary | Path to local trace to text. For debugging. |
-| --print-config | Print config instead of running. For debugging. |
+## OPTIONS
+`-n`, `--name` _NAMES_
+: Comma-separated list of process names to profile.
+
+`-p`, `--pid` _PIDS_
+: Comma-separated list of PIDs to profile.
+
+`-i`, `--interval`
+: Sampling interval. Default 4096 (4KiB)
+
+`-o`, `--output` _DIRECTORY_
+: Output directory.
+
+`--all-heaps`
+: Collect allocations from all heaps registered by target.
+
+`--block-client`
+: When buffer is full, block the client to wait for buffer space. Use with caution as this can significantly slow down the client. This is the default
+
+`--block-client-timeout`
+: If --block-client is given, do not block any allocation for longer than this timeout (us).
+
+`-c`, `--continuous-dump`
+: Dump interval in ms. 0 to disable continuous dump.
+
+`-d`, `--duration`
+: Duration of profile (ms). 0 to run until interrupted. Default: until interrupted by user.
+
+`--disable-fork-teardown`
+: Do not tear down client in forks. This can be useful for programs that use vfork. Android 11+ only.
+
+`--disable-selinux`
+: Disable SELinux enforcement for duration of profile.
+
+`--dump-at-max`
+: Dump the maximum memory usage rather than at the time of the dump.
+
+`-h`, `--help`
+: show this help message and exit
+
+`--heaps` _HEAPS_
+: Comma-separated list of heaps to collect, e.g: malloc,art. Requires Android 12.
+
+`--idle-allocations`
+: Keep track of how many bytes were unused since the last dump, per callstack
+
+`--no-android-tree-symbolization`
+: Do not symbolize using currently lunched target in the Android tree.
+
+`--no-block-client`
+: When buffer is full, stop the profile early.
+
+`--no-running`
+: Do not target already running processes. Requires Android 11.
+
+`--no-start`
+: Do not start heapprofd.
+
+`--no-startup`
+: Do not target processes that start during the profile. Requires Android 11.
+
+`--no-versions`
+: Do not get version information about APKs.
+
+`--print-config`
+: Print config instead of running. For debugging.
+
+`--shmem-size`
+: Size of buffer between client and heapprofd. Default 8MiB. Needs to be a power of two multiple of 4096, at least 8192.
+
+`--simpleperf`
+: Get simpleperf profile of heapprofd. This is only for heapprofd development.
+
+`--trace-to-text-binary`
+: Path to local trace to text. For debugging.
diff --git a/docs/reference/perfetto-cli.md b/docs/reference/perfetto-cli.md
index f0771d6..8de0f31 100644
--- a/docs/reference/perfetto-cli.md
+++ b/docs/reference/perfetto-cli.md
@@ -1,4 +1,10 @@
-# Perfetto CLI
+# PERFETTO(1)
+
+## NAME
+
+perfetto - capture traces
+
+## DESCRIPTION
This section describes how to use the `perfetto` commandline binary to capture
traces. Examples are given in terms of an Android device connected over ADB.
@@ -6,70 +12,117 @@
`perfetto` has two modes for configuring the tracing session (i.e. what and how
to collect):
-* __lightweight mode__: all config options are supplied as commandline flags,
+__lightweight mode__
+: all config options are supplied as commandline flags,
but the available data sources are restricted to ftrace and atrace. This mode
is similar to
[`systrace`](https://developer.android.com/topic/performance/tracing/command-line).
-* __normal mode__: the configuration is specified in a protocol buffer. This
- allows for full customisation of collected traces.
+
+__normal mode__
+: the configuration is specified in a protocol buffer. This allows for full
+ customisation of collected traces.
-## General options
+## GENERAL OPTIONS
The following table lists the available options when using `perfetto` in either
mode.
-|Option|Description|
-|---|---|
-| `--background \| -d` |Perfetto immediately exits the command-line interface and continues recording your trace in background.|
-|`--out OUT_FILE \| -o OUT_FILE`|Specifies the desired path to the output trace file, or `-` for stdout. `perfetto` writes the output to the file described in the flags above. The output format compiles with the format defined in [AOSP `trace.proto`](/protos/perfetto/trace/trace.proto).|
-|`--dropbox TAG`|Uploads your trace via the [DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html) using the tag you specify.|
-|`--no-guardrails`|Disables protections against excessive resource usage when enabling the `--dropbox` flag during testing.|
-|`--reset-guardrails`|Resets the persistent state of the guardrails and exits (for testing).|
-|`--query`|Queries the service state and prints it as human-readable text.|
-|`--query-raw`|Similar to `--query`, but prints raw proto-encoded bytes of `tracing_service_state.proto`.|
-|`--help \| -h`|Prints out help text for the `perfetto` tool.|
+`-d`, `--background`
+: Perfetto immediately exits the command-line interface and continues
+ recording your trace in background.
+
+`-o`, `--out` _OUT_FILE_
+: Specifies the desired path to the output trace file, or `-` for stdout.
+ `perfetto` writes the output to the file described in the flags above.
+ The output format compiles with the format defined in
+ [AOSP `trace.proto`](/protos/perfetto/trace/trace.proto).
+
+`--dropbox` _TAG_
+: Uploads your trace via the
+ [DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html)
+ using the tag you specify. Android only.
+
+`--no-guardrails`
+: Disables protections against excessive resource usage when enabling the
+ `--dropbox` flag during testing.
-## Lightweight mode
+`--reset-guardrails`
+: Resets the persistent state of the guardrails and exits (for testing).
+
+`--query`
+: Queries the service state and prints it as human-readable text.
+
+`--query-raw`
+: Similar to `--query`, but prints raw proto-encoded bytes of
+ `tracing_service_state.proto`.
+
+`-h`, `--help`
+: Prints out help text for the `perfetto` tool.
+
+
+## LIGHTWEIGHT MODE
The general syntax for using `perfetto` in *lightweight mode* is as follows:
-<pre class="none">
- adb shell perfetto [ --time <var>TIMESPEC</var> ] [ --buffer <var>SIZE</var> ] [ --size <var>SIZE</var> ]
- [ <var>ATRACE_CAT</var> | <var>FTRACE_GROUP/FTRACE_NAME</var>]...
-</pre>
+```
+ adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ]
+ [ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME]...
+```
The following table lists the available options when using `perfetto` in
*lightweight mode*.
-|Option|Description|
-|--- |--- |
-|`--time TIME[s\|m\|h] \| -t TIME[s\|m\|h]`|Specifies the trace duration in seconds, minutes, or hours. For example, `--time 1m` specifies a trace duration of 1 minute. The default duration is 10 seconds.|
-|`--buffer SIZE[mb\|gb] \| -b SIZE[mb\|gb`]|Specifies the ring buffer size in megabytes (mb) or gigabytes (gb). The default parameter is `--buffer 32mb`.|
-|`--size SIZE[mb\|gb] \| -s SIZE[mb\|gb]`|Specifies the max file size in megabytes (mb) or gigabytes (gb). By default `perfetto` uses only in-memory ring-buffer.|
+`-t`, `--time` _TIME[s|m|h]_
+: Specifies the trace duration in seconds, minutes, or hours.
+ For example, `--time 1m` specifies a trace duration of 1 minute.
+ The default duration is 10 seconds.
+
+`-b`, `--buffer` _SIZE[mb|gb]_
+: Specifies the ring buffer size in megabytes (mb) or gigabytes (gb).
+ The default parameter is `--buffer 32mb`.
+
+`-s`, `--size` _SIZE[mb|gb]_
+: Specifies the max file size in megabytes (mb) or gigabytes (gb).
+ By default `perfetto` uses only in-memory ring-buffer.
This is followed by a list of event specifiers:
-|Event|Description|
-|--- |--- |
-|`ATRACE_CAT`|Specifies the atrace categories you want to record a trace for. For example, the following command traces Window Manager using atrace: `adb shell perfetto --out FILE wm`. To record other categories, see this [list of atrace categories](https://android.googlesource.com/platform/frameworks/native/+/refs/tags/android-q-preview-5/cmds/atrace/atrace.cpp#100).|
-|`FTRACE_GROUP/FTRACE_NAME`|Specifies the ftrace events you want to record a trace for. For example, the following command traces sched/sched_switch events: `adb shell perfetto --out FILE sched/sched_switch`|
+`ATRACE_CAT`
+: Specifies the atrace categories you want to record a trace for.
+ For example, the following command traces Window Manager using atrace:
+ `adb shell perfetto --out FILE wm`. To record other categories, see this
+ [list of atrace categories](https://android.googlesource.com/platform/frameworks/native/+/refs/tags/android-q-preview-5/cmds/atrace/atrace.cpp#100).
+
+`FTRACE_GROUP/FTRACE_NAME`
+: Specifies the ftrace events you want to record a trace for.
+ For example, the following command traces sched/sched_switch events:
+ `adb shell perfetto --out FILE sched/sched_switch`
-## Normal mode
+## NORMAL MODE
The general syntax for using `perfetto` in *normal mode* is as follows:
-<pre class="none">
- adb shell perfetto [ --txt ] --config <var>CONFIG_FILE</var>
-</pre>
+```
+ adb shell perfetto [ --txt ] --config CONFIG_FILE
+```
-The following table lists the available options when using `perfetto` in *normal* mode.
+The following table lists the available options when using `perfetto` in
+*normal* mode.
-|Option|Description|
-|--- |--- |
-|`--config CONFIG_FILE \| -c CONFIG_FILE`|Specifies the path to a configuration file. In normal mode, some configurations may be encoded in a configuration protocol buffer. This file must comply with the protocol buffer schema defined in [AOSP `trace_config.proto`](/protos/perfetto/config/data_source_config.proto). You select and configure the data sources using the DataSourceConfig member of the TraceConfig, as defined in [AOSP `data_source_config.proto`](/protos/perfetto/config/data_source_config.proto).|
-|`--txt`|Instructs `perfetto` to parse the config file as pbtxt. This flag is experimental, and it's not recommended that you enable it for production.|
+`-c`, `--config` _CONFIG_FILE_
+: Specifies the path to a configuration file. In normal mode, some
+ configurations may be encoded in a configuration protocol buffer.
+ This file must comply with the protocol buffer schema defined in AOSP
+ [`trace_config.proto`](/protos/perfetto/config/data_source_config.proto).
+ You select and configure the data sources using the DataSourceConfig member
+ of the TraceConfig, as defined in AOSP
+ [`data_source_config.proto`](/protos/perfetto/config/data_source_config.proto).
+
+`--txt`
+: Instructs `perfetto` to parse the config file as pbtxt. This flag is
+ experimental, and it's not recommended that you enable it for production.
diff --git a/infra/perfetto.dev/src/markdown_render.js b/infra/perfetto.dev/src/markdown_render.js
index 8fe5cc9..21d03ed 100644
--- a/infra/perfetto.dev/src/markdown_render.js
+++ b/infra/perfetto.dev/src/markdown_render.js
@@ -158,6 +158,15 @@
if (cssClass != '') {
cssClass = ` class="callout ${cssClass}"`;
}
+
+ // Rudimentary support of definition lists.
+ var colonStart = text.search("\n:")
+ if (colonStart != -1) {
+ var key = text.substring(0, colonStart);
+ var value = text.substring(colonStart + 2);
+ return `<dl><dt><p>${key}</p></dt><dd><p>${value}</p></dd></dl>`
+ }
+
return `<p${cssClass}>${text}</p>\n`;
}
diff --git a/tools/heap_profile b/tools/heap_profile
index b635a12..f3ee35a 100755
--- a/tools/heap_profile
+++ b/tools/heap_profile
@@ -164,6 +164,25 @@
).decode('utf-8').strip()
return codename == release
+ORDER = ['-n', '-p', '-i', '-o']
+
+def arg_order(action):
+ result = len(ORDER)
+ for opt in action.option_strings:
+ if opt in ORDER:
+ result = min(ORDER.index(opt), result)
+ return result, action.option_strings[0].strip('-')
+
+def print_options(parser):
+ for action in sorted(parser._actions, key=arg_order):
+ if action.help is argparse.SUPPRESS:
+ continue
+ opts = ', '.join('`' + x + '`' for x in action.option_strings)
+ metavar = '' if action.metavar is None else ' _' + action.metavar + '_'
+ print('{}{}'.format(opts, metavar))
+ print(': {}'.format(action.help))
+ print()
+
def main(argv):
parser = argparse.ArgumentParser()
parser.add_argument(
@@ -294,8 +313,16 @@
help="Output directory.",
metavar="DIRECTORY",
default=None)
+ parser.add_argument(
+ "--print-options",
+ action="store_true",
+ help=argparse.SUPPRESS
+ )
args = parser.parse_args()
+ if args.print_options:
+ print_options(parser)
+ return 0
fail = False
if args.block_client and args.no_block_client:
print(
