1. API

struct libsc_eviction_strategy

Structure containing the access strategy for eviction.

struct libsc_eviction_set_s

Structure containing virtual addresses of an eviction set.

libsc_timestamp_function_t

Timestamp function

struct libsc_s

Structure containing all information of a libsc instance.

int llc_miss_threshold

LLC Miss timing information

int llc_hit_threshold

LLC Hit timing information

libsc_timestamp_function_t timestamp

High-resolution timestamp function

libsc_timer_t

Available sources for high-resolution timestamps

LIBSC_TIMER_NATIVE

Native timer

LIBSC_TIMER_COUNTING_THREAD

Counting thread

LIBSC_TIMER_PERF

Linux perf interface

LIBSC_TIMER_MONOTONIC_CLOCK

Monotonic clock

libsc_t * libsc_init()

Initializes libsc context

Returns

Returns a libsc context

void libsc_cleanup(libsc_t * ctx)

Clean-up libsc context

Parameters
  • ctx – The libsc context

void libsc_flush(libsc_t * ctx, void * addr)

Flushes the given address from the cache

Parameters
  • ctx – The libsc context

  • addr – The address to flush

void libsc_flush_b(libsc_t * ctx, void * addr)

Flushes the given address from the cache (with memory barriers)

Parameters
  • ctx – The libsc context

  • addr – The address to flush

void libsc_access(libsc_t * ctx, void * addr)

Accesses the given address

Parameters
  • ctx – The libsc context

  • addr – The address The address to load

void libsc_access_b(libsc_t * ctx, void * addr)

Accesses the given address (with memory barriers)

Parameters
  • ctx – The libsc context

  • addr – The address

void libsc_barrier_start(libsc_t * ctx)

Begin memory barrier

Parameters
  • ctx – The libsc context

void libsc_barrier_end(libsc_t * ctx)

End memory barrier

Parameters
  • ctx – The libsc context

uint64_t libsc_timestamp(libsc_t * ctx)

Returns the timestamp (depending on the used timer)

Parameters
  • ctx – The libsc context

Returns

The current timestamp

void libsc_measure_start(libsc_t * ctx)

Begin a timing measurement

Parameters
  • ctx – The libsc context

uint64_t libsc_measure_end(libsc_t * ctx)

End a timing measurement

Parameters
  • ctx – The libsc context

Returns

The time that has passed between the begin of the measurement

void libsc_set_timer(libsc_t * ctx, libsc_timer_t timer)

Set the used timer

Parameters
  • ctx – The libsc context

  • timer – The timer to use

int libsc_flush_reload(libsc_t * ctx, void * addr)
Measures the access time to addr to distinguish between a cache hit

and miss and flushes addr

Parameters
  • ctx – The libsc context

  • addr – The address

Returns

1 if the address was in the cache, 0 if the address was not cached

void libsc_calibrate_flush_reload(libsc_t * ctx)

Calibrates the threshold to distinguish between a cache hit and cache miss using Flush+Reload

Parameters
  • ctx – The libsc context

void libsc_speculation_barrier(libsc_t * ctx)

Barrier that is not crossed during speculative execution

Parameters
  • ctx – The libsc context

int libsc_try_start(libsc_t * ctx)

Begin a try/catch block using TSX or signal handling

Parameters
  • ctx – The libsc context

Returns

1 to enter the block

void libsc_try_end(libsc_t * ctx)

Ends the try/catch block

Parameters
  • ctx – The libsc context

void libsc_try_abort(libsc_t * ctx)

Aborts the transaction using TSX or by triggering an exception.

Parameters
  • ctx – The libsc context

int libsc_get_hyperthread(libsc_t * ctx, int logical_core)

Get the sibling hyperthread of the given logical core

Parameters
  • ctx – The libsc context

  • logical_core – The logical core

Returns

The id of the sibling hyperthread or -1

void libsc_pin_to_core(libsc_t * ctx, int pid, int core)

Pins the pid to the given core

Parameters
  • ctx – The libsc context

  • pid – The pid to pin

  • core – The core where pid should be pinned to

int libsc_get_physical_cores(libsc_t * ctx)

Get the number of physical cores

Parameters
  • ctx – The libsc context

Returns

Number of physical cores

int libsc_get_logical_cores(libsc_t * ctx)

Get the number of logical cores

Parameters
  • ctx – The libsc context

Returns

Number of logical cores

