--- title: "/ext/drpttracer/drpttracer.h File Reference" layout: default permalink: /drpttracer_8h.html ---
DynamoRIO
drpttracer.h File Reference

Header for DynamoRIO Intel PT Tracing Extension. More...

#include <inttypes.h>

Data Structures

struct  _pt_metadata_t
 
struct  _drpttracer_output_t
 

Typedefs

typedef struct _pt_metadata_t pt_metadata_t
 
typedef struct _drpttracer_output_t drpttracer_output_t
 

Enumerations

enum  drpttracer_status_t {
  DRPTTRACER_SUCCESS ,
  DRPTTRACER_ERROR ,
  DRPTTRACER_ERROR_INVALID_PARAMETER ,
  DRPTTRACER_ERROR_FAILED_TO_OPEN_PERF_EVENT ,
  DRPTTRACER_ERROR_FAILED_TO_MMAP_PERF_DATA ,
  DRPTTRACER_ERROR_FAILED_TO_MMAP_PT_DATA ,
  DRPTTRACER_ERROR_FAILED_TO_ALLOCATE_OUTPUT_BUFFER ,
  DRPTTRACER_ERROR_FAILED_TO_START_TRACING ,
  DRPTTRACER_ERROR_FAILED_TO_STOP_TRACING ,
  DRPTTRACER_ERROR_OVERWRITTEN_PT_TRACE ,
  DRPTTRACER_ERROR_FAILED_TO_READ_PT_DATA ,
  DRPTTRACER_ERROR_OVERWRITTEN_SIDEBAND_DATA ,
  DRPTTRACER_ERROR_FAILED_TO_READ_SIDEBANBD_DATA
}
 
enum  drpttracer_tracing_mode_t {
  DRPTTRACER_TRACING_ONLY_USER ,
  DRPTTRACER_TRACING_ONLY_KERNEL ,
  DRPTTRACER_TRACING_USER_AND_KERNEL
}
 

Functions

DR_EXPORT bool drpttracer_init (void)
 
DR_EXPORT void drpttracer_exit (void)
 
DR_EXPORT drpttracer_status_t drpttracer_create_handle (IN void *drcontext, IN drpttracer_tracing_mode_t tracing_mode, IN uint pt_size_shift, IN uint sideband_size_shift, OUT void **tracer_handle)
 
DR_EXPORT drpttracer_status_t drpttracer_destroy_handle (IN void *drcontext, INOUT void *tracer_handle)
 
DR_EXPORT drpttracer_status_t drpttracer_start_tracing (IN void *drcontext, IN void *tracer_handle)
 
DR_EXPORT drpttracer_status_t drpttracer_stop_tracing (IN void *drcontext, IN void *tracer_handle, OUT drpttracer_output_t *output)
 
DR_EXPORT drpttracer_status_t drpttracer_get_pt_metadata (IN void *tracer_handle, OUT pt_metadata_t *pt_metadata)
 
DR_EXPORT drpttracer_status_t drpttracer_create_output (IN void *drcontext, IN uint pt_buf_size_shift, IN size_t sd_buf_size_shift, OUT drpttracer_output_t **output)
 
DR_EXPORT drpttracer_status_t drpttracer_destroy_output (IN void *drcontext, IN drpttracer_output_t *output)
 

Detailed Description

Header for DynamoRIO Intel PT Tracing Extension.

Typedef Documentation

◆ drpttracer_output_t

The storage container type of drpttracer's output. This data struct is used by drpttracer to store PT trace, and sideband data. These data can be dumped into different files by the client. These files can be the inputs of pt2ir_t, which decodes the PT data into Dynamorio's IR.

Note
This buffer can be shared across different tracing sessions. Thus, we allocate a buffer with the maximum trace size. The pt_size and sideband_size variables indicate the valid data size within the buffer.

◆ pt_metadata_t

typedef struct _pt_metadata_t pt_metadata_t

The type of PT trace's metadata.

Note
drpttracer uses the cpuid instruction to get the cpu_family, cpu_model and cpu_stepping. The cpu_family, cpu_model and cpu_stepping are used to initialize the PT config of pt2ir_t when decoding a PT trace.
drpttracer gets the time_shift, time_mult and time_zero from the opened perf event file's head. The time_shift, time_mult and time_zero are used to initialize the PT sideband config of pt2ir_t when decoding a PT trace.

