1****************************************************************************
2* README *
3* *
4* This file provides all the information regarding 4 new CLI commands that *
5* enable using Intel(R) Processor Trace Tool from LLDB's CLI. *
6****************************************************************************
7
8
9============
10Introduction
11============
12A C++ based cli wrapper has been developed to use Intel(R) Processor Trace Tool
13through LLDB's command line. This also provides an idea to all developers on how
14to integrate the Tool into various IDEs providing LLDB as a debugger.
15
16
17
18============
19How to Build
20============
21The wrapper cli-wrapper-pt.cpp needs to be compiled and linked with the shared
22library of the Intel(R) Processor Trace Tool in order to be used through LLDB's
23CLI. The procedure to build shared library of the Intel(R) Processor Trace Tool
24is given in README_TOOL.txt file.
25
26
27
28============
29How to Use
30============
31All these commands are available via shared library (lldbIntelFeatures)
32obtained after building intel-features folder from top. Please refer to
33cli-wrapper.cpp and README files of "intel-features" folder for this purpose.
34
35
36
37============
38Description
39============
404 CLI commands have been designed keeping the LLDB's existing CLI command syntax
41in mind.
42
43 1) processor-trace start [-b <buffer-size>] [<thread-index>]
44
45 Start Intel(R) Processor Trace on a specific thread or on the whole process
46
47 Syntax: processor-trace start <cmd-options>
48
49 cmd-options Usage:
50 processor-trace start [-b <buffer-size>] [<thread-index>]
51
52 -b <buffer-size>
53 size of the trace buffer to store the trace data. If not specified
54 then a default value (=4KB) will be taken
55
56 <thread-index>
57 thread index of the thread. If no threads are specified, currently
58 selected thread is taken. Use the thread-index 'all' to start
59 tracing the whole process
60
61
62
63 2) processor-trace stop [<thread-index>]
64
65 Stop Intel(R) Processor Trace on a specific thread or on the whole process
66
67 Syntax: processor-trace stop <cmd-options>
68
69 cmd-options Usage:
70 processor-trace stop [<thread-index>]
71
72 <thread-index>
73 thread index of the thread. If no threads are specified, currently
74 selected thread is taken. Use the thread-index 'all' to stop
75 tracing the whole process
76
77
78
79 3) processor-trace show-trace-options [<thread-index>]
80
81 Display all the information regarding Intel(R) Processor Trace for a specific
82 thread or for the whole process. The information contains trace buffer
83 size and configuration options of Intel(R) Processor Trace.
84
85 Syntax: processor-trace show-trace-options <cmd-options>
86
87 cmd-options Usage:
88 processor-trace show-trace-options [<thread-index>]
89
90 <thread-index>
91 thread index of the thread. If no threads are specified, currently
92 selected thread is taken. Use the thread-index 'all' to display
93 information for all threads of the process
94
95
96
97 4) processor-trace show-instr-log [-o <offset>] [-c <count>] [<thread-index>]
98
99 Display a log of assembly instructions executed for a specific thread or
100 for the whole process. The length of the log to be displayed and the
101 offset in the whole instruction log from where the log needs to be
102 displayed can also be provided. The offset is counted from the end of this
103 whole instruction log which means the last executed instruction is at
104 offset 0 (zero).
105
106 Syntax: processor-trace show-instr-log <cmd-options>
107
108 cmd-options Usage:
109 processor-trace show-instr-log [-o <offset>] [-c <count>] [<thread-index>]
110
111 -c <count>
112 number of instructions to be displayed. If not specified then a
113 default value (=10) will be taken
114
115 -o <offset>
116 offset in the whole instruction log from where the log will be
117 displayed. If not specified then default value is calculated as
118 offset = count -1
119
120 <thread-index>
121 thread index of the thread. If no threads are specified, currently
122 selected thread is taken. Use the thread-index 'all' to show
123 instruction log for all the threads of the process
124
1*******************************************************************************
2* README *
3* *
4* This file provides all the information regarding Intel(R) Processor Trace *
5* Tool. It consists explanation about how Tool internally works, its hardware *
6* and software dependencies, build procedure and usage of the API. *
7*******************************************************************************
8
9
10
11============
12Introduction
13============
14The Intel(R) Processor Trace Tool is developed on top of LLDB and provides its
15its users execution trace of the debugged applications. Tool makes use of
16Intel(R) Processor Trace hardware feature implementation inside LLDB for this
17purpose. This hardware feature generates a set of trace packets that
18encapsulates program flow information. These trace packets along with the binary
19of the application can be decoded with the help of a software decoder to
20construct the execution trace of the application.
21
22More information about Intel(R) Processor Trace feature can be obtained from
23website: https://software.intel.com/en-us/blogs/2013/09/18/processor-tracing
24
25
26
27
28=========
29Details
30=========
31The functionality of the Tool consists three parts:
32
331. Raw Trace Collection from LLDB
34 With the help of API of this Tool (given below), Intel(R) Processor Trace
35 can be started on the application being debugged with LLDB. The generated
36 trace of the application is gathered inside LLDB and is collected by the
37 Tool from LLDB through LLDB's public API.
38
392. Raw Trace Decoding
40 For decoding the raw trace data, the Tool makes use of "libipt", an
41 Intel(R) Processor Trace Decoder Library. The library needs binary of
42 the application and information about the cpu on which the application is
43 running in order to decode the raw trace. The Tool gathers this
44 information from LLDB public API and provide it to "libipt". More
45 information about "libipt" can be found at:
46 https://software.intel.com/en-us/blogs/2013/09/18/processor-tracing and
47 https://github.com/01org/processor-trace
48
493. Decoded Trace Post-processing
50 The decoded trace is post-processed to reconstruct the execution flow of
51 the application. The execution flow contains the list of assembly
52 instructions (called instruction log hereafter).
53
54
55
56
57=============
58Dependencies
59=============
60The Tool has following hardware and software dependencies:
61
62 - Hardware dependency: The Tool makes use of this hardware feature to capture
63 raw trace of an application from LLDB. This hardware feature may not be
64 present in all processors. The hardware feature is supported on Broadwell
65 and other succeeding CPUs such as Skylake etc. In order for Tool to provide
66 something meaningful, the target machine on which the application is running
67 should have this feature.
68
69 - Software dependency: The Tool has an indirect dependency on the Operating
70 System level software support for Intel(R) Processor Trace on the target
71 machine where the application is running and being debugged by LLDB. This
72 support is required to enable raw trace generation on the target machine.
73 Currently, the Tool works for applications running on Linux OS as till now
74 the Operating System level support for the feature is present only in Linux
75 (more specifically starting from the 4.1 kernel). In Linux, this feature is
76 implemented in perf_events subsystem and is usable through perf_event_open
77 system call. In the User space level, the Tool has a direct dependency on
78 "libipt" to decode the captured raw trace. This library might be
79 pre-installed on host systems. If not then the library can be built from
80 its sources (available at): https://github.com/01org/processor-trace
81
82
83
84
85============
86How to Build
87============
88The Tool has a cmake based build and can be built by specifying some extra flags
89while building LLDB with cmake. The following cmake flags need to be provided to
90build the Tool:
91
92 - LIBIPT_INCLUDE_PATH - The flag specifies the directory where the header
93 file of "libipt" resides. If the library is not pre-installed on the host
94 system and is built directly from "libipt" project sources then this file
95 may either come as a part of the sources itself or will be generated in
96 build folder while building library.
97
98 - LIBIPT_LIBRARY_PATH - The flag points to the location of "libipt" shared
99 library.
100
101The Tool currently works successfully with following versions of this library:
102 - v1.4, v1.5, v1.6
103
104
105
106============
107How to Use
108============
109The Tool's API are exposed as a C++ object oriented interface (file PTDecoder.h)
110in a shared library. The main class that implements the whole functionality is
111PTDecoder. This class makes use of 3 other classes,
112 - PTInstruction to represent an assembly instruction
113 - PTInstructionList to return instruction log
114 - PTTraceOptions to return trace specific information
115The users can use these API to develop their own products. All API are also
116available as python functions through a script bridging interface, allowing
117them to be used directly from python either interactively or to build python
118apps.
119
120Currently, cli wrapper has been developed on top of the Tool to use it through
121LLDB's command line. Please refer to README_CLI.txt file for command line usage.
122
123
124A brief introduction about the classes and their API are given below.
125
126 class PTDecoder
127 ===============
128 This class makes use of Intel(R) Processor Trace hardware feature
129 (implemented inside LLDB) to gather trace data for an inferior (being
130 debugged with LLDB) to provide meaningful information out of it. Currently
131 the meaningful information comprises of the execution flow of the inferior
132 (in terms of assembly instructions executed). The class enables user to:
133
134 - start the trace with configuration options for a thread/process,
135 - stop the trace for a thread/process,
136 - get the execution flow (assembly instructions) for a thread and
137 - get trace specific information for a thread
138
139 Corresponding API are explained below:
140 a) void StartProcessorTrace(lldb::SBProcess &sbprocess,
141 lldb::SBTraceOptions &sbtraceoptions,
142 lldb::SBError &sberror)
143 ------------------------------------------------------------------------
144 This API allows the user to start trace on a particular thread or on
145 the whole process with Intel(R) Processor Trace specific
146 configuration options.
147
148 @param[in] sbprocess : A valid process on which this operation
149 will be performed. An error is returned in case of an invalid
150 process.
151
152 @param[out] sberror : An error with the failure reason if API
153 fails. Else success.
154
155 @param[in] sbtraceoptions : Contains thread id information and
156 configuration options:
157 For tracing a single thread, provide a valid thread id. If
158 sbprocess doesn't contain this thread id, error will be returned.
159 For tracing complete process, set to lldb::LLDB_INVALID_THREAD_ID
160 Configuration options comprises of:
161 - trace buffer size, meta data buffer size, TraceType and
162 - All other possible Intel(R) Processor Trace specific
163 configuration options (hereafter collectively referred as
164 CUSTOM_OPTIONS)
165
166 Trace buffer, meant to store the trace data read from target
167 machine, inside LLDB is configured as a cyclic buffer. Hence,
168 depending upon the trace buffer size provided here, buffer
169 overwrites may happen while LLDB writes trace data into it.
170 CUSTOM_OPTIONS are formatted as json text i.e. {"Name":Value,
171 "Name":Value,...} inside sbtraceoptions, where "Value" should be
172 a 64-bit unsigned integer in hex format. For information
173 regarding what all configuration options are currently supported
174 by LLDB and detailed information about CUSTOM_OPTIONS usage,
175 please refer to SBProcess::StartTrace() API description. An
176 overview of some of the various CUSTOM_OPTIONS are briefly given
177 below. Please refer to "Intel(R) 64 and IA-32 Architectures
178 Software Developer's Manual" for more details about them.
179 - CYCEn Enable/Disable Cycle Count Packet (CYC) Packet
180 - OS Packet generation enabled/disabled if
181 Current Privilege Level (CPL)=0
182 - User Packet generation enabled/disabled if CPL>0
183 - CR3Filter Enable/Disable CR3 Filtering
184 - MTCEn Enable/disable MTC packets
185 - TSCEn Enable/disable TSC packets
186 - DisRETC Enable/disable RET Compression
187 - BranchEn Enable/disable COFI-based packets
188 - MTCFreq Defines MTC Packet Frequency
189 - CycThresh CYC Packet threshold
190 - PSBFreq Frequency of PSB Packets
191
192 TraceType should be set to
193 lldb::TraceType::eTraceTypeProcessorTrace, else error is
194 returned. To find out any other requirement to start tracing
195 successfully, refer to SBProcess::StartTrace() API description.
196 LLDB's current implementation of Intel(R) Processor Trace
197 feature may round off invalid values for configuration options.
198 Therefore, the configuration options with which the trace was
199 actually started, might be different to the ones with which
200 trace was asked to be started by user. The actual used
201 configuration options can be obtained from
202 GetProcessorTraceInfo() API.
203
204
205
206 b) void StopProcessorTrace(lldb::SBProcess &sbprocess,
207 lldb::SBError &sberror,
208 lldb::tid_t tid = LLDB_INVALID_THREAD_ID)
209 ------------------------------------------------------------------------
210 This API allows the user to Stop trace on a particular thread or on
211 the whole process.
212
213 @param[in] sbprocess : A valid process on which this operation will
214 be performed. An error is returned in case of an invalid process.
215
216 @param[in] tid : To stop tracing a single thread, provide a
217 valid thread id. If sbprocess doesn't contain the thread tid,
218 error will be returned. To stop tracing complete process, use
219 lldb::LLDB_INVALID_THREAD_ID
220
221 @param[out] sberror : An error with the failure reason if API fails.
222 Else success
223
224
225
226 c) void GetInstructionLogAtOffset(lldb::SBProcess &sbprocess, lldb::tid_t tid,
227 uint32_t offset, uint32_t count,
228 PTInstructionList &result_list,
229 lldb::SBError &sberror)
230 ------------------------------------------------------------------------
231 This API provides instruction log that contains the execution flow
232 for a thread of a process in terms of assembly instruction executed.
233 The API works on only 1 thread at a time. To gather this information
234 for whole process, this API needs to be called for each thread.
235
236 @param[in] sbprocess : A valid process on which this operation
237 will be performed. An error is returned in case of an invalid
238 process.
239
240 @param[in] tid : A valid thread id of the thread for which
241 instruction log is desired. If sbprocess doesn't contain the
242 thread tid, error will be returned.
243
244 @param[in] count : Number of instructions requested by the
245 user to be returned from the complete instruction log. Complete
246 instruction log refers to all the assembly instructions obtained
247 after decoding the complete raw trace data obtained from LLDB.
248 The length of the complete instruction log is dependent on the
249 trace buffer size with which processor tracing was started for
250 this thread.
251 The number of instructions actually returned are dependent on
252 'count' and 'offset' parameters of this API.
253
254 @param[in] offset : The offset in the complete instruction log
255 from where 'count' number of instructions are requested by the
256 user. offset is counted from the end of of this complete
257 instruction log (which means the last executed instruction
258 is at offset 0 (zero)).
259
260 @param[out] result_list : Depending upon 'count' and 'offset' values,
261 list will be overwritten with the instructions.
262
263 @param[out] sberror : An error with the failure reason if API
264 fails. Else success
265
266
267
268 d) void GetProcessorTraceInfo(lldb::SBProcess &sbprocess, lldb::tid_t tid,
269 PTTraceOptions &options, lldb::SBError &sberror)
270 ------------------------------------------------------------------------
271 This API provides Intel(R) Processor Trace specific information for
272 a thread of a process. The API works on only 1 thread at a time. To
273 gather this information for whole process, this API needs to be
274 called for each thread. The information contains the actual
275 configuration options with which the trace was started for this
276 thread.
277
278 @param[in] sbprocess : The valid process on which this operation
279 will be performed. An error is returned in case of an invalid
280 process.
281
282 @param[in] tid : A valid thread id of the thread for which the
283 trace specific information is required. If sbprocess doesn't
284 contain the thread tid, an error will be returned.
285
286 @param[out] options : Contains actual configuration options (they
287 may be different to the ones with which tracing was asked to be
288 started for this thread during StartProcessorTrace() API call).
289
290 @param[out] sberror : An error with the failure reason if API
291 fails. Else success
292
293
294 class PTInstruction
295 ===================
296 This class represents an assembly instruction containing raw instruction
297 bytes, instruction address along with execution flow context and
298 Intel(R) Processor Trace context. For more details, please refer to
299 PTDecoder.h file.
300
301 class PTInstructionList
302 =======================
303 This class represents a list of assembly instructions. Each assembly
304 instruction is of type PTInstruction.
305
306 class PTTraceOptions
307 ====================
308 This class provides Intel(R) Processor Trace specific configuration
309 options like trace type, trace buffer size, meta data buffer size along
310 with other trace specific options. For more details, please refer to
311 PTDecoder.h file.
312