Detailed Description

This API allows the user to debug the application that is running on top of Pin. It also allows a tool to interact with the debugger and provide extended commands to the debugger. Also see the tutorial section on this topic: The Pin Advanced Debugging Extensions.

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.

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.

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.

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 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.

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.

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:

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.