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_size New 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_size New 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_blocks The 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_ins The 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_size The 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:
start The original program starting address of the range we want to invalidate
end The 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_pc The 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_pc The 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


Generated on Wed Jan 21 02:19:21 2015 for Pin by  doxygen 1.5.1-p1