- Main Page
- Modules
- Classes

- Search for |

# CONTROLLER

## Modules

| CONTROLLER_LENGTH
| CONTROLLER_START_ADDRESS_GENERIC
| CONTROLLER_START_ADDRESS
| CONTROLLER_START_THREADID
| CONTROLLER_STOP_ADDRESS
| CONTROLLER_STOP_ADDRESS_RELATIVE
| CONTROLLER_FINI
| CONTROLLER_SKIP
| CONTROLLER_UNIFORM
| CONTROLLER_INIT
| CONTROLLER_REGIONS
| CONTROLLER_MULTI
| CONTROLLER_STATS_EVENT_ADDRESS

## Typedefs

typedef VOID(* | INSTLIB::CONTROL_HANDLER )(CONTROL_EVENT, VOID *, CONTEXT *, VOID *, THREADID tid)

## Enumerations

enum | INSTLIB::CONTROL_EVENT { CONTROL_INVALID, INSTLIB::CONTROL_START, INSTLIB::CONTROL_STOP, INSTLIB::CONTROL_THREADID,
INSTLIB::CONTROL_WARMUP_START,
INSTLIB::CONTROL_WARMUP_STOP,
INSTLIB::CONTROL_PROLOG_START,
INSTLIB::CONTROL_PROLOG_STOP,
INSTLIB::CONTROL_EPILOG_START,
INSTLIB::CONTROL_EPILOG_STOP
}

## Detailed Description

It is often desirable to use instrumentation to observe an interval of the execution of a program. Controllers are used to detect the beginning or end of an interval. Some of the methods are instruction counts, or the nth time an address or symbol is executed.

A controller is usually an ALARM with some coordination for stop and start and some built in command line switches.

The example below can be found in InstLibExamples/control.cpp

    #include <iostream>

    #include "pin.H"
    #include "instlib.H"

    using namespace INSTLIB;

    #if defined(__GNUC__)
    #  if defined(__APPLE__)
    #    define ALIGN_LOCK __attribute__ ((aligned(16))) /* apple only supports 16B alignment */
    #  else
    #    define ALIGN_LOCK __attribute__ ((aligned(64)))
    #  endif
    #else
    # define ALIGN_LOCK __declspec(align(64))
    #endif

    LOCALVAR PIN_LOCK  ALIGN_LOCK output_lock;

    // Track the number of instructions executed
    ICOUNT icount;

    // Contains knobs and instrumentation to recognize start/stop points
    CONTROL control("controller_");

    VOID Handler(CONTROL_EVENT ev, VOID * v, CONTEXT * ctxt, VOID * ip, THREADID tid)
    {
        PIN_GetLock(&output_lock, tid+1);

        std::cout << "tid: " << tid << " ";
        std::cout << "ip: "  << ip << " " << icount.Count() ;

        switch(ev)
        {
          case CONTROL_START:
            std::cout << "Start" << endl;
            break;

          case CONTROL_STOP:
            std::cout << "Stop" << endl;
            break;

          case CONTROL_THREADID:
            std::cout << "ThreadID" << endl;
            break;

          default:
            ASSERTX(false);
            break;
        }
        PIN_ReleaseLock(&output_lock);
    }

    INT32 Usage()
    {
        cerr <<
            "This pin tool demonstrates use of CONTROL to identify start/stop points in a program\n"
            "\n";

        cerr << KNOB_BASE::StringKnobSummary() << endl;
        return -1;
    }

    // argc, argv are the entire command line, including pin -t <toolname> -- ...
    int main(int argc, char * argv[])
    {
        if( PIN_Init(argc,argv) )
        {
            return Usage();
        }

        PIN_InitLock(&output_lock);
        icount.Activate();

        // Activate alarm, must be done before PIN_StartProgram
        control.RegisterHandler(Handler, 0, FALSE);
        control.Activate();

        // Start the program, never returns
        PIN_StartProgram();

        return 0;
    }

## Typedef Documentation

typedef VOID(* INSTLIB::CONTROL_HANDLER)(CONTROL_EVENT, VOID *, CONTEXT *, VOID *, THREADID tid)

| Type for generic event handler

## Enumeration Type Documentation

enum INSTLIB::CONTROL_EVENT

| Event that is passed to handler when controller detects the beginning or end of an interval

Enumerator:

  CONTROL_START | Beginning of interval.
  CONTROL_STOP | End of interval.
  CONTROL_THREADID | Capture executing thread id for later processing.
  CONTROL_WARMUP_START | Beginning of warmup region.
  CONTROL_WARMUP_STOP | End of warmup region.
  CONTROL_PROLOG_START | Beginning of prolog region.
  CONTROL_PROLOG_STOP | End of prolog region.
  CONTROL_EPILOG_START | Beginning of epilog region.
  CONTROL_EPILOG_STOP | End of epilog region.