Classes
struct	DEBUG_CONNECTION_INFO

struct	DEBUG_MODE

Typedefs
typedef BOOL(*	LEVEL_PINCLIENT::DEBUG_INTERPRETER_CALLBACK) (THREADID threadIndex, CONTEXT ctxt, const std::string &cmd, std::string reply, VOID *v)

typedef BOOL(*	LEVEL_PINCLIENT::DEBUG_BREAKPOINT_CALLBACK) (ADDRINT addr, UINT size, BOOL insert, VOID *v)

Enumerations
enum	DEBUG_STATUS { DEBUG_STATUS_DISABLED, DEBUG_STATUS_UNCONNECTABLE, DEBUG_STATUS_UNCONNECTED, DEBUG_STATUS_CONNECTED }

enum	DEBUG_CONNECTION_TYPE { DEBUG_CONNECTION_TYPE_NONE, DEBUG_CONNECTION_TYPE_TCP_SERVER, DEBUG_CONNECTION_TYPE_TCP_CLIENT }

enum	DEBUGGER_TYPE { DEBUGGER_TYPE_UNKNOWN, DEBUGGER_TYPE_GDB, DEBUGGER_TYPE_LLDB, DEBUGGER_TYPE_IDB, DEBUGGER_TYPE_VISUAL_STUDIO_VSDBG, DEBUGGER_TYPE_VISUAL_STUDIO }

enum	DEBUG_MODE_OPTION { DEBUG_MODE_OPTION_NONE = 0, DEBUG_MODE_OPTION_STOP_AT_ENTRY = (1<<0), DEBUG_MODE_OPTION_SILENT = (1<<1), DEBUG_MODE_OPTION_ALLOW_REMOTE = (1<<2) }

Functions
PIN_CALLBACK	LEVEL_PINCLIENT::PIN_AddDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun, VOID *val)

VOID	LEVEL_PINCLIENT::PIN_RemoveDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun)

PIN_CALLBACK	LEVEL_PINCLIENT::PIN_AddBreakpointHandler (DEBUG_BREAKPOINT_CALLBACK fun, VOID *val)

VOID	LEVEL_PINCLIENT::PIN_RemoveBreakpointHandler (DEBUG_BREAKPOINT_CALLBACK fun)

VOID	LEVEL_PINCLIENT::PIN_ResetBreakpointAt (ADDRINT addr)

VOID	LEVEL_PINCLIENT::PIN_ApplicationBreakpoint (const CONTEXT *ctxt, THREADID tid, BOOL waitIfNoDebugger, const std::string &msg)

BOOL	LEVEL_PINCLIENT::PIN_SetDebugMode (const DEBUG_MODE *mode)

DEBUG_STATUS	LEVEL_PINCLIENT::PIN_GetDebugStatus ()

BOOL	LEVEL_PINCLIENT::PIN_GetDebugConnectionInfo (DEBUG_CONNECTION_INFO *info)

DEBUGGER_TYPE	LEVEL_PINCLIENT::PIN_GetDebuggerType ()

BOOL	LEVEL_PINCLIENT::PIN_WaitForDebuggerToConnect (unsigned timeout)

BOOL	LEVEL_PINCLIENT::PIN_GetStoppedThreadPendingToolBreakpoint (THREADID tid, std::string *msg)

BOOL	LEVEL_PINCLIENT::PIN_ChangePendingToolBreakpointOnStoppedThread (THREADID tid, BOOL squash, const std::string &msg)

Detailed Description

Typedef Documentation

◆ DEBUG_BREAKPOINT_CALLBACK

typedef BOOL(* LEVEL_PINCLIENT::DEBUG_BREAKPOINT_CALLBACK) (ADDRINT addr, UINT size, BOOL insert, VOID *v)

Call-back function to handle breakpoint set requests from a debugger.

Once a callback accepted control over a breakpoint at the given address, Pin and PinADX will not stop at that address. The stop responsibility is handled solely by the tool.

However, PinADX does keep track of the breakpoint, in case the tool wants to "reset" the breakpoint and give the control back to PinADX.

Parameters

[in]	addr	The address of the requested breakpoint.
[in]	size	The size of the breakpoint (HW/SW)
[in]	insert	Whether if this is a breakpoint insertion or deletion.
[in]	v	The tool's call-back value.

Returns: TRUE if this callback function takes control over the breakpoint. FALSE if it does not. If FALSE is returned, Pin will call the next registered interpreter to see if it understands cmd.

◆ DEBUG_INTERPRETER_CALLBACK

