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

#include <inttypes.h>
#include "drpttracer_shared.h"

Data Structures
struct	_drpttracer_output_t

Typedefs
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 (DR_PARAM_IN void drcontext, DR_PARAM_IN drpttracer_tracing_mode_t tracing_mode, DR_PARAM_IN uint pt_size_shift, DR_PARAM_IN uint sideband_size_shift, DR_PARAM_OUT void *tracer_handle)

DR_EXPORT drpttracer_status_t	drpttracer_destroy_handle (DR_PARAM_IN void drcontext, DR_PARAM_INOUT void tracer_handle)

DR_EXPORT drpttracer_status_t	drpttracer_start_tracing (DR_PARAM_IN void drcontext, DR_PARAM_IN void tracer_handle)

DR_EXPORT drpttracer_status_t	drpttracer_stop_tracing (DR_PARAM_IN void drcontext, DR_PARAM_IN void tracer_handle, DR_PARAM_OUT drpttracer_output_t *output)

DR_EXPORT drpttracer_status_t	drpttracer_get_pt_metadata (DR_PARAM_IN void tracer_handle, DR_PARAM_OUT pt_metadata_t pt_metadata)

DR_EXPORT drpttracer_status_t	drpttracer_create_output (DR_PARAM_IN void drcontext, DR_PARAM_IN uint pt_buf_size_shift, DR_PARAM_IN size_t sd_buf_size_shift, DR_PARAM_OUT drpttracer_output_t *output)

DR_EXPORT drpttracer_status_t	drpttracer_destroy_output (DR_PARAM_IN void drcontext, DR_PARAM_IN drpttracer_output_t output)

Detailed Description

Header for DynamoRIO Intel PT Tracing Extension.

Typedef Documentation

◆ drpttracer_output_t

typedef struct _drpttracer_output_t 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.

Enumeration Type Documentation

◆ drpttracer_status_t

enum 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

enum 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	(	DR_PARAM_IN void *	drcontext,
		DR_PARAM_IN drpttracer_tracing_mode_t	tracing_mode,
		DR_PARAM_IN uint	pt_size_shift,
		DR_PARAM_IN uint	sideband_size_shift,
		DR_PARAM_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]	drcontext	The context of DynamoRIO.
[in]	tracing_mode	The tracing mode.
[in]	pt_size_shift	The size shift of PT trace's ring buffer.
[in]	sideband_size_shift	The size shift of sideband data's ring buffer.
[out]	tracer_handle	The 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	(	DR_PARAM_IN void *	drcontext,
		DR_PARAM_IN uint	pt_buf_size_shift,
		DR_PARAM_IN size_t	sd_buf_size_shift,
		DR_PARAM_OUT drpttracer_output_t **	output
	)

Creates an output object of drpttracer.

Parameters

[in]	drcontext	The context of DynamoRIO.
[in]	pt_buf_size_shift	The size shift of the PT trace's output buffer.
[in]	sd_buf_size_shift	The size shift of the sideband data's output buffer.
[out]	output	The output object that will be created.

Returns: the status code.

◆ drpttracer_destroy_handle()

DR_EXPORT drpttracer_status_t drpttracer_destroy_handle	(	DR_PARAM_IN void *	drcontext,
		DR_PARAM_INOUT void *	tracer_handle
	)

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

Parameters

[in]	drcontext	The context of DynamoRIO.
[in]	tracer_handle	The pttracer handle.

Returns: the status code.

◆ drpttracer_destroy_output()

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

Destroys an output object of drpttracer.

Parameters

[in]	drcontext	The context of DynamoRIO.
[in]	output	The 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	(	DR_PARAM_IN void *	tracer_handle,
		DR_PARAM_OUT pt_metadata_t *	pt_metadata
	)

Get the PT metadata of the given pttracer handle.

Parameters

[in]	tracer_handle	The pttracer handle.
[out]	pt_metadata	The 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	(	DR_PARAM_IN void *	drcontext,
		DR_PARAM_IN void *	tracer_handle
	)

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

Parameters

[in]	drcontext	The context of DynamoRIO.
[in]	tracer_handle	The pttracer handle.

Returns: the status code.

◆ drpttracer_stop_tracing()

DR_EXPORT drpttracer_status_t drpttracer_stop_tracing	(	DR_PARAM_IN void *	drcontext,
		DR_PARAM_IN void *	tracer_handle,
		DR_PARAM_OUT drpttracer_output_t *	output
	)

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

Parameters

[in]	drcontext	The context of DynamoRIO.
[in]	tracer_handle	The pttracer handle.
[out]	output	The 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:

Return DRPTTRACER_ERROR_OVERWRITTEN_PT_TRACE if the PT trace is overwritten.
Return DRPTTRACER_ERROR_OVERWRITTEN_SIDEBAND_DATA if the sideband data is overwritten.

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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ drpttracer_output_t

Enumeration Type Documentation

◆ drpttracer_status_t

◆ drpttracer_tracing_mode_t

Function Documentation

◆ drpttracer_create_handle()

◆ drpttracer_create_output()

◆ drpttracer_destroy_handle()

◆ drpttracer_destroy_output()

◆ drpttracer_exit()

◆ drpttracer_get_pt_metadata()

◆ drpttracer_init()

◆ drpttracer_start_tracing()

◆ drpttracer_stop_tracing()