- Main Page
- Modules
- Classes

- Search for |

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# DEBUGGER_SHELL::ICUSTOM_INSTRUMENTOR Class Reference
[DEBUGGER_SHELL]

`#include <debugger-shell.H>`

List of all members.

## Public Member Functions

virtual VOID | InsertBreakpointBefore (INS ins, BBL bbl, CALL_ORDER order, const std::string &message)=0
virtual VOID | InsertBreakpointAfter (INS ins, BBL bbl, IPOINT ipoint, CALL_ORDER order, const std::string &message)=0
virtual | ~ICUSTOM_INSTRUMENTOR ()=0

## Detailed Description

Some tools may need to define their own analysis routine that stops at a debugger breakpoint. Such tools can define their own class, which derives from ICUSTOM_INSTRUMENTOR. Pass a pointer to that object to STARTUP_ARGUMENTS::_customInstrumentor.

Most tools do not need to override the default instrumentation, so most tools need not use this interface.

## Constructor & Destructor Documentation

DEBUGGER_SHELL::ICUSTOM_INSTRUMENTOR::~ICUSTOM_INSTRUMENTOR | ( |  | ) | `[inline, pure virtual]`

| Destroys the custom instrumentor object.

## Member Function Documentation

virtual VOID DEBUGGER_SHELL::ICUSTOM_INSTRUMENTOR::InsertBreakpointAfter | ( | INS | ins,
|  | BBL | bbl,
|  | IPOINT | ipoint,
|  | CALL_ORDER | order,
|  | const std::string & | message
| ) | `[pure virtual]`

| The debugger shell calls this method to insert a "then" instrumentation call to an analysis routine that stops at a debugger breakpoint _after_ an instruction. The default instrumentation looks like this. Tools that implement this method should insert similar instrumentation:

      VOID InsertBreakpointAfter(INST ins, BBL bbl, IPOINT ipoint, CALL_ORDER order,
          const std::string &message)
      {
          INS_InsertThenCall(ins, ipoint, (AFUNPTR)TriggerBreakpointAfter,
              IARG_CALL_ORDER, order,
              IARG_CONTEXT, IARG_INST_PTR, IARG_THREAD_ID,
              IARG_PTR, message.c_str(),
              IARG_END);
      }

      VOID TriggerBreakpointAfter(CONTEXT *ctxt, ADDRINT pc, THREADID tid, const char *message)
      {
          std::ostringstream os;
          os << message << "\n";
          os << "Breakpoint triggered after instruction at 0x" << std::hex << pc;

          PIN_ApplicationBreakpoint(ctxt, tid, FALSE, os.str());
      }

Parameters:

  `[in]` | ins | Insert the instrumentation after this instruction.
  `[in]` | bbl | The basic block containing ins.
  `[in]` | ipoint | Tells whether to instrument IPOINT_AFTER or IPOINT_TAKEN_BRANCH.
  `[in]` | order | The instrumentation call order to use for the instrumentation.
  `[in]` | message | String telling why the breakpoint is triggered. The string is allocated in permanent storage, so the client can pass it directly to an analysis routine. If the debugger shell removes instrumentation, it will also deallocate this string.

virtual VOID DEBUGGER_SHELL::ICUSTOM_INSTRUMENTOR::InsertBreakpointBefore | ( | INS | ins,
|  | BBL | bbl,
|  | CALL_ORDER | order,
|  | const std::string & | message
| ) | `[pure virtual]`

| The debugger shell calls this method to insert a "then" instrumentation call to an analysis routine that stops at a debugger breakpoint _before_ an instruction. The default instrumentation looks like this. Tools that implement this method should insert similar instrumentation:

      VOID InsertBreakpointBefore(INST ins, BBL bbl, CALL_ORDER order, const std::string &message)
      {
          INS_InsertThenCall(ins, IPOINT_BEFORE, (AFUNPTR)TriggerBreakpointBefore,
              IARG_CALL_ORDER, order,
              IARG_CONTEXT, IARG_THREAD_ID,
              IARG_UINT32, static_cast<UINT32>(RegSkipOne),
              IARG_PTR, message.c_str(),
              IARG_END);
      }

      VOID TriggerBreakpointBefore(CONTEXT *ctxt, THREADID tid, UINT32 regSkipOne, const char *message)
      {
          ADDRINT skipPc = PIN_GetContextReg(ctxt, static_cast<REG>(regSkipOne));
          ADDRINT pc = PIN_GetContextReg(ctxt, REG_INST_PTR);
          if (skipPc == pc)
              return

          PIN_SetContextReg(ctxt, static_cast<REG>(regSkipOne), pc);
          PIN_ApplicationBreakpoint(ctxt, tid, FALSE, message);
      }

See the method ISHELL::GetSkipOneRegister() for the register number to use for RegSkipOne.

Parameters:

  `[in]` | ins | Insert the instrumentation before this instruction.
  `[in]` | bbl | The basic block containing ins.
  `[in]` | order | The instrumentation call order to use for the instrumentation.
  `[in]` | message | String telling why the breakpoint is triggered. The string is allocated in permanent storage, so the client can pass it directly to an analysis routine. If the debugger shell removes instrumentation, it will also deallocate this string.

The documentation for this class was generated from the following file:

- debugger-shell.H