typedef BOOL(* LEVEL_PINCLIENT::DEBUG_INTERPRETER_CALLBACK) (THREADID threadIndex, CONTEXT *ctxt, const std::string &cmd, std::string *reply, VOID *v)

Call-back function to handle commands from a debugger.

The format of the cmd and reply strings may vary depending on which debugger is connected to Pin. Tools can call PIN_GetDebuggerType() to tell which debugger is connected.

When the debugger is GDB, cmd is the text string that the user types after the "monitor" command and reply is displayed verbatim as a response to the command.

Pin reserves all command strings that start with the prefix "pin " or "pin:". Pin interprets these commands itself and does not pass them on to the tool.

Parameters

[in]	threadIndex	The Pin thread ID of the debugger's "focus" thread.
[in]	ctxt	Application register state of the debugger's "focus" thread. The interpreter can change this state if it handles cmd. When the debugger resumes this thread, it will use the new register state in ctxt.
[in]	cmd	The debugger command.
[out]	reply	Receives the reply to the command, if the interpreter understands cmd.
[in]	v	The tool's call-back value.

Returns: TRUE if this interpreter function understands cmd. FALSE if it does not. If FALSE is returned, Pin will call the next registered interpreter to see if it understands cmd.

Enumeration Type Documentation

◆ DEBUG_CONNECTION_TYPE

enum DEBUG_CONNECTION_TYPE

Possible connection types for an application debugger. The connection type can be specified either via the -appdebug knobs or by PIN_SetDebugMode().

Enumerator
DEBUG_CONNECTION_TYPE_NONE	Application debugging is disabled in this session.
DEBUG_CONNECTION_TYPE_TCP_SERVER	Pin opens a TCP port and waits for a debugger to connect.
DEBUG_CONNECTION_TYPE_TCP_CLIENT	Pin connects to a TCP port opened by the debugger.

◆ DEBUG_MODE_OPTION

enum DEBUG_MODE_OPTION

Options which affect application debugging.

Enumerator
DEBUG_MODE_OPTION_NONE	No options specified.
DEBUG_MODE_OPTION_STOP_AT_ENTRY	If this option is set, Pin stops the application at the first instruction and execution remains stopped until a debugger connects and continues the application. If this option is cleared, the application immediately runs when PIN_StartProgram() is called.
DEBUG_MODE_OPTION_SILENT	If debugging is enabled Pin normally prints a message to the console when PIN_StartProgram() is called which tells the user how to connect a debugger. This option suppresses the message.
DEBUG_MODE_OPTION_ALLOW_REMOTE	By default, Pin only listens for a debugger's TCP connection on the local machine. If this option is enabled, Pin will also listen for a connection from a remote machine.

◆ DEBUG_STATUS

enum DEBUG_STATUS

Possible status codes telling the state of application level debugging.

Enumerator
DEBUG_STATUS_DISABLED	Application debugging is not enabled in this Pin session.
DEBUG_STATUS_UNCONNECTABLE	Application debugging is enabled, but it is too early to allow a debugger to connect.
DEBUG_STATUS_UNCONNECTED	Application debugging is enabled, but no debugger is connected yet.
DEBUG_STATUS_CONNECTED	Application debugging is enabled and a debugger is connected.

◆ DEBUGGER_TYPE

enum DEBUGGER_TYPE

Application debugger types that could be connected to Pin.

Enumerator
DEBUGGER_TYPE_UNKNOWN	No debugger connected, or type is unknown.
DEBUGGER_TYPE_GDB	The GNU debugger.
DEBUGGER_TYPE_LLDB	The LLVM debugger.
DEBUGGER_TYPE_IDB	The Intel debugger.
DEBUGGER_TYPE_VISUAL_STUDIO_VSDBG	Visual Studio via VSDBG.
DEBUGGER_TYPE_VISUAL_STUDIO	Visual Studio via native connection.

Function Documentation

◆ PIN_AddBreakpointHandler()

PIN_CALLBACK LEVEL_PINCLIENT::PIN_AddBreakpointHandler	(	DEBUG_BREAKPOINT_CALLBACK	fun,
		VOID *	val
	)

Register a handler that can intercept breakpoint set/delete commands sent from an application debugger. This API allows a tool to take control over specific breakpoints stop behavior.

A tool may install more than one handler function. Pin calls each one until it reaches an handler that understand the command.

Parameters

[in]	fun	The breakpoint handler function.
[in]	val	Value to pass to the handler function.

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

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

Availability:: Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_AddDebugInterpreter()

