libsel4bench/include/sel4bench/sel4bench.h - 3p/sel4/sel4_libs - Git at Google

 /*
  * Copyright 2017, Data61
  * Commonwealth Scientific and Industrial Research Organisation (CSIRO)
  * ABN 41 687 119 230.
  *
  * This software may be distributed and modified according to the terms of
  * the BSD 2-Clause license. Note that NO WARRANTY is provided.
  * See "LICENSE_BSD2.txt" for details.
  *
  * @TAG(DATA61_BSD)
  */
 #pragma once

 #include <stddef.h>
 #include <stdint.h>

 #include <sel4/sel4.h>
 #include <sel4bench/types.h>
 #include <sel4bench/arch/sel4bench.h>
 #include <utils/attribute.h>
 #include <utils/arith.h>

 /**
  * @file
  *
  * libsel4bench is a library designed to abstract over the performance
  * monitoring counters (PMCs) in modern IA-32 and ARM processors, so that you
  * can measure the performance of your software.  It will also work out whether
  * certain operations need to be done in kernel mode, and perform kernel code
  * injection calls to make them happen. As a result, expect that any library
  * call could potentially result in a syscall. (This is of particular note on
  * the ARM1136, for which even reading the cycle counter must be done in kernel
  * mode.)
  *
  * It also goes out of its way to ensure that there's always a cycle counter
  * available for use. _init() will start this running, and _destroy() will tear
  * it down, if necessary.
  *
  * Notes:
  * - Overflow is completely ignored, even on processors that only support
  *   32-bit counters (and thus where there is space to overflow into). If you
  *   are doing something that might overflow a counter, it's up to you to deal
  *   with that possibility.
  * - Everything is zero-indexed.
  */

 /*
  * CPP constants for events that are common to all architecture
  * variants.
  * Additional events are architecture (and potentially processor) specific.
  * These may be defined in architecture or processor header files.
  */
 static UNUSED event_id_t GENERIC_EVENTS[] = {
     SEL4BENCH_EVENT_CACHE_L1I_MISS,
     SEL4BENCH_EVENT_CACHE_L1D_MISS,
     SEL4BENCH_EVENT_TLB_L1I_MISS,
     SEL4BENCH_EVENT_TLB_L1D_MISS,
     SEL4BENCH_EVENT_EXECUTE_INSTRUCTION,
     SEL4BENCH_EVENT_BRANCH_MISPREDICT,
     SEL4BENCH_EVENT_MEMORY_ACCESS,
 };

 static UNUSED char *GENERIC_EVENT_NAMES[] = {
     "L1 i-cache misses",
     "L1 d-cache misses",
     "L1 i-tlb misses",
     "L1 d-tlb misses",
     "Instructions",
     "Branch mispredict",
     "Memory access",
 };

 static_assert(ARRAY_SIZE(GENERIC_EVENTS) == ARRAY_SIZE(GENERIC_EVENT_NAMES),
               "event names same length as counters");

 /* Number of generic counters */
 #define SEL4BENCH_NUM_GENERIC_EVENTS ARRAY_SIZE(GENERIC_EVENTS)

 /**
  * Initialise the sel4bench library. Nothing else is guaranteed to work, and
  * may produce strange failures, if you don't do this first.
  * Starts the cycle counter, which is guaranteed to run until _destroy() is
  * called.
  */
 static UNUSED void sel4bench_init();

 /**
  * Tear down the sel4bench library. Nothing else is guaranteed to work, and may
  * produce strange failures, after you do this.
  */
 static UNUSED void sel4bench_destroy();

 /**
  * Query the cycle counter. If said counter needs starting, _init() will have
  * taken care of it.
  *
  * @return The current cycle count. This might be since _init(), if the cycle
  *         counter needs explicit starting, or since bootup, if it freewheels.
  */
 static UNUSED ccnt_t sel4bench_get_cycle_count();

 /**
  * Query how many performance counters are supported on this CPU, excluding the
  * cycle counter.
  *
  * @return Processor's available counters.
  */
 static UNUSED seL4_Word sel4bench_get_num_counters();

 /**
  * Query the description of a counter
  * @param counter The counter to query
  * @return An ASCII string prepresentation of the counters description, or NULL
  *         if the counter does not exist.
  */
 const char *sel4bench_get_counter_description(counter_t counter);

 /**
  * Query the value of a counter.
  *
  * @param counter The counter to query.
  * @return The value of the counter.
  */
 static UNUSED ccnt_t sel4bench_get_counter(counter_t counter);

 /**
  * Query the value of a set of counters.
  *
  * @param counters A bitfield indicating which counter(s) to query.
  * @param values   An array of ccnt_t, of length equal to the
  *                 highest counter index to be read (to a maximum of
  *                 sel4bench_get_num_counters()). Each counter to be read
  *                 will be written to its corresponding index in this array.
  * @return The current cycle count, as sel4bench_get_cycle_count()
  */
 static UNUSED ccnt_t sel4bench_get_counters(counter_bitfield_t counters,
                                             ccnt_t *values);

 /**
  * Assign a counter to track a specific event. Events are processor-specific,
  * though some common ones might be exposed through preprocessor constants.
  *
  * @param counter The counter to configure.
  * @param event The event to track.
  */
 static UNUSED void sel4bench_set_count_event(counter_t counter, event_id_t id);

 /**
  * Start counting events on a set of performance counters. The argument is a
  * bitfield detailing that set. (Note that this means the library supports a
  * number of counters less than or equal to the machine word size in bits.)
  *
  * @param counters A bitfield indicating which counter(s) to start.
  */
 static UNUSED void sel4bench_start_counters(counter_bitfield_t counters);

 /**
  * Stop counting events on a set of performance counters. The argument is a
  * bitfield detailing that set. (Note that this means the library supports a
  * number of counters less than or equal to the machine word size in bits.)
  *
  * Some processors (notably, the ARM1136) may not support this operation.
  *
  * @param counters A bitfield indicating which counter(s) to stop.
  */
 static UNUSED void sel4bench_stop_counters(counter_bitfield_t counters);

 /**
  * Reset all performance counters to zero (not including the cycle counter).
  *
  */
 static UNUSED void sel4bench_reset_counters(void);

 /*
  * @return the number benchmark loops required to read a number of events
  */
 static inline int sel4bench_get_num_counter_chunks(seL4_Word n_counters, seL4_Word n_events)
 {
     return DIV_ROUND_UP(n_events, n_counters);
 }

 /*
  * Enable a chunk of the event counters passed in.
  *
  * @param chunk      events is divided into sel4bench_get_num_counter_chunks, determined by
  *                   ceiling(n_events / n_counters).
  * @param n_counters value returned by sel4bench_get_num_counters(), passed in to avoid
  *                         expensive operations multiple times.
  * @return a mask    used to manipulate the counters enabled.
  */
 static inline counter_bitfield_t sel4bench_enable_counters(seL4_Word n_events, event_id_t events[n_events],
                                                            seL4_Word chunk,
                                                            seL4_Word n_counters)
 {
     assert(chunk < sel4bench_get_num_counter_chunks(n_counters, n_events));
     /* This value is passed in as it can be expensive to call, but
      * should not be different to the returned function result */
     assert(n_counters == sel4bench_get_num_counters());
     counter_bitfield_t mask = 0;

     for (seL4_Word i = 0; i < n_counters; i++) {
         seL4_Word counter = chunk * n_counters + i;
         if (counter >= n_events) {
             break;
         }
         sel4bench_set_count_event(i, events[counter]);
         mask |= BIT(i);
     }

     sel4bench_reset_counters();
     sel4bench_start_counters(mask);
     return mask;
 }

 /*
  * Read and stop the counters set in mask.
  *
  * @param chunk      as passed to sel4bench_enable_counters.
  * @param n_counters value returned by sel4bench_get_num_counters(), passed in to avoid
  *                         expensive operations multiple times.
  * @param mask       returned by sel4bench_enable_counters.
  * @param results    array of counter results. Must match the size of n_events as passed to
  *                   sel4bench_enable_counters.
  */
 static inline void sel4bench_read_and_stop_counters(counter_bitfield_t mask, seL4_Word chunk, seL4_Word n_counters,
                                                     ccnt_t results[])
 {
     sel4bench_get_counters(mask, &results[chunk * n_counters]);
     sel4bench_stop_counters(mask);
 }

 /* shortcut for calling sel4bench_enable_counters on the GENERIC_EVENTS supplied by all platforms in
  * libsel4bench */
 static inline counter_bitfield_t sel4bench_enable_generic_counters(seL4_Word chunk, seL4_Word n_counters)
 {
     return sel4bench_enable_counters(SEL4BENCH_NUM_GENERIC_EVENTS, GENERIC_EVENTS, chunk, n_counters);
 }

 /* shortcut for calling sel4bench_enable_counters on the GENERIC_EVENTS supplied by all platforms in
  * libsel4bench */
 static inline int sel4bench_get_num_generic_counter_chunks(seL4_Word n_counters)
 {
     return sel4bench_get_num_counter_chunks(n_counters, SEL4BENCH_NUM_GENERIC_EVENTS);
 }
	/*
	* Copyright 2017, Data61
	* Commonwealth Scientific and Industrial Research Organisation (CSIRO)
	* ABN 41 687 119 230.
	*
	* This software may be distributed and modified according to the terms of
	* the BSD 2-Clause license. Note that NO WARRANTY is provided.
	* See "LICENSE_BSD2.txt" for details.
	*
	* @TAG(DATA61_BSD)
	*/
	#pragma once

	#include <stddef.h>
	#include <stdint.h>

	#include <sel4/sel4.h>
	#include <sel4bench/types.h>
	#include <sel4bench/arch/sel4bench.h>
	#include <utils/attribute.h>
	#include <utils/arith.h>

	/**
	* @file
	*
	* libsel4bench is a library designed to abstract over the performance
	* monitoring counters (PMCs) in modern IA-32 and ARM processors, so that you
	* can measure the performance of your software. It will also work out whether
	* certain operations need to be done in kernel mode, and perform kernel code
	* injection calls to make them happen. As a result, expect that any library
	* call could potentially result in a syscall. (This is of particular note on
	* the ARM1136, for which even reading the cycle counter must be done in kernel
	* mode.)
	*
	* It also goes out of its way to ensure that there's always a cycle counter
	* available for use. _init() will start this running, and _destroy() will tear
	* it down, if necessary.
	*
	* Notes:
	* - Overflow is completely ignored, even on processors that only support
	* 32-bit counters (and thus where there is space to overflow into). If you
	* are doing something that might overflow a counter, it's up to you to deal
	* with that possibility.
	* - Everything is zero-indexed.
	*/

	/*
	* CPP constants for events that are common to all architecture
	* variants.
	* Additional events are architecture (and potentially processor) specific.
	* These may be defined in architecture or processor header files.
	*/
	static UNUSED event_id_t GENERIC_EVENTS[] = {
	SEL4BENCH_EVENT_CACHE_L1I_MISS,
	SEL4BENCH_EVENT_CACHE_L1D_MISS,
	SEL4BENCH_EVENT_TLB_L1I_MISS,
	SEL4BENCH_EVENT_TLB_L1D_MISS,
	SEL4BENCH_EVENT_EXECUTE_INSTRUCTION,
	SEL4BENCH_EVENT_BRANCH_MISPREDICT,
	SEL4BENCH_EVENT_MEMORY_ACCESS,
	};

	static UNUSED char *GENERIC_EVENT_NAMES[] = {
	"L1 i-cache misses",
	"L1 d-cache misses",
	"L1 i-tlb misses",
	"L1 d-tlb misses",
	"Instructions",
	"Branch mispredict",
	"Memory access",
	};

	static_assert(ARRAY_SIZE(GENERIC_EVENTS) == ARRAY_SIZE(GENERIC_EVENT_NAMES),
	"event names same length as counters");

	/* Number of generic counters */
	#define SEL4BENCH_NUM_GENERIC_EVENTS ARRAY_SIZE(GENERIC_EVENTS)

	/**
	* Initialise the sel4bench library. Nothing else is guaranteed to work, and
	* may produce strange failures, if you don't do this first.
	* Starts the cycle counter, which is guaranteed to run until _destroy() is
	* called.
	*/
	static UNUSED void sel4bench_init();

	/**
	* Tear down the sel4bench library. Nothing else is guaranteed to work, and may
	* produce strange failures, after you do this.
	*/
	static UNUSED void sel4bench_destroy();

	/**
	* Query the cycle counter. If said counter needs starting, _init() will have
	* taken care of it.
	*
	* @return The current cycle count. This might be since _init(), if the cycle
	* counter needs explicit starting, or since bootup, if it freewheels.
	*/
	static UNUSED ccnt_t sel4bench_get_cycle_count();

	/**
	* Query how many performance counters are supported on this CPU, excluding the
	* cycle counter.
	*
	* @return Processor's available counters.
	*/
	static UNUSED seL4_Word sel4bench_get_num_counters();

	/**
	* Query the description of a counter
	* @param counter The counter to query
	* @return An ASCII string prepresentation of the counters description, or NULL
	* if the counter does not exist.
	*/
	const char *sel4bench_get_counter_description(counter_t counter);

	/**
	* Query the value of a counter.
	*
	* @param counter The counter to query.
	* @return The value of the counter.
	*/
	static UNUSED ccnt_t sel4bench_get_counter(counter_t counter);

	/**
	* Query the value of a set of counters.
	*
	* @param counters A bitfield indicating which counter(s) to query.
	* @param values An array of ccnt_t, of length equal to the
	* highest counter index to be read (to a maximum of
	* sel4bench_get_num_counters()). Each counter to be read
	* will be written to its corresponding index in this array.
	* @return The current cycle count, as sel4bench_get_cycle_count()
	*/
	static UNUSED ccnt_t sel4bench_get_counters(counter_bitfield_t counters,
	ccnt_t *values);

	/**
	* Assign a counter to track a specific event. Events are processor-specific,
	* though some common ones might be exposed through preprocessor constants.
	*
	* @param counter The counter to configure.
	* @param event The event to track.
	*/
	static UNUSED void sel4bench_set_count_event(counter_t counter, event_id_t id);

	/**
	* Start counting events on a set of performance counters. The argument is a
	* bitfield detailing that set. (Note that this means the library supports a
	* number of counters less than or equal to the machine word size in bits.)
	*
	* @param counters A bitfield indicating which counter(s) to start.
	*/
	static UNUSED void sel4bench_start_counters(counter_bitfield_t counters);

	/**
	* Stop counting events on a set of performance counters. The argument is a
	* bitfield detailing that set. (Note that this means the library supports a
	* number of counters less than or equal to the machine word size in bits.)
	*
	* Some processors (notably, the ARM1136) may not support this operation.
	*
	* @param counters A bitfield indicating which counter(s) to stop.
	*/
	static UNUSED void sel4bench_stop_counters(counter_bitfield_t counters);

	/**
	* Reset all performance counters to zero (not including the cycle counter).
	*
	*/
	static UNUSED void sel4bench_reset_counters(void);

	/*
	* @return the number benchmark loops required to read a number of events
	*/
	static inline int sel4bench_get_num_counter_chunks(seL4_Word n_counters, seL4_Word n_events)
	{
	return DIV_ROUND_UP(n_events, n_counters);
	}

	/*
	* Enable a chunk of the event counters passed in.
	*
	* @param chunk events is divided into sel4bench_get_num_counter_chunks, determined by
	* ceiling(n_events / n_counters).
	* @param n_counters value returned by sel4bench_get_num_counters(), passed in to avoid
	* expensive operations multiple times.
	* @return a mask used to manipulate the counters enabled.
	*/
	static inline counter_bitfield_t sel4bench_enable_counters(seL4_Word n_events, event_id_t events[n_events],
	seL4_Word chunk,
	seL4_Word n_counters)
	{
	assert(chunk < sel4bench_get_num_counter_chunks(n_counters, n_events));
	/* This value is passed in as it can be expensive to call, but
	* should not be different to the returned function result */
	assert(n_counters == sel4bench_get_num_counters());
	counter_bitfield_t mask = 0;

	for (seL4_Word i = 0; i < n_counters; i++) {
	seL4_Word counter = chunk * n_counters + i;
	if (counter >= n_events) {
	break;
	}
	sel4bench_set_count_event(i, events[counter]);
	mask \|= BIT(i);
	}

	sel4bench_reset_counters();
	sel4bench_start_counters(mask);
	return mask;
	}

	/*
	* Read and stop the counters set in mask.
	*
	* @param chunk as passed to sel4bench_enable_counters.
	* @param n_counters value returned by sel4bench_get_num_counters(), passed in to avoid
	* expensive operations multiple times.
	* @param mask returned by sel4bench_enable_counters.
	* @param results array of counter results. Must match the size of n_events as passed to
	* sel4bench_enable_counters.
	*/
	static inline void sel4bench_read_and_stop_counters(counter_bitfield_t mask, seL4_Word chunk, seL4_Word n_counters,
	ccnt_t results[])
	{
	sel4bench_get_counters(mask, &results[chunk * n_counters]);
	sel4bench_stop_counters(mask);
	}

	/* shortcut for calling sel4bench_enable_counters on the GENERIC_EVENTS supplied by all platforms in
	* libsel4bench */
	static inline counter_bitfield_t sel4bench_enable_generic_counters(seL4_Word chunk, seL4_Word n_counters)
	{
	return sel4bench_enable_counters(SEL4BENCH_NUM_GENERIC_EVENTS, GENERIC_EVENTS, chunk, n_counters);
	}

	/* shortcut for calling sel4bench_enable_counters on the GENERIC_EVENTS supplied by all platforms in
	* libsel4bench */
	static inline int sel4bench_get_num_generic_counter_chunks(seL4_Word n_counters)
	{
	return sel4bench_get_num_counter_chunks(n_counters, SEL4BENCH_NUM_GENERIC_EVENTS);
	}