Pin
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Typedefs | Functions
Code Cache API

Typedefs

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_NOARG_CALLBACK )()
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_CACHEBLOCK_CALLBACK )(USIZE new_block_size)
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_FULL_CALLBACK )(USIZE trace_size, USIZE stub_size)
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_ENTEREXIT_CALLBACK )(ADDRINT cache_pc)
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_LINKED_CALLBACK )(ADDRINT branch_pc, ADDRINT target_pc)
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_UNLINKED_CALLBACK )(ADDRINT branch_pc, ADDRINT stub_pc)
 
typedef VOID(* LEVEL_PINCLIENT::CODECACHE_TRACEINVALIDATED_CALLBACK )(ADDRINT orig_pc, ADDRINT cache_pc, BOOL success)
 

Functions

PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheInitFunction (CODECACHE_NOARG_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheBlockFunction (CODECACHE_CACHEBLOCK_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddFullCacheFunction (CODECACHE_FULL_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheFlushedFunction (CODECACHE_NOARG_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCodeCacheEnteredFunction (CODECACHE_ENTEREXIT_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCodeCacheExitedFunction (CODECACHE_ENTEREXIT_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceLinkedFunction (CODECACHE_LINKED_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceUnlinkedFunction (CODECACHE_UNLINKED_CALLBACK fun, VOID *val)
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceInvalidatedFunction (CODECACHE_TRACEINVALIDATED_CALLBACK fun, VOID *val)
 
UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateTraceAtProgramAddress (ADDRINT app_pc)
 
UINT32 LEVEL_PINCLIENT::CODECACHE_CodeMemReserved ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_DirectoryMemUsed ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_CodeMemUsed ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_ExitStubBytes ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_LinkBytes ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_CacheSizeLimit ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_BlockSize ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_NumTracesInCache ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_NumExitStubsInCache ()
 
BOOL LEVEL_PINCLIENT::CODECACHE_CreateNewCacheBlock (USIZE block_size)
 
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeCacheLimit (USIZE cache_size)
 
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeBlockSize (USIZE block_size)
 
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxInsPerTrace (UINT32 max_ins)
 
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxBblsPerTrace (UINT32 max_basic_blocks)
 
BOOL LEVEL_PINCLIENT::CODECACHE_FlushCache ()
 
UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateRange (ADDRINT start, ADDRINT end)
 
ADDRINT LEVEL_PINCLIENT::INS_CodeCacheAddress (INS ins)
 
ADDRINT LEVEL_PINCLIENT::BBL_CodeCacheAddress (BBL bbl)
 
ADDRINT LEVEL_PINCLIENT::TRACE_CodeCacheAddress (TRACE trace)
 
USIZE LEVEL_PINCLIENT::INS_CodeCacheSize (INS ins)
 
USIZE LEVEL_PINCLIENT::BBL_CodeCacheSize (BBL bbl)
 
USIZE LEVEL_PINCLIENT::TRACE_CodeCacheSize (TRACE trace)
 
ADDRINT LEVEL_PINCLIENT::CODECACHE_OriginalAddress (ADDRINT cache_pc)
 
USIZE LEVEL_PINCLIENT::PIN_MemoryAllocatedForPin ()
 
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceInsertedFunction (TRACE_INSTRUMENT_CALLBACK fun, VOID *val)
 

Detailed Description

This API allows the user to inspect Pin's code cache and/or alter the code cache replacement policy. For example, to alter the replacement policy, a user can register a routine that is called anytime the cache is full.
APIs from this group are available in any thread, including any internal thread spawned by the tool.

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_CACHEBLOCK_CALLBACK)(USIZE new_block_size)

Call back function when Pin's code cache adds a new cache block

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_ENTEREXIT_CALLBACK)(ADDRINT cache_pc)

Call back function when control enters or exits code cache

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_FULL_CALLBACK)(USIZE trace_size, USIZE stub_size)

Call back function when Pin's code cache is full

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_LINKED_CALLBACK)(ADDRINT branch_pc, ADDRINT target_pc)

Call back function when a trace is linked

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_NOARG_CALLBACK)()

Call back function that passes no arguments

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_TRACEINVALIDATED_CALLBACK)(ADDRINT orig_pc, ADDRINT cache_pc, BOOL success)

Call back function when Pin removes a region from the cache

typedef VOID(* LEVEL_PINCLIENT::CODECACHE_UNLINKED_CALLBACK)(ADDRINT branch_pc, ADDRINT stub_pc)

Call back function when a trace is unlinked

Function Documentation

ADDRINT LEVEL_PINCLIENT::BBL_CodeCacheAddress ( BBL  bbl)

This routine determines the starting code cache address of a basic block (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Code Cache Address
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
USIZE LEVEL_PINCLIENT::BBL_CodeCacheSize ( BBL  bbl)

This routine determines the code cache footprint of a basic block (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Size of the basic block in the code cache
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheBlockFunction ( CODECACHE_CACHEBLOCK_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever a new cache block is formed.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheFlushedFunction ( CODECACHE_NOARG_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever the cache is physically flushed. Note that this event may occur later than the point at which the flush was first requested, either because we were in an analysis routine so it wasn't safe to flush, or because we are running a multithreaded application and we needed to wait for all threads to move out of the traces they were executing before we could flush. (But rest assured that no traces were entered between the time that the flush was requested and when this callback occurs.)

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCacheInitFunction ( CODECACHE_NOARG_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called once, when the code cache is first formed.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCodeCacheEnteredFunction ( CODECACHE_ENTEREXIT_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever control enters the code cache.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddCodeCacheExitedFunction ( CODECACHE_ENTEREXIT_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever control exits the code cache.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddFullCacheFunction ( CODECACHE_FULL_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever the cache fills up.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceInsertedFunction ( TRACE_INSTRUMENT_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever a trace is placed in the code cache.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceInvalidatedFunction ( CODECACHE_TRACEINVALIDATED_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever a trace is invalidated in the code cache. (This means the trace will never be executed again, but the space is not reclaimed until a full code cache flush.

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceLinkedFunction ( CODECACHE_LINKED_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever a trace is linked (backpatched)

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
PIN_CALLBACK LEVEL_PINCLIENT::CODECACHE_AddTraceUnlinkedFunction ( CODECACHE_UNLINKED_CALLBACK  fun,
VOID *  val 
)

Adds a function that gets called whenever a trace is unlinked (unpatched)

Returns
PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties
Note
The pin client lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_BlockSize ( )
Returns
Default size (in bytes) of code cache allocation units (code cache blocks)
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_CacheSizeLimit ( )
Returns
Current limit imposed on the memory allowed for storing traces and exit stubs
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeBlockSize ( USIZE  block_size)
Parameters
block_sizeNew default size for all future code cache blocks (regions)
Returns
True on successful change of default cache block size
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeCacheLimit ( USIZE  cache_size)

Define a new limit to code cache size. The requested size will be rounded up to the nearest multiplication of the cache block size. See CODECACHE_ChangeBlockSize on changing the block size, and CODECACHE_CacheSizeLimit for checking the actual size limit.

Parameters
cache_sizeNew code cache size limit
Returns
True on successful change of max code cache size
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxBblsPerTrace ( UINT32  max_basic_blocks)
Parameters
max_basic_blocksThe new limit of BBs per trace
Returns
True on successful change of basic block limit per trace
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxInsPerTrace ( UINT32  max_ins)
Parameters
max_insThe new limit of instructions per trace
Returns
True on successful change of instruction limit per trace
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_CodeMemReserved ( )
Returns
Memory size (bytes) reserved for code caching (traces and exit stubs)
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_CodeMemUsed ( )
Returns
Bytes of code cache currently occupied by traces and exit stubs
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_CreateNewCacheBlock ( USIZE  block_size)
Parameters
block_sizeThe size (in bytes) of the new code cache block (region)
Returns
True on successful generation of a new code cache block
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_DirectoryMemUsed ( )
Returns
Memory size (bytes) of the code cache directory data structures Note that this is a lower bound, as it is difficult to get an accurate account for the size of all of the data structures.
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_ExitStubBytes ( )
Returns
Bytes of code cache currently occupied exit stubs
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
BOOL LEVEL_PINCLIENT::CODECACHE_FlushCache ( )

This routine flushes the entire cache. We do not need to remove any links, as they will be flushed with the cache.

Returns
Boolean success if the given cache was successfully flushed
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateRange ( ADDRINT  start,
ADDRINT  end 
)

This routine unlinks and invalidates any traces in the code cache that correspond to any code in the given source program address range [start,end]

Parameters
startThe original program starting address of the range we want to invalidate
endThe original program ending address (inclusive) of the range we want to invalidate
Returns
Number of Traces Invalidated
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateTraceAtProgramAddress ( ADDRINT  app_pc)

Invalidates any traces starting at the given program address. Note: More than one trace may correspond to a single program address due to register allocation

Parameters
app_pcThe original program address (must be a trace head)
Returns
The number of traces sucessfully invalidated
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_LinkBytes ( )
Returns
Bytes of cache directory currently occupied by links
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_NumExitStubsInCache ( )
Returns
Number of exit stubs in the entire code cache
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
UINT32 LEVEL_PINCLIENT::CODECACHE_NumTracesInCache ( )
Returns
Number of traces in the entire code cache
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
ADDRINT LEVEL_PINCLIENT::CODECACHE_OriginalAddress ( ADDRINT  cache_pc)

This routine returns the original application address associated with the given code cache address.

Parameters
cache_pcThe address of the trace in the code cache (any address, not just start of trace)
Returns
The original application address if it exists; zero is returned if no application address corresponds with the given code cache address.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
ADDRINT LEVEL_PINCLIENT::INS_CodeCacheAddress ( INS  ins)

This routine determines the code cache address of any given instruction (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Code Cache Address
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
USIZE LEVEL_PINCLIENT::INS_CodeCacheSize ( INS  ins)

This routine determines the code cache footprint of an instruction (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Size of the instrution in the code cache
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
USIZE LEVEL_PINCLIENT::PIN_MemoryAllocatedForPin ( )

This routine returns the amount (in bytes) of memory currently allocated by Pin for all internal structures and data. This is an accurate representation tracked through mmap calls.

Returns
Bytes of allocated memory
Note
The vm lock is obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All
ADDRINT LEVEL_PINCLIENT::TRACE_CodeCacheAddress ( TRACE  trace)

This routine determines the starting code cache address of a trace (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Code Cache Address
USIZE LEVEL_PINCLIENT::TRACE_CodeCacheSize ( TRACE  trace)

This routine determines the code cache footprint of a trace. If instrumentation is inlined into the trace, the footprint will include that space. (Note: Only valid after code cache space has been allocated for this trace - normally after the instrumentation phase.)

Returns
Size of the trace in the code cache
Availability:
Mode: JIT
O/S: Linux, Windows & MacOS
CPU: All