PIN_CALLBACK LEVEL_PINCLIENT::PIN_AddDebugInterpreter	(	DEBUG_INTERPRETER_CALLBACK	fun,
		VOID *	val
	)

Register a handler that can interpret commands sent from an application debugger. This API allows a tool to extend the normal set of commands understood by a debugger that is connected to Pin.

A tool may install more than one interpreter function. Pin calls each one until it reaches an interpreter that understand the command.

Parameters

[in]	fun	The debug interpreter function.
[in]	val	Value to pass to the interpreter function.

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

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

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

◆ PIN_ApplicationBreakpoint()

VOID LEVEL_PINCLIENT::PIN_ApplicationBreakpoint	(	const CONTEXT *	ctxt,
		THREADID	tid,
		BOOL	waitIfNoDebugger,
		const std::string &	msg
	)

A tool can call this API to stop execution in an application debugger as though a breakpoint was hit. The ctxt parameter tells the register state that the debugger sees when the application stops. If application level debugging is not enabled in this Pin session, execution does not stop, but resumes immediately at ctxt. Tools can tell if application level debugging is enabled by calling PIN_GetDebugStatus().

The semantics of this API are very similar to PIN_ExecuteAt(). Both APIs abandon the current analysis function and resume execution at a new CONTEXT. The only difference is that PIN_ApplicationBreakpoint() also stops at a breakpoint in the application debugger.

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

When this API is called from an analysis function or replacement function, and if they execute the current routine or instruction being analyzed, then execution will resume at the instrumented routine or instruction and the analysis function will be called again. It is the pintool's responsibility to avoid going into an infinite loop of calls to the analysis function.

The expected format of the msg string may depend on which debugger is connected to Pin. Tools can call PIN_GetDebuggerType() to find the debugger type.

When used with GDB, the msg string is displayed verbatim to the user when the debugger stops. The debugger adds a newline to the end of the string before displaying it.

Parameters

[in]	ctxt	The register state that is reported to the debugger. When the debugger resumes this thread, it resumes execution at this register state (unless the debugger changes the register state).
[in]	tid	The ID of the calling thread.
[in]	waitIfNoDebugger	If waitIfNoDebugger is TRUE and the status is DEBUG_STATUS_UNCONNECTED, PIN_ApplicationBreakpoint() blocks until a debugger connects. Tools can call PIN_GetDebugStatus() to get the status. If waitIfNoDebugger is FALSE or if the status is DEBUG_STATUS_DISABLED or DEBUG_STATUS_UNCONNECTABLE, PIN_ApplicationBreakpoint() resumes immediately at the new context when no debugger is connected.
[in]	msg	Tells the reason why the breakpoint was triggered.

Returns: This API never returns.

Note: The vm 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_ChangePendingToolBreakpointOnStoppedThread()

BOOL LEVEL_PINCLIENT::PIN_ChangePendingToolBreakpointOnStoppedThread	(	THREADID	tid,
		BOOL	squash,
		const std::string &	msg
	)

If the given stopped thread has a pending tool breakpoint, this function can change the message associated with that breakpoint request or it can squash the breakpoint request entirely. The debugger will see the effect of the changed breakpoint after it resumes execution of the thread. If the tool changes the breakpoint message, the debugger will receive the breakpoint event with the new message. If the tool squashes the breakpoint request, the thread will not stop at the breakpoint at all. Instead, it continues executing at the \i ctxt parameter that was passed to PIN_ApplicationBreakpoint().

Parameters

[in]	tid	Pin ID of a stopped thread.
[in]	squash	If TRUE, the breakpoint request is squashed. The msg parameter is ignored in this case.
[in]	msg	The new breakpoint message for this breakpoint request.

Returns: TRUE if thread tid is stopped and has a pending breakpoint from PIN_ApplicationBreakpoint().

◆ PIN_GetDebugConnectionInfo()

BOOL LEVEL_PINCLIENT::PIN_GetDebugConnectionInfo ( DEBUG_CONNECTION_INFO * info )

This function retrieves the information that an application level debugger will need in order to connect to this Pin session.

Parameters

[out] info Receives the connection information.

Returns: TRUE if application level debugging is enabled for this Pin session.

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

◆ PIN_GetDebuggerType()

DEBUGGER_TYPE LEVEL_PINCLIENT::PIN_GetDebuggerType ( )

This function tells the type of application level debugger (if any) that is connected to Pin. If no debugger is connected, returns DEBUGGER_TYPE_UNKNOWN.

Returns: The type of the application level debugger that is connected to Pin.

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

◆ PIN_GetDebugStatus()

