--- title: "Intel PT Tracing" layout: default permalink: /page_drpttracer.html ---
DynamoRIO
|
The drpttracer
DynamoRIO Extension provides clients with tracing functionality via Intel's PT instruction tracing feature.
To use drpttracer
with your client simply include this line in your client's CMakeLists.txt
file:
That will automatically set up the include path and library dependence.
Initialize and clean up drpttracer
by calling drpttracer_init() and drpttracer_exit().
Intel PT (Processor Trace) only logs control flow changes. Therefore, when decoding a trace, the decoder needs to get raw bits of every instruction from images. drpttracer
provides APIs to use Intel PT to generate trace data and some auxiliary data to help the decoder (e.g. libipt) to decode the trace. One type of auxiliary data is sideband data. This sideband data stores perf event records, which contain the image change messages necessary for decoding the trace. Another type of auxiliary data is the metadata for a trace. The metadata contains the CPU information and some other information that can be used to synthesize the time of PT trace and the perf event records. The auxiliary data enables the decoder to find the correct raw bits for every instruction.
drpttracer
uses the pttracer handle to manage the tracing sessions. The handle is a pointer to drpttracer's
internal data structure, which contains the tracing's PT data buffer, sideband data buffer, and metadata. To generate a pttracer handle, the client needs to call:
The create function lets the client specify the following parameters:
The client must ensure that the PT trace's ring buffer and the sideband data's ring buffer is large enough to hold the PT data. Insufficient buffer size will lead to lost data, which may cause issues in dynamorio::drmemtrace::pt2ir_t decoding.
After creating a pttracer handle successfully, the client can start or stop a tracing session by calling drpttracer_start_tracing() and drpttracer_stop_tracing().
The client must pass a valid trace handle to the start and stop function. And the client can use one handle for multiple tracing sessions. When the tracing is stopped, the stop function will allocate an instance of drpttracer_output_t, and copy the PT data, sideband data, and metadata to a drpttracer_output_t instance which is returned to the client. If drpttracer_stop_tracing() detects an overflow, it will return an error status code:
After all the tracing sessions are stopped, the client needs to call the following function to free the pttracer handle:
Additionally, to avoid memory leak, the client must call the following function to destroy the output instances after using them:
Also, the client can dump the data in the output to different files for offline post-processing. The user can use the library dynamorio::drmemtrace::pt2ir_t in drcachesim to convert the PT trace to DynamoRIO's IR.
drpttracer
provides three types of tracing modes:
When starting tracing, the client can choose the tracing mode by passing the appropriate flag to drpttracer_start_tracing().
drpttracer
doesn't contain sideband data; it only contains the trace data and metadata.