1include "../../../../source/Commands/OptionsBase.td"
2
3// The information of the start commands here should match the description of
4// the intel-pt section of the jLLDBTraceStart packet in the
5// lldb/docs/lldb-gdb-remote.txt documentation file. Similarly, it should match
6// the API help message of TraceIntelPT::GetStartConfigurationHelp().
7
8let Command = "thread trace start intel pt" in {
9  def thread_trace_start_intel_pt_size: Option<"size", "s">,
10    Group<1>,
11    Arg<"Value">,
12    Desc<"Trace size in bytes per thread. It must be a power of 2 greater "
13         "than or equal to 4096 (2^12). The trace is circular keeping "
14         "the most recent data. Defaults to 4096 bytes. It's possible to "
15         "specify size using multiples of unit bytes, e.g., 4KB, 1MB, 1MiB, "
16         "where 1K is 1024 bytes and 1M is 1048576 bytes.">;
17  def thread_trace_start_intel_pt_tsc: Option<"tsc", "t">,
18    Group<1>,
19    Desc<"Enable the use of TSC timestamps. This is supported on all devices "
20         "that support intel-pt.">;
21  def thread_trace_start_intel_pt_psb_period: Option<"psb-period", "p">,
22    Group<1>,
23    Arg<"Value">,
24    Desc<"This value defines the period in which PSB packets will be "
25         "generated. A PSB packet is a synchronization packet that contains a "
26         "TSC timestamp and the current absolute instruction pointer. "
27         "This parameter can only be used if "
28         "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc is 1. Otherwise, "
29         "the PSB period will be defined by the processor. If supported, valid "
30         "values for this period can be found in "
31         "/sys/bus/event_source/devices/intel_pt/caps/psb_periods which "
32         "contains a hexadecimal number, whose bits represent valid values "
33         "e.g. if bit 2 is set, then value 2 is valid. The psb_period value is "
34         "converted to the approximate number of raw trace bytes between PSB "
35         "packets as: 2 ^ (value + 11), e.g. value 3 means 16KiB between PSB "
36         "packets. Defaults to 0 if supported.">;
37}
38
39let Command = "process trace start intel pt" in {
40  def process_trace_start_intel_pt_buffer_size: Option<"buffer-size", "s">,
41    Group<1>,
42    Arg<"Value">,
43    Desc<"Size in bytes used by each individual per-thread or per-cpu trace "
44         "buffer. It must be a power of 2 greater than or equal to 4096 (2^12) "
45         "bytes. It's possible to specify a unit for these bytes, like 4KB, "
46         "16KiB or 1MB. Lower case units are allowed for convenience.">;
47  def process_trace_start_intel_pt_per_cpu_tracing:
48    Option<"per-cpu-tracing", "c">,
49    Group<1>,
50    Desc<"Instead of having an individual trace buffer per thread, which uses "
51         "a number trace buffers proportional to the number of running "
52         "threads, this option triggers the collection on a per cpu core "
53         "basis. This effectively traces the entire activity on all cpus "
54         "using a limited amount of trace buffers regardless of the number of "
55         "threads. This might cause data loss for less frequent threads. This "
56         "option forces the capture of TSC timestamps (see --tsc). Also, this "
57         "option can't be used simulatenously with any other trace sessions "
58         "because of its system-wide nature.">;
59  def process_trace_start_intel_pt_process_size_limit:
60    Option<"total-size-limit", "l">,
61    Group<1>,
62    Arg<"Value">,
63    Desc<"Maximum total trace size per process in bytes. This limit applies to "
64         "the sum of the sizes of all thread and cpu traces of this process, "
65         "excluding the ones created with the \"thread trace start\" command. "
66         "Whenever a thread is attempted to be traced due to this command and "
67         "the limit would be reached, the process is stopped with a "
68         "\"processor trace\" reason, so that the user can retrace the process "
69         "if needed. Defaults to 500MB. It's possible to specify a unit for "
70         "these bytes, like 4KB, 16KiB or 1MB. Lower case units are allowed "
71         "for convenience.">;
72  def process_trace_start_intel_pt_tsc: Option<"tsc", "t">,
73    Group<1>,
74    Desc<"Enable the use of TSC timestamps. This is supported on all devices "
75         "that support intel-pt.">;
76  def process_trace_start_intel_pt_psb_period: Option<"psb-period", "p">,
77    Group<1>,
78    Arg<"Value">,
79    Desc<"This value defines the period in which PSB packets will be "
80         "generated. A PSB packet is a synchronization packet that contains a "
81         "TSC timestamp and the current absolute instruction pointer. "
82         "This parameter can only be used if "
83         "/sys/bus/event_source/devices/intel_pt/caps/psb_cyc is 1. Otherwise, "
84         "the PSB period will be defined by the processor. If supported, valid "
85         "values for this period can be found in "
86         "/sys/bus/event_source/devices/intel_pt/caps/psb_periods which "
87         "contains a hexadecimal number, whose bits represent valid values "
88         "e.g. if bit 2 is set, then value 2 is valid. The psb_period value is "
89         "converted to the approximate number of raw trace bytes between PSB "
90         "packets as: 2 ^ (value + 11), e.g. value 3 means 16KiB between PSB "
91         "packets. Defaults to 0 if supported.">;
92  def process_trace_start_intel_pt_disable_cgroup_filtering:
93    Option<"disable-cgroup-filtering", "d">,
94    Desc<"Disable the automatic cgroup filtering that is applied if --per-cpu "
95         "is provided. Cgroup filtering allows collecting intel pt data "
96         "exclusively of processes of the same cgroup as the target.">;
97}
98