REPLAY

Functions
IMG	IMG_CreateAt (const char *filename, ADDRINT start, USIZE size, ADDRINT loadOffset, BOOL mainExecutable)
VOID	IMG_ReplayImageLoad (IMG img)
VOID	PIN_ReplayContextChange (THREADID tid, const CONTEXT *from, CONTEXT *to, CONTEXT_CHANGE_REASON reason, INT32 info)
VOID	IMG_ReplayImageUnload (IMG img)
BOOL	PIN_WasMemoryReservedInLoadTime ()

Detailed Description

Function Documentation

IMG_CreateAt()

IMG IMG_CreateAt	(	const char *	filename,
		ADDRINT	start,
		USIZE	size,
		ADDRINT	loadOffset,
		BOOL	mainExecutable
	)

Static model for instrumenting IMG's once they are loaded into memory.

Returns a IMG object for image loaded outside of PIN's loader. Tool should use this IMG object to mark the routines inside it, using RTN_CreateAt(). After all the routines are marked, tool should call IMG_ReplayImageLoad() to finalize the image load procedure.

Parameters

filename	name of the image visible to Pin tools
start	memory address where first byte of the image is loaded to
size	the size of the image in memory. This means that the image region in memory will be at [start .. start+size)
loadOffset	the offset between the memory addresses specified in the executable/library files and the memory addresses where this image was actaully loaded
mainImage	TRUE if this is the main image

Returns

IMG object that represents the image. Please make sure to call IMG_ReplayImageLoad() on the IMG object after you're done creating all the routines in the IMG object.

Availability:

Mode: JIT
O/S: All
CPU: All

IMG_ReplayImageLoad()

VOID IMG_ReplayImageLoad

(

IMG

img

)

Replays the image load of an IMG object (created by IMG_CreateAt()). This means that all the image load callbacks will be called for the specified IMG object. If PIN_StartProgram() wasn't called yet, PIN will enqueue this request and will process this request after PIN_StartProgram() was called

Parameters

[in]

img

The image object to replay its load

Note

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

Availability:

Mode: JIT
O/S: All
CPU: All

IMG_ReplayImageUnload()

VOID IMG_ReplayImageUnload

(

IMG

img

)

Ask Pin to perform all the functions it would normally do when it detects that a shared library has been unloaded. This is intended for use in a replay system, where the replay tool has recorded library unload operations, and now wants to replay them.

Note that a replay system need not explicitly call this function to cause image unload callbacks at the end of process execution. Pin will generate those callbacks itself provided that images were created using the IMG_ReplayImageLoad call. However, this function is required to handle explicit image unloads (for instance those caused by dlclose() )

IMG_ReplayImageUnload can be called from analysis or callback routines. If called from an analysis routine, the Pin client lock must be claimed before calling IMG_ReplayImageUnload (the Pin client lock is already held when in a callback routine, so there is no need to claim it again).

Parameters

img	the IMG to be unloaded

Note

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

Availability:

Mode: JIT
O/S: Linux (others to follow)
CPU: All

PIN_ReplayContextChange()

VOID PIN_ReplayContextChange	(	THREADID	tid,
		const CONTEXT *	from,
		CONTEXT *	to,
		CONTEXT_CHANGE_REASON	reason,
		INT32	info
	)

This API is intended for use by tools that replay the execution of an application and need to replay an asynchronous context change that was received by the application at record time. This API is not intended as a general way to send a forced context change (signal, exception, APC) to the application. To do that, see PIN_RaiseException().

Calling this API causes Pin to call back on the tool's context-changed notification function if one was set up with PIN_AddContextChangeFunction(). Thus, the tool is notified about the context change as though the application really received it. Calling this API may also notify an external debugger if one is attached to Pin via the -appdebug switch, which gives the debugger a chance to stop execution of the application when it receives the replayed context change. (Whether this happens depends on the CONTEXT_CHANGE_REASON, and the expected behavior of the debugger on different platforms).

PIN_ReplayContextChange() does not return to its caller. If the to parameter is not NULL, execution resumes at that context after it has been potentially modified by the tool's context-changed call-back. If reason is CONTEXT_CHANGE_REASON_FATALSIGNAL, Pin emulates a fatal signal and execution terminates gracefully after calling the tool's Fini functions.

This API can be called from an analysis routine or a replacement routine, but not from a callback.

Parameters

[in]	tid	The ID of the calling thread.
[in]	from	The register state prior to the context change (e.g. the register state at the point when the signal is received for CONTEXT_CHANGE_REASON_SIGNAL).
[in]	to	The register state immediately after the context change. This should be NULL for CONTEXT_CHANGE_REASON_FATALSIGNAL.
[in]	reason	The type of the context change.
[in]	info	Additional information, depending on reason. (Ignored for reason codes not listed below.) CONTEXT_CHANGE_REASON_FATALSIGNAL: The Unix signal number. CONTEXT_CHANGE_REASON_SIGNAL: The Unix signal number. CONTEXT_CHANGE_REASON_EXCEPTION: The Windows exception code.

Returns

This function does not return.

Note

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

Availability:

Mode: JIT
O/S: Linux & Windows
CPU: All

PIN_WasMemoryReservedInLoadTime()

BOOL PIN_WasMemoryReservedInLoadTime

(

)

Return TRUE if PIN was successfully reserved the neccessary memory at application load time (specified on the -reserve_memory knob), and was successfully restricted the memory from the loader (specified on the -restrict_memory knob). It is guaranteed this is the return value is FALSE then none the memory specified in the mentioned knobs was reserved/restricted

Returns

TRUE if all the memory was reserved/restricted

Availability:

Mode: JIT
O/S: Linux
CPU: All