lukego/pmu.lua

## pmu.lua
-- This module counts and reports on CPU events such as cache misses,
-- branch mispredictions, utilization of internal CPU resources such
-- as execution units, and so on.
--
-- Hundreds of low-level counters are available. The exact list
-- depends on CPU model. See pmu_cpu.lua for our definitions.
--
-- API:
--
-- profile(fn, event_list) => <printed report>
--   Execute 'fn' and print a measurement report for event_list.
--   This is a simple convenience function over the API below.
--
-- is_available() => true | false, why
--   Return true if hardware performance counters are available.
--   Otherwise return false with a string briefly explaining why.
--
-- setup(event_list)
--   Setup the hardware performance counters to track a given list of
--   events (in addition to the built-in fixed-function counters).
--
--   Return the number of overflowed counters that could not be
--   tracked due to hardware constraints. These will be the last
--   counters in the list.
--
--   Example:
--     setup({"uops_issued.any",
--            "uops_retired.all",
--            "br_inst_retired.conditional",
--            "br_misp_retired.all_branches"}) => 0
--
-- new_counter_set()
--   Return a "counter_set" object that can be used for accumulating events.
--
--   The counter_set will be valid only until the next call to setup().
--
-- switch(counter_set)
--   Switch to a new set of counters to accumulate events in. Has the
--   side-effect of committing the current accumulators to the
--   previous record.
--
--   If counter_set is nil then do not accumulate events.
--
-- to_table(counter_set) => table {eventname = count}
--   Return a table containing the values accumulated in the counter set.
--
-- Example:
--   to_table(cs) =>
--     {
--      -- Fixed-function counters
--      instructions                 = 133973703,
--      cycles                       = 663011188,
--      ref-cycles                   = 664029720,
--      -- General purpose counters selected with setup()
--      uops_issued.any              = 106860997,
--      uops_retired.all             = 106844204,
--      br_inst_retired.conditional  =  26702830,
--      br_misp_retired.all_branches =       419
--     }
--
-- report(counter_set,  auxnames, auxvalues)
--   Print a textual report on the values accumulated in a counter set.
--   Optionally include auxiliary application-level counters. The
--   ratio of each event to each auxiliary counter is also reported.
--
--   Example:
--     report(my_counter_set, {packet = 26700000, breath = 208593})
--   prints output approximately like:
--     EVENT                                   TOTAL     /packet     /breath
--     instructions                      133,973,703       5.000     642.000
--     cycles                            663,011,188      24.000    3178.000
--     ref-cycles                        664,029,720      24.000    3183.000
--     uops_issued.any                   106,860,997       4.000     512.000
--     uops_retired.all                  106,844,204       4.000     512.000
--     br_inst_retired.conditional        26,702,830       1.000     128.000
--     br_misp_retired.all_branches              419       0.000       0.000
--     packet                             26,700,000       1.000     128.000
--     breath                                208,593       0.008       1.000
	-- This module counts and reports on CPU events such as cache misses,
	-- branch mispredictions, utilization of internal CPU resources such
	-- as execution units, and so on.
	--
	-- Hundreds of low-level counters are available. The exact list
	-- depends on CPU model. See pmu_cpu.lua for our definitions.
	--
	-- API:
	--
	-- profile(fn, event_list) => <printed report>
	-- Execute 'fn' and print a measurement report for event_list.
	-- This is a simple convenience function over the API below.
	--
	-- is_available() => true \| false, why
	-- Return true if hardware performance counters are available.
	-- Otherwise return false with a string briefly explaining why.
	--
	-- setup(event_list)
	-- Setup the hardware performance counters to track a given list of
	-- events (in addition to the built-in fixed-function counters).
	--
	-- Return the number of overflowed counters that could not be
	-- tracked due to hardware constraints. These will be the last
	-- counters in the list.
	--
	-- Example:
	-- setup({"uops_issued.any",
	-- "uops_retired.all",
	-- "br_inst_retired.conditional",
	-- "br_misp_retired.all_branches"}) => 0
	--
	-- new_counter_set()
	-- Return a "counter_set" object that can be used for accumulating events.
	--
	-- The counter_set will be valid only until the next call to setup().
	--
	-- switch(counter_set)
	-- Switch to a new set of counters to accumulate events in. Has the
	-- side-effect of committing the current accumulators to the
	-- previous record.
	--
	-- If counter_set is nil then do not accumulate events.
	--
	-- to_table(counter_set) => table {eventname = count}
	-- Return a table containing the values accumulated in the counter set.
	--
	-- Example:
	-- to_table(cs) =>
	-- {
	-- -- Fixed-function counters
	-- instructions = 133973703,
	-- cycles = 663011188,
	-- ref-cycles = 664029720,
	-- -- General purpose counters selected with setup()
	-- uops_issued.any = 106860997,
	-- uops_retired.all = 106844204,
	-- br_inst_retired.conditional = 26702830,
	-- br_misp_retired.all_branches = 419
	-- }
	--
	-- report(counter_set, auxnames, auxvalues)
	-- Print a textual report on the values accumulated in a counter set.
	-- Optionally include auxiliary application-level counters. The
	-- ratio of each event to each auxiliary counter is also reported.
	--
	-- Example:
	-- report(my_counter_set, {packet = 26700000, breath = 208593})
	-- prints output approximately like:
	-- EVENT TOTAL /packet /breath
	-- instructions 133,973,703 5.000 642.000
	-- cycles 663,011,188 24.000 3178.000
	-- ref-cycles 664,029,720 24.000 3183.000
	-- uops_issued.any 106,860,997 4.000 512.000
	-- uops_retired.all 106,844,204 4.000 512.000
	-- br_inst_retired.conditional 26,702,830 1.000 128.000
	-- br_misp_retired.all_branches 419 0.000 0.000
	-- packet 26,700,000 1.000 128.000
	-- breath 208,593 0.008 1.000