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