- Main Page
- Modules
- Classes

- Search for |

# 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

VOID | LEVEL_PINCLIENT::CODECACHE_AddCacheInitFunction (CODECACHE_NOARG_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddCacheBlockFunction (CODECACHE_CACHEBLOCK_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddFullCacheFunction (CODECACHE_FULL_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddCacheFlushedFunction (CODECACHE_NOARG_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddCodeCacheEnteredFunction (CODECACHE_ENTEREXIT_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddCodeCacheExitedFunction (CODECACHE_ENTEREXIT_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddTraceLinkedFunction (CODECACHE_LINKED_CALLBACK fun, VOID *val)
VOID | LEVEL_PINCLIENT::CODECACHE_AddTraceUnlinkedFunction (CODECACHE_UNLINKED_CALLBACK fun, VOID *val)
VOID | 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 ()
VOID | 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

VOID LEVEL_PINCLIENT::CODECACHE_AddCacheBlockFunction | ( | CODECACHE_CACHEBLOCK_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID 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.)

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddCacheInitFunction | ( | CODECACHE_NOARG_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddCodeCacheEnteredFunction | ( | CODECACHE_ENTEREXIT_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddCodeCacheExitedFunction | ( | CODECACHE_ENTEREXIT_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddFullCacheFunction | ( | CODECACHE_FULL_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID 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.

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID 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.

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddTraceLinkedFunction | ( | CODECACHE_LINKED_CALLBACK | fun,
|  | VOID * | val
| ) |

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

Note:
  The pin client lock is obtained during the call of this API.

Availability:
  Mode: JIT
  O/S: Linux, Windows & MacOS
  CPU: All

VOID LEVEL_PINCLIENT::CODECACHE_AddTraceUnlinkedFunction | ( | CODECACHE_UNLINKED_CALLBACK | fun,
|  | VOID * | val
| ) |

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

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