Enumeration Type Documentation

◆ drpttracer_status_t

Success code for each drpttracer operation.

Enumerator
DRPTTRACER_SUCCESS 

Operation succeeded.

DRPTTRACER_ERROR 

Operation failed.

DRPTTRACER_ERROR_INVALID_PARAMETER 

Operation failed: invalid parameter.

DRPTTRACER_ERROR_FAILED_TO_OPEN_PERF_EVENT 

Operation failed: failed to open perf event.

DRPTTRACER_ERROR_FAILED_TO_MMAP_PERF_DATA 

Operation failed: failed to mmap perf data.

DRPTTRACER_ERROR_FAILED_TO_MMAP_PT_DATA 

Operation failed: failed to mmap PT data.

DRPTTRACER_ERROR_FAILED_TO_ALLOCATE_OUTPUT_BUFFER 

Operation failed: failed to allocate output buffer.

DRPTTRACER_ERROR_FAILED_TO_START_TRACING 

Operation failed: failed to start tracing.

DRPTTRACER_ERROR_FAILED_TO_STOP_TRACING 

Operation failed: failed to stop tracing.

DRPTTRACER_ERROR_OVERWRITTEN_PT_TRACE 

Operation failed: overwritten PT trace.

DRPTTRACER_ERROR_FAILED_TO_READ_PT_DATA 

Operation failed: failed to read PT data from PT ring buffer.

DRPTTRACER_ERROR_OVERWRITTEN_SIDEBAND_DATA 

Operation failed: overwritten sideband data.

DRPTTRACER_ERROR_FAILED_TO_READ_SIDEBANBD_DATA 

Operation failed: failed to read SIDEBAND data from perf data ring buffer.

◆ drpttracer_tracing_mode_t

The tracing modes for drpttracer_start_tracing().

XXX: The DRPTTRACER_TRACING_ONLY_USER and DRPTTRACER_TRACING_USER_AND_KERNEL modes are not completely supported yet. The sideband data collected in these two modes do not include the initial mmap2 event recording. Therefore, if the user uses pt2ir_t in sideband converter mode, pt2ir_t cannot find the image and cannot decode the PT trace.

Enumerator
DRPTTRACER_TRACING_ONLY_USER 

Trace only userspace instructions.

DRPTTRACER_TRACING_ONLY_KERNEL 

Trace only kernel instructions.

DRPTTRACER_TRACING_USER_AND_KERNEL 

Trace both userspace and kernel instructions.

Function Documentation

◆ drpttracer_create_handle()

DR_EXPORT drpttracer_status_t drpttracer_create_handle ( IN void * drcontext,
IN drpttracer_tracing_mode_t tracing_mode,
IN uint pt_size_shift,
IN uint sideband_size_shift,
OUT void ** tracer_handle )

Create a pttracer handle. Must be called after drpttracer_init() and before drpttracer_exit(). The handle is used to start and stop PT tracing.

Parameters
[in]drcontextThe context of DynamoRIO.
[in]tracing_modeThe tracing mode.
[in]pt_size_shiftThe size shift of PT trace's ring buffer.
[in]sideband_size_shiftThe size shift of sideband data's ring buffer.
[out]tracer_handleThe pttracer handle.
Note
The size offset is used to control the size of the buffer allocated by the perf: sizeof(PT trace's buffer) = 2 ^ pt_size_shift * PAGE_SIZE. sizeof(Sideband data's buffer) = 2 ^ sideband_size_shift * PAGE_SIZE. Additionally, perf sets the buffer size to 4MiB by default. Therefore, when the client uses drpttracer to trace, it is best to set the trace and sideband buffer larger than 4Mib.
The client must ensure that the buffer is large enough to hold the PT data. Insufficient buffer size will lead to lost data, which may cause issues in pt2ir_t decoding. If we detect an overflow, drpttracer_stop_tracing() will return an error code DRPTTRACER_ERROR_OVERWRITTEN_PT_TRACE or DRPTTRACER_ERROR_OVERWRITTEN_SIDEBAND_DATA.
Each thread corresponds to a trace handle. When calling drpttracer_create_handle(), the client will get a tracer_handle. The client can start and stop tracing by passing it to drpttracer_start_tracing() and drpttracer_stop_tracing(). And if the thread hold a tracer_handle, the client needs to call drpttracer_destroy_handle() to destroy the corresponding tracer_handle and release the resources before the thread end.
For one thread, only one tracing can execute at the same time. So the client needs to ensure one thread only owns one pttracer handle.
Returns
the status code.

