1# Atrace categories
2
3The atrace command (and the perfetto configuration) allow listing **categories**
4to select subsets of events to be traced.
5
6Each category can include some userspace events and some ftrace events.
7
8## Vendor categories
9
10It's possible to extend exiting categories (or to define new categories) from
11the /vendor partition in order to add hardware specific ftrace events.
12
13Since android 14, if the file `/vendor/etc/atrace/atrace_categories.txt`, atrace
14and perfetto will consider the categories and ftrace events listed there.
15
16The file contains a list of categories, and for each category (on the following
17lines, indented with one or more spaces of time), a list of ftrace events that
18should be enabled when the category is enabled.
19
20Each ftrace event should be a subdirectory in `/sys/kernel/tracing/events/` and
21should be of the form `group/event`. Listing a whole group is not supported,
22each event needs to be listed explicitly.
23
24It is not an error if an ftrace event is listed in the file, but not present on
25the tracing file system.
26
27Example:
28
29```
30gfx
31 mali/gpu_power_state
32 mali/mali_pm_status
33thermal_tj
34 thermal_exynos/thermal_cpu_pressure
35 thermal_exynos/thermal_exynos_arm_update
36```
37
38The file lists two categories (`gfx` and `thermal_tj`). When the `gfx` category
39is enabled, atrace (or perfetto) will enable
40`/sys/kernel/tracing/events/mali/gpu_power_state` and
41`/sys/kernel/tracing/events/mali/mali_pm_status`. When the `thermal_tj` category
42is enabled, atrace (or perfetto) will enable
43`/sys/kernel/tracing/events/thermal_exynos/thermal_cpu_pressure` and
44`/sys/kernel/tracing/events/thermal_exynos/thermal_exynos_arm_update`.
45
46Since android 14, if the file `/vendor/etc/atrace/atrace_categories.txt` exists
47on the file system, perfetto and atrace do not query the android.hardware.atrace
48HAL (which is deprecated).
49