Pintool Regions

Published: 02/10/2015   Last Updated: 02/10/2015

What is a "Region"?

A "region" is a slice of execution of a program. It is demarcated  by dynamic "start" (EVENT_START)  and "stop" (EVENT_STOP) triggers as a program is running.

e.g. the PinPlay logger starts recording a pinball on an EVENT_START and stops recording it on an EVENT_STOP.

Specifying "Region of interest" for Pin-based analyses

Pintools can include $PIN_ROOT/source/tools/InstLib/control_manager.H to define a "CONTROL_MANAGER". See the example usage in $PIN_ROOT/source/tools/InstLibExamples/control.cpp.

CONTROL_MANAGER makes available a number of switches to the pintool (with an optional prefix), that allow specifying "EVENT_START" and "EVENT_STOP" event callbacks to the pintool, and the pintool can then choose to take some action (such as 'enable analysis' or 'disable analysis').

Region triggers from a Pintool:

A Pintool can start/stop regions programmatically  by calling the following CONTROL_MANAGER method:

 //trigger all registered control handlers
 //eventID - the Id of the event
 //tid - the triggering thread 
 //bcast - whether this event affects all threads 
 VOID Fire(EVENT_TYPE eventID, CONTEXT* ctx, VOID * ip, THREADID tid, BOOL bcast);

e.g. the 'gdb_record' script invokes the underlying pinplay-driver tool with "-log:controller_default_start 0" and then the pinplay-driver tool triggers EVENT_START/EVENT_STOP whenever "(gdb) pin record on" and "(gdb) pin record off"commands are issued by the user.

Overview:Command Line Switches

[ Please do not copy-and-paste the commands listed as dashes get messed up. ]