◆ drpttracer_create_output()

DR_EXPORT drpttracer_status_t drpttracer_create_output ( IN void * drcontext,
IN uint pt_buf_size_shift,
IN size_t sd_buf_size_shift,
OUT drpttracer_output_t ** output )

Creates an output object of drpttracer.

Parameters
[in]drcontextThe context of DynamoRIO.
[in]pt_buf_size_shiftThe size shift of the PT trace's output buffer.
[in]sd_buf_size_shiftThe size shift of the sideband data's output buffer.
[out]outputThe output object that will be created.
Returns
the status code.

◆ drpttracer_destroy_handle()

DR_EXPORT drpttracer_status_t drpttracer_destroy_handle ( IN void * drcontext,
INOUT void * tracer_handle )

Destroy a pttracer handle and release the resources. Must be called after drpttracer_init() and before drpttracer_exit().

Parameters
[in]drcontextThe context of DynamoRIO.
[in]tracer_handleThe pttracer handle.
Returns
the status code.

◆ drpttracer_destroy_output()

DR_EXPORT drpttracer_status_t drpttracer_destroy_output ( IN void * drcontext,
IN drpttracer_output_t * output )

Destroys an output object of drpttracer.

Parameters
[in]drcontextThe context of DynamoRIO.
[in]outputThe output object that will be destroyed.
Returns
the status code.

◆ drpttracer_exit()

DR_EXPORT void drpttracer_exit ( void )

Cleans up the drpttracer extension.

◆ drpttracer_get_pt_metadata()

DR_EXPORT drpttracer_status_t drpttracer_get_pt_metadata ( IN void * tracer_handle,
OUT pt_metadata_t * pt_metadata )

Get the PT metadata of the given pttracer handle.

Parameters
[in]tracer_handleThe pttracer handle.
[out]pt_metadataThe PT metadata of the current pttracer handle.
Returns
the status code.

◆ drpttracer_init()

DR_EXPORT bool drpttracer_init ( void )

Initializes the drpttracer extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drpttracer_exit().

Returns
whether successful.

◆ drpttracer_start_tracing()

DR_EXPORT drpttracer_status_t drpttracer_start_tracing ( IN void * drcontext,
IN void * tracer_handle )

Start a PT tracing session. Must pass a valid pttracer handle to this function.

Parameters
[in]drcontextThe context of DynamoRIO.
[in]tracer_handleThe pttracer handle.
Returns
the status code.

◆ drpttracer_stop_tracing()

DR_EXPORT drpttracer_status_t drpttracer_stop_tracing ( IN void * drcontext,
IN void * tracer_handle,
OUT drpttracer_output_t * output )

Stops a PT tracing session. Must pass a valid pttracer handle to this function.

Parameters
[in]drcontextThe context of DynamoRIO.
[in]tracer_handleThe pttracer handle.
[out]outputThe output of PT tracing. This function will allocate and fill this output. It will copy the PT trace to the pt_buf of the output. When the tracing mode is DRPTTRACER_TRACING_ONLY_USER or DRPTTRACER_TRACING_USER_AND_KERNEL, the PT sideband data will be copied to the sideband_buf of the output. When the tracing mode is DRPTTRACER_TRACING_ONLY_KERNEL, it will not copy the sideband data to the buffer.
Note
If the buffer size that was set in drpttracer_start_tracing() is not enough, this function will return an error status code:
The client can dump the output data to files. After online tracing is done, pt2ir_t can use these files to decode the online PT trace.
The client doesn't need to allocate the output object, but it needs to free the output object using drpttracer_destroy_output().
Returns
the status code.