michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef perf_jsperf_h
michael@0: #define perf_jsperf_h
michael@0: 
michael@0: #include "jstypes.h"
michael@0: 
michael@0: #include "js/TypeDecls.h"
michael@0: #include "js/Utility.h"
michael@0: 
michael@0: namespace JS {
michael@0: 
michael@0: /*
michael@0:  * JS::PerfMeasurement is a generic way to access detailed performance
michael@0:  * measurement APIs provided by your operating system.  The details of
michael@0:  * exactly how this works and what can be measured are highly
michael@0:  * system-specific, but this interface is (one hopes) implementable
michael@0:  * on top of all of them.
michael@0:  *
michael@0:  * To use this API, create a PerfMeasurement object, passing its
michael@0:  * constructor a bitmask indicating which events you are interested
michael@0:  * in.  Thereafter, Start() zeroes all counters and starts timing;
michael@0:  * Stop() stops timing again; and the counters for the events you
michael@0:  * requested are available as data values after calling Stop().  The
michael@0:  * object may be reused for many measurements.
michael@0:  */
michael@0: class JS_FRIEND_API(PerfMeasurement)
michael@0: {
michael@0:   protected:
michael@0:     // Implementation-specific data, if any.
michael@0:     void* impl;
michael@0: 
michael@0:   public:
michael@0:     /*
michael@0:      * Events that may be measured.  Taken directly from the list of
michael@0:      * "generalized hardware performance event types" in the Linux
michael@0:      * perf_event API, plus some of the "software events".
michael@0:      */
michael@0:     enum EventMask {
michael@0:         CPU_CYCLES          = 0x00000001,
michael@0:         INSTRUCTIONS        = 0x00000002,
michael@0:         CACHE_REFERENCES    = 0x00000004,
michael@0:         CACHE_MISSES        = 0x00000008,
michael@0:         BRANCH_INSTRUCTIONS = 0x00000010,
michael@0:         BRANCH_MISSES       = 0x00000020,
michael@0:         BUS_CYCLES          = 0x00000040,
michael@0:         PAGE_FAULTS         = 0x00000080,
michael@0:         MAJOR_PAGE_FAULTS   = 0x00000100,
michael@0:         CONTEXT_SWITCHES    = 0x00000200,
michael@0:         CPU_MIGRATIONS      = 0x00000400,
michael@0: 
michael@0:         ALL                 = 0x000007ff,
michael@0:         NUM_MEASURABLE_EVENTS  = 11
michael@0:     };
michael@0: 
michael@0:     /*
michael@0:      * Bitmask of events that will be measured when this object is
michael@0:      * active (between Start() and Stop()).  This may differ from the
michael@0:      * bitmask passed to the constructor if the platform does not
michael@0:      * support measuring all of the requested events.
michael@0:      */
michael@0:     const EventMask eventsMeasured;
michael@0: 
michael@0:     /*
michael@0:      * Counters for each measurable event.
michael@0:      * Immediately after one of these objects is created, all of the
michael@0:      * counters for enabled events will be zero, and all of the
michael@0:      * counters for disabled events will be uint64_t(-1).
michael@0:      */
michael@0:     uint64_t cpu_cycles;
michael@0:     uint64_t instructions;
michael@0:     uint64_t cache_references;
michael@0:     uint64_t cache_misses;
michael@0:     uint64_t branch_instructions;
michael@0:     uint64_t branch_misses;
michael@0:     uint64_t bus_cycles;
michael@0:     uint64_t page_faults;
michael@0:     uint64_t major_page_faults;
michael@0:     uint64_t context_switches;
michael@0:     uint64_t cpu_migrations;
michael@0: 
michael@0:     /*
michael@0:      * Prepare to measure the indicated set of events.  If not all of
michael@0:      * the requested events can be measured on the current platform,
michael@0:      * then the eventsMeasured bitmask will only include the subset of
michael@0:      * |toMeasure| corresponding to the events that can be measured.
michael@0:      */
michael@0:     PerfMeasurement(EventMask toMeasure);
michael@0: 
michael@0:     /* Done with this set of measurements, tear down OS-level state. */
michael@0:     ~PerfMeasurement();
michael@0: 
michael@0:     /* Start a measurement cycle. */
michael@0:     void start();
michael@0: 
michael@0:     /*
michael@0:      * End a measurement cycle, and for each enabled counter, add the
michael@0:      * number of measured events of that type to the appropriate
michael@0:      * visible variable.
michael@0:      */
michael@0:     void stop();
michael@0: 
michael@0:     /* Reset all enabled counters to zero. */
michael@0:     void reset();
michael@0: 
michael@0:     /*
michael@0:      * True if this platform supports measuring _something_, i.e. it's
michael@0:      * not using the stub implementation.
michael@0:      */
michael@0:     static bool canMeasureSomething();
michael@0: };
michael@0: 
michael@0: /* Inject a Javascript wrapper around the above C++ class into the
michael@0:  * Javascript object passed as an argument (this will normally be a
michael@0:  * global object).  The JS-visible API is identical to the C++ API.
michael@0:  */
michael@0: extern JS_FRIEND_API(JSObject*)
michael@0:     RegisterPerfMeasurement(JSContext *cx, JS::HandleObject global);
michael@0: 
michael@0: /*
michael@0:  * Given a Value which contains an instance of the aforementioned
michael@0:  * wrapper class, extract the C++ object.  Returns nullptr if the
michael@0:  * Value is not an instance of the wrapper.
michael@0:  */
michael@0: extern JS_FRIEND_API(PerfMeasurement*)
michael@0:     ExtractPerfMeasurement(Value wrapper);
michael@0: 
michael@0: } // namespace JS
michael@0: 
michael@0: #endif /* perf_jsperf_h */