There are three major ways to specify regions currently to PinPlay logger (assumes the controller switches all have a "log:" prefix)

  1. Simple switches (mainly for backward compatibility with older control manager).
    1. EVENT_START
      -log:skip [default ]
       number of instructions to skip
      -log:start_address
      Address and count to trigger a start
      -log:start_category
      Trigger a start on seeing an instruction from this XED ISA category
      -log:start_extension
      Trigger a start on seeing an instruction from this XED ISA extension
      -log:start_int3
      Trigger a start on seeing an 'int 3' instruction,Requires a count argument
      -log:start_itext
      Trigger a start on seeing specified instruction bytes (max 15Bytes=30nibbles)
      -log:start_ssc_mark
      Trigger a start on seeing specified SSC marker -- big-endian hex without an 0x prefix
    2. EVENT_STOP
      -log:length [default ]
      Number of instructions to execute before stopping
      -log:stop_address Address:count to trigger a start
      -log:stop_category Trigger a stop on seeing an instruction from this XED ISA category
      -log:stop_extension Trigger a stop on seeing an instruction from this XED ISA extension
      -log:stop_int3
      Trigger a stop on seeing an 'int 3' instruction,Requires a count argument.
      -log:stop_itext
      Trigger a stop on seeing specified instruction bytes (max 15Bytes=30nibbles)
      -log:stop_ssc_mark
      Trigger a stop on seeing specified SSC marker -- big-endian hex without an 0x prefix
  2. Region controller (mainly used by PinPoints):

    -log:regions:epilog [default 0]
    # of instructions in the epilog region
    -log:regions:in [default ]
    Regions file : format <comment,thread-id,region-id,simulation-region-start-icount,simulation-region-end-icount,region-weight>
    -log:regions:out [default ]
    Output file containing regions skipped due to overlap
    -log:regions:overlap_ok [default 0]
    Allow overlap in regions.
    -log:regions:prolog [default 0]
    # of instructions in the prolog region
    -log:regions:verbose [default 0]
    Print information about regions/events
    -log:regions:warmup [default 0]
    # of instructions in the warm-up region
  3. Generic "Alarm Chain" switch

    The CONTROL_MANAGER exposes a switch: "-<prefix>control", this switch can be specified multiple times

    Each switch defines an “alarm chain” (see description below).

    Alarm chain is a sequence of alarms, where each alarm is activated only after the previous one was fired

    You can set the entire chain to start only after some other chain has finished.

    The switch:
    -log:control [,repeat[:]][,name:][,waitfor:]
    alarm-chain ::= [,]
    alarm ::= ::[:count][:tid][:bcast]
    event ::= start|stop|threadid|precond
    type ::= icount|address|ssc|itext|isa-extension|isa-category|enter_func|exit_func
    ** "precond" is a special event that is not transmitted to the tool and used just for activating the next alarm.

    Values per type

    • icount: int
    • address:
      0x [pc address]
      + [image + offset]
      [symbol]
    • ssc: hex (can be added by Intel compilers using "_SSC_MARK" intrinsics)
    • itext: hex (raw bytes of the instruction)
    • isa-extension: string (the instructions extension as specified by xed)
    • isa-category: string (the instructions category as specified by xed)
    • enter_func: string (bare function name - without namespace and params)
    • exit_func: string (bare function name - without namespace and params)

      Special alarm - Uniform:
    • uniform:<period>:<length>:<count>
    • period: number of instructions before next sampling starts.
    • length: number of instructions to sample.
    • count: number of samples.

    Tokens

    • repeat: #iterations of the chain (when no number provided - execute in endless loop).
    • tid: the thread to monitor, events on other threads are ignored.
    • bcast: inform the tool that the event should be processed for all threads (this behavior is tool specific and it is in the tool's responsibility).
    • name: the name of the chain, other chains can “wait” for this chain to finish before it starts.
    • waitfor: start the chain only after the chain with the specified name has finished.

Usage Examples: 'record' script with region specification

Here are some examples of command line usage for defining the alarms/events.

[ Please do not copy-and-paste the commands listed as dashes get messed up. ]

 

Currently, you can specify controller switches to the "record" script using the swithc "--pintool_options=" a PinPlay logger option and passed verbatim to pinplay-driver.so.

>record --pintool_options="–log:control start:address:foo,stop:addres:bar" -- <app>
start at symbol foo, stop at symbol bar

>record --pintool_options="–log:control start:icount:1000000,stop:icount:100000" -- <app> 
start after 1M instrctions, stop after 100K instructions equivalent to: >sde –skip 1000000 -length 100000 --


>record --pintool_options="–log:control precond:ssc-mark:11223344,start:address:foo,stop:addres:bar" -- <app>
start at symbol foo, only after ssc mark 0x11223344, stop at symbol bar


>record --pintool_options="–log:control start:address:foo,bcast,stop:addres:bar,bcast" -- <app>
start at symbol foo, process the event for all threads, stop at symbol bar, process the event for all threads.
* it is the tool's responsibility to process the events.


>record --pintool_options="–log:control start:address:foo:tid0,stop:addres:bar:tid0" -- <app> 
start at symbol foo, stop at symbol bar but monitor only tid0


>record --pintool_options="–log:control precond:icount:200,uniform:800:500:5:tid0" -- <app>
start uniform sampling after 200 instructions;
uniform sampling period
of 800 instructions with each sample of length 500 instructions. Stop after 5 samples. All counts refer to tid0.

>record --pintool_options="–log:control precond:ssc-mark:11223344,uniform:800:500:5" -- <app>
start uniform sampling after ssc mark 0x11223344 instructions.

>record --pintool_options="–log:control precond:address:foo,precond:address:bar,repeat:2,name:c1 -log:control start:address:boo,waitfor:c1" -- <app>
start at symbol foo only after the sequence foo,bar,foo,bar

>record --pintool_options="–log:control start:enter_func:foo,stop:exit_func:foo" -- <app>
start at beginning of function foo, stop when exiting for function foo
for this call sequence: A->B->foo->C->D capturing functions foo,C,D

>record --pintool_options="–log:control start:enter_func:foo,stop:exit_func:bar" -- <app>
for this call sequence: A->bar->foo->C->bar
start at beginning of function foo, stop when exiting the first bar function
*for exit function event we always refer to the top-most caller.

>record --pintool_options="–log:control start:enter_func:foo,stop:exit_func:foo" -- <app>
for this call sequence: A->foo->foo->foo->foo->C
start at beginning of the first function foo, stop when exiting the first foo function.

 

[ Please do not copy-and-paste the commands listed as dashes get messed up. ]

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.