Fast Buffering APIs

Typedefs
typedef VOID *(*	TRACE_BUFFER_CALLBACK) (BUFFER_ID id, THREADID tid, const CONTEXT *ctxt, VOID *buf, UINT64 numElements, VOID *v)
typedef UINT32	BUFFER_ID

Functions
BUFFER_ID	PIN_DefineTraceBuffer (size_t recordSize, UINT32 numPages, TRACE_BUFFER_CALLBACK fun, VOID *val)
VOID *	PIN_AllocateBuffer (BUFFER_ID id)
VOID	PIN_DeallocateBuffer (BUFFER_ID id, VOID *buf)
VOID *	PIN_GetBufferPointer (CONTEXT *const ctxt, BUFFER_ID id)

Variables
const BUFFER_ID	BUFFER_ID_INVALID = 0

Detailed Description

APIs to perform low-overhead buffering of data for analysis. Use PIN_DefineTraceBuffer() to create space for storing data, and INS_InsertFillBuffer() to fill the buffers. When a buffer overflows, or the thread exits, the defined callback will be used to process the data.

Typedef Documentation

BUFFER_ID

typedef UINT32 BUFFER_ID

Tool buffer ID assigned by Pin.

TRACE_BUFFER_CALLBACK

typedef VOID*(* TRACE_BUFFER_CALLBACK) (BUFFER_ID id, THREADID tid, const CONTEXT *ctxt, VOID *buf, UINT64 numElements, VOID *v)

A call-back function which Pin calls whenever the tools needs to consume a trace buffer (e.g., the trace buffer is full).

@Note This function may be called on a different thread than the given threadIndex.

Parameters

[in]	id	The ID of the trace buffer.
[in]	tid	The ID of the thread owning this buffer.
[in]	buf	Pointer to the start of the buffer.
[in]	numElements	The number of elements collected into the buffer which need to be consumed.
[in]	v	The tool's call-back value.

Returns

A pointer to the buffer to use when the thread resumes. Typically, this is buf, but see also PIN_AllocateBuffer().

Function Documentation

PIN_AllocateBuffer()

VOID* PIN_AllocateBuffer

(

BUFFER_ID

id

)

Explicitly allocate a trace buffer. This is only needed for tools which use a "double buffering" technique. When used, the buffer pointer should be returned from the TRACE_BUFFER_CALLBACK call-back.

Parameters

[in]

id

The ID of the trace buffer to allocate.

Returns

A pointer to the new buffer.]

Note

The pin client lock is obtained during the call of this API.

Availability:

Mode: JIT
O/S: Linux & Windows
CPU: IA-32 and Intel(R) 64 architectures

PIN_DeallocateBuffer()

VOID PIN_DeallocateBuffer	(	BUFFER_ID	id,
		VOID *	buf
	)

Explicitly deallocate a trace buffer. This is only needed by tools using a "double buffering" technique, where it is used to deallocate buffers allocated via PIN_AllocateBuffer(). However, it may be safely called (with no effect) for a thread's implicit initial buffer.

Parameters

[in]	id	The ID of the trace buffer.
[in]	buf	Pointer to the start of the buffer.

Note

The pin client lock is obtained during the call of this API.

Availability:

Mode: JIT
O/S: Linux & Windows
CPU: IA-32 and Intel(R) 64 architectures

PIN_DefineTraceBuffer()

BUFFER_ID PIN_DefineTraceBuffer	(	size_t	recordSize,
		UINT32	numPages,
		TRACE_BUFFER_CALLBACK	fun,
		VOID *	val
	)

Define a trace buffer to use with the Pin trace buffer API. This function defines the shape of the buffer, but doesn't allocate the buffer itself. Each thread implicitly creates its first buffer on start-up. Additional buffers may then be created using PIN_AllocateBuffer, but this is only needed by tools using "double buffering".

Upon exit, the notification callback may be called on a different physical thread than the one that is exiting.

Parameters

[in]	recordSize	Size (bytes) of each record in the buffer. This size must be less than the size of an OS page.
[in]	numPages	The number of OS pages to allocate for each buffer. This size does not have to be an even multiple of recordSize.
[in]	fun	A call-back function that is called whenever the buffer is full, or when the thread exits with a partially-full buffer. Note that when called for a full buffer, not during thread exit, this function is called WITHOUT holding any Pin locks. So that multiple threads may be executing the function simultaneously. It is the tool's responsibility to take care of the multi-thread safety of this function, and any functions called by it.
[in]	val	Passed as the last argument to fun.

Returns

On success, a BUFFER_ID. On error (e.g., maximum number of trace buffers exceeded,) returns BUFFER_ID_INVALID.

Note

The vm and pin client locks are obtained during the call of this API.

Availability:

Mode: JIT
O/S: Linux & Windows
CPU: IA-32 and Intel(R) 64 architectures

PIN_GetBufferPointer()

VOID* PIN_GetBufferPointer	(	CONTEXT *const	ctxt,
		BUFFER_ID	id
	)

Returns the address of the current position in the buffer. Needs a CONTEXT that was passed in as a call back argument or IARG_CONTEXT

Parameters

[in]	id	The ID of the trace buffer.
[in]	ctxt	CONTEXT

Availability:

Mode: JIT
O/S: Linux & Windows
CPU: IA-32 and Intel(R) 64 architectures

Variable Documentation

BUFFER_ID_INVALID

const BUFFER_ID BUFFER_ID_INVALID = 0

ID returned if defining a buffer fails.