Application Level Debugging API

Classes
struct	DEBUG_CONNECTION_INFO
Typedefs
typedef BOOL(*	LEVEL_PINCLIENT::DEBUG_INTERPRETER_CALLBACK )(THREADID threadIndex, CONTEXT *ctxt, const std::string &cmd, std::string *reply, VOID *v)
Enumerations
enum	DEBUG_STATUS {   DEBUG_STATUS_DISABLED,   DEBUG_STATUS_UNCONNECTED,   DEBUG_STATUS_CONNECTED }
enum	DEBUG_CONNECTION_TYPE {   DEBUG_CONNECTION_TYPE_TCP_SERVER,   DEBUG_CONNECTION_TYPE_TCP_CLIENT }
Functions
VOID	LEVEL_PINCLIENT::PIN_AddDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_RemoveDebugInterpreter (DEBUG_INTERPRETER_CALLBACK fun)
VOID	LEVEL_PINCLIENT::PIN_ApplicationBreakpoint (const CONTEXT *ctxt, THREADID tid, BOOL waitIfNoDebugger, const std::string &msg)
DEBUG_STATUS	LEVEL_PINCLIENT::PIN_GetDebugStatus ()
BOOL	LEVEL_PINCLIENT::PIN_GetDebugConnectionInfo (DEBUG_CONNECTION_INFO *info)
BOOL	LEVEL_PINCLIENT::PIN_WaitForDebuggerToConnect (unsigned timeout)
BOOL	LEVEL_PINCLIENT::PIN_IsActionPending (THREADID tid)

---

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: Debugging the Application while Running Under Pin.

---

Typedef Documentation

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. 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 cmd. [in]  cmd  The debugger command. If the command was entered from GDB, cmd does not include the "monitor" prefix. [out]  reply  Receives the reply to the command, if the interpreter understands cmd. The debugger will display the reply to the user. [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

enum DEBUG_CONNECTION_TYPE

Possible connection types for an application debugger. The connection type is specified via knobs when Pin is started. Enumerator: 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.

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_UNCONNECTED  Application debugging is enabled, but no debugger is connected yet. DEBUG_STATUS_CONNECTED  Application debugging is enabled and a debugger is connected.

---

Function Documentation

VOID 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. Availability: Mode: JIT O/S: Linux CPU: IA-32 and Intel(R) 64 architectures

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

Stop in an external debugger as though a breakpoint was hit. If application level debugging is not enabled in this Pin session, execution does not stop, but resumes immediately at the context specified by ctxt. Tools can tell if application level debugging is enabled by calling PIN_GetDebugStatus(). 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. [in]  tid  The ID of the calling thread. [in]  waitIfNoDebugger  If there is no debugger connected to Pin and waitIfNoDebugger is TRUE, PIN_ApplicationBreakpoint() blocks until a debugger connects. Otherwise, PIN_ApplicationBreakpoint() resumes immediately at the new context when no debugger is connected. Tools can call PIN_GetDebugStatus() to tell if a debugger is connected. [in]  msg  A message that is displayed at the debugger prompt. For example, this could tell the user why a breakpoint was hit. Availability: Mode: JIT O/S: Linux CPU: IA-32 and Intel(R) 64 architectures

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 CPU: IA-32 and Intel(R) 64 architectures

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 CPU: IA-32 and Intel(R) 64 architectures

BOOL LEVEL_PINCLIENT::PIN_IsActionPending (  THREADID  tid  )

This function is useful when an analysis routine might block for an indefinite period of time. In such cases, the analysis code can periodically call PIN_IsActionPending() to see if the thread has some pending action that needs to be handled in the Pin VM. If so, the analysis routine should return back to the VM, either by returning or by calling PIN_ExecuteAt(). Parameters: [in]  tid  The ID of the calling thread. Returns: TRUE if the thread has a pending action in the Pin VM. Availability: Mode: JIT O/S: Linux CPU: IA-32 and Intel(R) 64 architectures

VOID LEVEL_PINCLIENT::PIN_RemoveDebugInterpreter (  DEBUG_INTERPRETER_CALLBACK  fun  )

Remove a previously installed debug interpreter function. Parameters: [in]  fun  The interpreter function to remove. Availability: Mode: JIT O/S: Linux CPU: IA-32 and Intel(R) 64 architectures

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 application level debugging is not enabled on this Pin session, it returns FALSE immediately. 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 CPU: IA-32 and Intel(R) 64 architectures

---