DEBUG_STATUS LEVEL_PINCLIENT::PIN_GetDebugStatus ( )

This function tells whether application level debugging is enabled in this Pin session. If so, it tells whether an application debugger is currently connected to Pin.

Returns: A code telling the status of application level debugging.

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

◆ PIN_GetStoppedThreadPendingToolBreakpoint()

BOOL LEVEL_PINCLIENT::PIN_GetStoppedThreadPendingToolBreakpoint	(	THREADID	tid,
		std::string *	msg
	)

Tells whether a stopped thread has called PIN_ApplicationBreakpoint(), but the breakpoint has NOT yet been reported to the debugger. For example, this can occur if two threads call PIN_ApplicationBreakpoint() simultaneously and the debugger has asked Pin to report one debugger event at a time. In this case, Pin reports one breakpoint to the debugger and leaves the other breakpoint pending.

Parameters

[in]	tid	Pin ID of a stopped thread.
[out]	msg	If there is a pending breakpoint and if msg is not NULL, msg receives the breakpoint message.

Returns: TRUE if thread tid is stopped and has a pending breakpoint from PIN_ApplicationBreakpoint().

◆ PIN_RemoveBreakpointHandler()

VOID LEVEL_PINCLIENT::PIN_RemoveBreakpointHandler ( DEBUG_BREAKPOINT_CALLBACK fun )

Remove a previously installed breakpoint handler function.

Parameters

[in] fun The breakpoint handler to remove.

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

Availability:: Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_RemoveDebugInterpreter()

VOID LEVEL_PINCLIENT::PIN_RemoveDebugInterpreter ( DEBUG_INTERPRETER_CALLBACK fun )

Remove a previously installed debug interpreter function.

Parameters

[in] fun The interpreter function to remove.

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_ResetBreakpointAt()

VOID LEVEL_PINCLIENT::PIN_ResetBreakpointAt ( ADDRINT addr )

Resets the breakpoint address, and returns the control back to PinADX.

Parameters

[in] addr The breakpoint address.

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

Availability:: Mode: JIT
O/S: Linux, Windows, macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetDebugMode()

BOOL LEVEL_PINCLIENT::PIN_SetDebugMode ( const DEBUG_MODE * mode )

Set whether application debugging is enabled or disabled in this Pin session and set the debugging mode if debugging is enabled. This API overrides the following knobs if they are specified on the command line:

If the tool calls this API, it must be called before PIN_StartProgram().

Parameters

[in] mode Tells whether application debugging is enabled and specifies the mode. If mode->_tcpClient->_ip is set, this method makes a copy of the string.

Returns: TRUE on success, FALSE on failure or if called after PIN_StartProgram().

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

◆ PIN_WaitForDebuggerToConnect()

BOOL LEVEL_PINCLIENT::PIN_WaitForDebuggerToConnect ( unsigned timeout )

Waits for an application level debugger to connect to this Pin session. This function may only be called after PIN_StartProgram(). If the debugger status is DEBUG_STATUS_DISABLED or DEBUG_STATUS_UNCONNECTABLE, it returns FALSE immediately.

After a successful return, an application level debugger is connected to Pin. The debugger will stop the application soon, but there is no guarantee that this will happen immediately after this API returns. If the tool wants to guarantee an immediate stop, it should call PIN_ApplicationBreakpoint().

Parameters

[in] timeout A timeout value (milliseconds). This function returns (with FALSE) if a debugger has not connected by the end of the timeout period. A timeout value of zero means wait forever.

Returns: TRUE if an application level debugger is connected.

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

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ DEBUG_BREAKPOINT_CALLBACK

◆ DEBUG_INTERPRETER_CALLBACK

Enumeration Type Documentation

◆ DEBUG_CONNECTION_TYPE

◆ DEBUG_MODE_OPTION

◆ DEBUG_STATUS

◆ DEBUGGER_TYPE

Function Documentation

◆ PIN_AddBreakpointHandler()

◆ PIN_AddDebugInterpreter()

◆ PIN_ApplicationBreakpoint()

◆ PIN_ChangePendingToolBreakpointOnStoppedThread()

◆ PIN_GetDebugConnectionInfo()

◆ PIN_GetDebuggerType()

◆ PIN_GetDebugStatus()

◆ PIN_GetStoppedThreadPendingToolBreakpoint()

◆ PIN_RemoveBreakpointHandler()

◆ PIN_RemoveDebugInterpreter()

◆ PIN_ResetBreakpointAt()

◆ PIN_SetDebugMode()

◆ PIN_WaitForDebuggerToConnect()