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)
BOOL	LEVEL_PINCLIENT::CODECACHE_InvalidateTraceAtCacheAddress (ADDRINT cache_pc)
UINT32	LEVEL_PINCLIENT::CODECACHE_MemReserved ()
UINT32	LEVEL_PINCLIENT::CODECACHE_MemUsed ()
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)
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.

---

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 Returns: Code Cache Address

USIZE LEVEL_PINCLIENT::BBL_CodeCacheSize (  BBL  bbl  )

This routine determines the code cache footprint of a basic block Returns: Size of the basic block in the code cache

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

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

VOID LEVEL_PINCLIENT::CODECACHE_AddCacheFlushedFunction (  CODECACHE_NOARG_CALLBACK  fun, VOID *  val )

Adds a function that gets called whenever the cache is actually flushed.

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.

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

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

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

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

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

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

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.

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 it will never be executed again, but the space is not reclaimed until a full code cache flush.

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

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

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

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

UINT32 LEVEL_PINCLIENT::CODECACHE_BlockSize (   )

Returns: Default size (in bytes) of code cache allocation units (code cache blocks)

UINT32 LEVEL_PINCLIENT::CODECACHE_CacheSizeLimit (   )

Returns: Current limit imposed on the memory allowed for storing traces and exit stubs

BOOL LEVEL_PINCLIENT::CODECACHE_ChangeBlockSize (  USIZE  block_size  )

Returns: True on successful change of default cache block size

BOOL LEVEL_PINCLIENT::CODECACHE_ChangeCacheLimit (  USIZE  cache_size  )

Returns: True on successful change of max cache size

BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxBblsPerTrace (  UINT32  max_basic_blocks  )

Returns: True on successful change of basic block limit per trace

BOOL LEVEL_PINCLIENT::CODECACHE_ChangeMaxInsPerTrace (  UINT32  max_ins  )

Returns: True on successful change of instruction limit per trace

BOOL LEVEL_PINCLIENT::CODECACHE_CreateNewCacheBlock (  USIZE  block_size  )

Returns: True on successful generation of a new cache block

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

UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateRange (  ADDRINT  start, ADDRINT  end )

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

BOOL LEVEL_PINCLIENT::CODECACHE_InvalidateTraceAtCacheAddress (  ADDRINT  cache_pc  )

Invalidates the trace starting at the given code cache address Returns: Success if trace exists at location indicated and is invalidated

UINT32 LEVEL_PINCLIENT::CODECACHE_InvalidateTraceAtProgramAddress (  ADDRINT  app_pc  )

Invalidates any traces starting at the given program address Returns: The number of traces sucessfully invalidated

UINT32 LEVEL_PINCLIENT::CODECACHE_MemReserved (   )

Returns: Memory size (bytes) reserved for code caching

UINT32 LEVEL_PINCLIENT::CODECACHE_MemUsed (   )

Returns: Bytes of code cache currently occupied by traces and exit stubs

UINT32 LEVEL_PINCLIENT::CODECACHE_NumExitStubsInCache (   )

Returns: Number of exit stubs in the entire code cache

UINT32 LEVEL_PINCLIENT::CODECACHE_NumTracesInCache (   )

Returns: Number of traces in the entire code cache

ADDRINT LEVEL_PINCLIENT::CODECACHE_OriginalAddress (  ADDRINT  cache_pc  )

This routine returns the original application address associated with the given code cache address. Returns: The original application address if it exists; zero is returned if no application address corresponds with the given code cache address.

ADDRINT LEVEL_PINCLIENT::INS_CodeCacheAddress (  INS  ins  )

This routine determines the code cache address of any given instruction Returns: Code Cache Address

USIZE LEVEL_PINCLIENT::INS_CodeCacheSize (  INS  ins  )

This routine determines the starting code cache address of a trace Returns: Code Cache Address

ADDRINT LEVEL_PINCLIENT::TRACE_CodeCacheAddress (  TRACE  trace  )

This routine determines the starting code cache address of a trace Returns: Code Cache Address

USIZE LEVEL_PINCLIENT::TRACE_CodeCacheSize (  TRACE  trace  )

This routine determines the code cache footprint of a trace Returns: Size of the trace in the code cache

---