Region Specification
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
There are three major ways to specify regions currently to PinPlay logger (assumes the controller switches all have a "log:" prefix)
Values per type
Tokens
Usage Examples: 'record' script with region specification
Here are some examples of command line usage for defining the alarms/events.
Currently, you can specify controller switches to the "record" script in a free form – anything that is not a "--option" is considered a PinPlay logger option and passed verbatim to pinplay-driver.so.
- Simple switches (mainly for backward compatibility with older control manager).
- EVENT_START
-log:skip [default ]
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 - EVENT_STOP
-log:length [default ]
Number of instructions to execute before stopping
-log:stop_address Address and 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
- EVENT_START
- Region controller (mainly used by PinPoints):
![]()
-log:regions:epilog [default 0]
# of instructions in the epilog region
-log:regions:in [default ]
Regions file : format
-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 - Generic "Alarm Chain" switch
The CONTROL_MANAGER exposes a switch: "-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: 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.
Currently, you can specify controller switches to the "record" script in a free form – anything that is not a "--option" is considered a PinPlay logger option and passed verbatim to pinplay-driver.so.
>record –log:control start:address:foo,stop:addres:bar -- start at symbol foo, stop at symbol bar
>record –log:control start:icount:1000000,stop:icount:100000 -- start after 1M instrctions, stop after 100K instructions equivalent to: >sde –skip 1000000 -length 100000 -- >record –log:control precond:ssc-mark:11223344,start:address:foo,stop:addres:bar -- start at symbol foo, only after ssc mark 0x11223344, stop at symbol bar 
>record –log:control start:address:foo,bcast,stop:addres:bar,bcast -- start at symbol foo, process the event for all threads, stop at symbol bar, process the event for all threads.
* this is the tools responsibility to process the events.
>record –log:control start:address:foo:tid0,stop:addres:bar:tid0 -- start at symbol foo, stop at symbol bar but monitor only tid0
>record –log:control precond:icount:200,uniform:800:500:5 -- uniform sampling period
start uniform sampling after 200 instructions;
of 800 instructions with each sample of length 500 instructions. Stop after 5 samples.>record –log:control precond:ssc-mark:11223344,uniform:800:500:5 --
start uniform sampling after ssc mark 0x11223344 instructions.>record –log:control precond:address:foo,precond:address:bar,repeat:2,name:c1 -control start:address:boo,waitfor:c1 -- start at symbol boo only after the sequence foo,bar,foo,bar
>record –log:control start:enter_func:foo,stop:exit_func:foo --
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,Drecord –log:control start:enter_func:foo,stop:exit_func:bar --
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 –log:control start:enter_func:foo,stop:exit_func:foo --
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.