int libsc_get_cache_slice(libsc_t * ctx, int paddr)

Returns the cache slice of the given physical address

Parameters
  • ctx – The libsc context

  • paddr – The physical address

Returns

Cache slice of the physical address

int libsc_get_cache_set(libsc_t * ctx, int paddr)

Returns the cache set of the given physical address

Parameters
  • ctx – The libsc context

  • paddr – The physical address

Returns

Cache set of the physical address

int libsc_get_physical_address()

Returns the physical address of the given virtual address

Parameters
  • ctx – The libsc context

  • vaddr – The virtual address

Returns

The corresponding physical address

int libsc_build_eviction_set(libsc_t * ctx, libsc_eviction_set_t * set, int paddr)

Builds an eviction set for the physical address

Parameters
  • ctx – The libsc context

  • set – The built eviction set

  • paddr – The physical address

Returns

0 on success

void libsc_evict(libsc_t * ctx, libsc_eviction_set_t set)

Runs eviction using the given eviction set

Parameters
  • ctx – The libsc context

  • set – The eviction set

int libsc_evict_reload(libsc_t * ctx, void * addr, libsc_eviction_set_t set)

Performs Evict+Reload :param ctx: The libsc context :param addr: The address :param set: The eviction set that should be used :return: 1 if addr was cached

void libsc_prime(libsc_t * ctx, libsc_eviction_set_t set)

Performs the prime step using the given eviction set :param ctx: The libsc context :param set: The eviction set that should be used

int libsc_prime_probe(libsc_t * ctx, libsc_eviction_set_t set)

Performs Prime+Probe: Builds an eviction set for the given address if one does not exist :param ctx: The libsc context :param set: The eviction set :return: The executim time of the probe step

void * libsc_map_file_by_offset(libsc_t * ctx, const char * filename, int offset)

Maps a page of the given file at the defined offset to the programs address space and returns its address.

Note: This function leaks memory.

Parameters
  • ctx – The libsc context The libsc instance

  • filename – The path to the file

  • offset – The offset that should be mounted

Returns

Mapped address or NULL if any error occurs

void * libsc_map_file(libsc_t * ctx, const char * filename, int * filesize)

Maps a the entire file to the programs address space and returns its address.

Note: This function leaks memory.

Parameters
  • ctx – The libsc context The libsc instance

  • filename – The path to the file

  • filesize – Returns the size of the file (if not NULL)

Returns

Mapped address or NULL if any error occurs

int libsc_find_index_of_nth_largest_int(libsc_t * ctx, int * list, int nmemb, int skip)

Finds the index of the nth largest integer in the list

Parameters
  • ctx – The libsc context

  • list – The list

  • nmemb – Number of list entries

  • skip – The index to select

Returns

The index

int libsc_find_index_of_nth_largest_size_t(libsc_t * ctx, int * list, int nmemb, int skip)

Finds the index of the nth largest size_t in the list

Parameters
  • ctx – The libsc context

  • list – The list

  • nmemb – Number of list entries

  • skip – The index to select

Returns

The index

int libsc_wrmsr(libsc_t * ctx, int cpu, uint32_t reg, uint64_t val)

Writes to MSR

Parameters
  • ctx – The libsc context

  • cpu – The core id

  • reg – The register

  • val – The value

Returns

0 on success

int libsc_rdmsr()

Reads from MSR

Parameters
  • ctx – The libsc context

  • cpu – The core id

  • reg – The register

Returns

The value of the register or 0

int libsc_measure_slice()

Calculates the slice id of the address (requires MSR access)

Parameters
  • ctx – The libsc context

  • addr – The addressess

Returns

The slice id

void libsc_cache_encode(libsc_t * ctx, unsigned char value)

Encodes a value into the cache

Parameters
  • ctx – The libsc context

  • value – The value to encode

unsigned char libsc_cache_decode_from_to(libsc_t * ctx, int from, int to)

Decodes the value in a given range from the cache

Parameters
  • ctx – The libsc context

  • from – Range begin

  • to – Range end

Returns

The decoded value

unsigned char libsc_cache_decode(libsc_t * ctx)

Decodes the value from the cache

Parameters
  • ctx – The libsc context

Returns

The decoded value

unsigned char libsc_cache_decode_nonull(libsc_t * ctx)

Decodes the value from the cache (no null version)

Parameters
  • ctx – The libsc context

Returns

The decoded value