Rework HWCPipe (#11)

- Add a middle layer for specifying counters in a
  platform-independent way
- Create interfaces for CPU/GPU profilers to enhance
  extensibility
- Improve performance when sampling counters
- Avoid unnecessary memory allocations
- Support enabling counters via code or via JSON string

Author: AttilioProvenzano-ARM

.gitignore

@@ -30,3 +30,7 @@
 *.exe
 *.out
 *.app
+
+# Ctags
+.tags
+.tags1

CMakeLists.txt

@@ -1,34 +1,55 @@
+# Copyright (c) 2019, Arm Limited and Contributors
+#
+# SPDX-License-Identifier: MIT
+#
+# Permission is hereby granted, free of charge,
+# to any person obtaining a copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+# and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
 cmake_minimum_required(VERSION 3.6)
 
 project(hwcpipe LANGUAGES C CXX)
 
 set(PROJECT_FILES
-    instrument.h
-    instruments_stats.h
-    measurement.h
-    instruments_stats.cpp)
-
-if(ANDROID)
-    list(APPEND PROJECT_FILES        
-        hwc.hpp
-        hwc_names.hpp
-        mali_counter.h
-        mali_counter.cpp)
-endif()
+    hwcpipe.h
+    cpu_profiler.h
+    gpu_profiler.h
+    value.h
+
+    hwcpipe.cpp)
 
 if(UNIX AND NOT APPLE)
     list(APPEND PROJECT_FILES
-        pmu.h
-        pmu_counter.h
-        
-        pmu.cpp
-        pmu_counter.cpp)
+        vendor/arm/mali/hwc.hpp
+        vendor/arm/mali/hwc_names.hpp
+        vendor/arm/mali/mali_profiler.h
+        vendor/arm/mali/mali_profiler.cpp)
+
+    list(APPEND PROJECT_FILES
+        vendor/arm/pmu/pmu_counter.h
+        vendor/arm/pmu/pmu_profiler.h
+        vendor/arm/pmu/pmu_counter.cpp
+        vendor/arm/pmu/pmu_profiler.cpp)
 endif()
-    
+
 source_group("\\" FILES ${PROJECT_FILES})
 
 add_library(${PROJECT_NAME} STATIC ${PROJECT_FILES})
 
 target_include_directories(${PROJECT_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
 
+target_include_directories(${PROJECT_NAME} PUBLIC third_party)
+
 set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_STANDARD 11)

README.md

@@ -1,77 +1,156 @@
-# HWCPipe
+<!--
+- Copyright (c) 2019, Arm Limited and Contributors
+-
+- SPDX-License-Identifier: MIT
+-
+- Permission is hereby granted, free of charge,
+- to any person obtaining a copy of this software and associated documentation files (the "Software"),
+- to deal in the Software without restriction, including without limitation the rights to
+- use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+- and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+-
+- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+-
+- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+- INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+-
+-->
 
+# HWCPipe
 
 ## Introduction
 
-HWCPipe is an interface to the Arm Hardware Counters, designed to allow for easily interfacing with and reading the hardware counters built into Arm hardware.
-
+HWCPipe is a simple and extensible interface for reading CPU and GPU hardware counters.
 
 ## License
 
-The software is provided under an MIT license. Contributions to this project are accepted under the same license.
+The software is provided under an MIT license.
+
+This project has a third-party dependency, which may have independent licensing:
+
+- [nlohmann/json](https://github.com/nlohmann/json): A JSON library for modern C++
 
+## Contributions
+
+All contributions are accepted under the same [LICENSE](LICENSE).
 
 ## Building
 
-To use HWCPipe, build it as a shared library in your Android Project, to do this it must be integrated into your project with CMake.
+To use HWCPipe, build it as a shared library in your project.
 
+If your project uses CMake, you can add the following to your `CMakeLists.txt`:
 
-## Using
+```
+add_subdirectory(hwcpipe)
+```
 
-### Performance data
+## Usage
 
-In order for performance data to be displayed, profiling needs to be enabled on the device.
-Some devices may disable it by default.
+### Using HWCPipe
 
-Profiling can be enabled via adb:
+Basic usage for HWCPipe is simple:
 
 ```
-adb shell setprop security.perf_harden 0
+// HWCPipe performs automated platform detection for CPU/GPU counters
+hwcpipe::HWCPipe h;
+
+// Start HWCPipe once at the beginning of the profiling session
+h.run();
+
+while (main_loop) {
+    // Call sample() to sample counters with the frequency you need
+    auto measurements = h.sample();
+
+    [...]
+}
+
+// At the end of the profiling session, stop HWCPipe
+h.stop();
 ```
 
-#### Enabling a Counter:
+The `sample` function returns a `Measurements` struct, which can be accessed like this:
+
+```
+// Check if CPU measurements are available
+if (measurements.cpu)
+{
+    // Look for a counter in the map
+    const auto &counter = measurements.cpu->find(CpuCounter::Cycles);
+    if (counter != measurements.cpu->end())
+    {
+        // Get the data stored in the counter, casted to the type you need
+        auto value = cpu_res->counter.get<float>();
+    }
+}
+```
 
-To enable a counter, create either a PMU or Mali counter and then call its start function.
+### Enabling counters
+
+The available counters are specified in the `CpuCounter` and `GpuCounter` enums (`cpu_profiler.h` and `gpu_profiler.h` respectively).
+
+Platforms will support a subset of these counters, which can be queried via:
 
 ```
-Instrument instrument_ = PMUCounter();
-instrument_.start();
+auto cpu_counters = h.cpu_profiler()->supported_counters();
+auto gpu_counters = h.gpu_profiler()->supported_counters()
 ```
 
-#### Reading a Counter:
+You can specify the counters to be enabled in the following ways:
 
-To read a counter, first stop it and then call its measurements function to store results in the MeasurementsMap variable which can then be read from.
+```
+// Enable a default set of counters
+auto h = hwcpipe::HWCPipe();
 
+// Pass sets of CPU and GPU counters to be enabled
+auto h = hwcpipe::HWCPipe({CpuCounter::Cycles, CpuCounter::Instructions}, {GpuCounter::GpuCycles});
+
+// Pass a JSON string
+auto h = hwcpipe::HWCPipe(json);
 ```
-instrument_.stop();
-MeasurementsMap measurements = instrument_.measurements();
+
+The JSON string should be formatted like this:
+
+```
+{
+    "cpu": ["Cycles", "Instructions"],
+    "gpu": ["GpuCycles"]
+}
 ```
 
+Available counter names can be found in `cpu_counter_names` (`cpu_profiler.h`) and `gpu_counter_names` (`gpu_profiler.h`).
+
+For more information regarding Mali counters, see [Mali Performance Counters](https://community.arm.com/graphics/b/blog/posts/mali-bifrost-family-performance-counters).
+
+### Enabling profiling on Android
+
+In order for performance data to be displayed, profiling needs to be enabled on the device.
+Some devices may disable it by default.
+
+Profiling can be enabled via `adb`:
+
+```
+adb shell setprop security.perf_harden 0
+```
 
-## Counters
+## Adding support for a new platform
 
-The counters are separated into two categories: PMU and Mali counters, the available counters are:
+If the counters provided in `CpuCounter` and `GpuCounter` are enough for the new platform,
+the process is simple:
 
-#### PMU
+* Add an implementation of either `CpuProfiler` of `GpuProfiler` (you can use `PmuProfiler` and `MaliProfiler` as references).
+* Add your platform to the automated platform detection in `hwcpipe.cpp`. For consistency in platform detection, the constructor for your platform should throw if the platform is not available.
+* Add your platform to the build system.
 
- - CPU cycles
- - CPU instructions
- - Cache miss ratio
- - Branch miss ratio
+### Adding new counters
 
-#### Mali
+If you need to add new counters to the existing ones, you should update the following variables:
 
- - Timespan
- - GPU cycles
- - Fragment Jobs
- - Vertex/compute jobs
- - L2 cache read lookups
- - L2 cache external reads
- - L2 cache external read stalls
- - L2 cache external read beats
- - L2 cache write lookups
- - L2 cache external writes
- - L2 cache external write stalls
- - L2 cache external write beats
+* Add the counter to the `CpuCounter`/`GpuCounter` enum.
+* Add the counter name to the `cpu_counter_names`/`gpu_counter_names` map (necessary for JSON initialization).
+* Add a description and the unit for your counter to the `cpu_counter_info`/`gpu_counter_info` map.
 
-For more information regarding these counters, see [Mali Performance Counters](https://community.arm.com/graphics/b/blog/posts/mali-bifrost-family-performance-counters).
+The `CpuCounter` and `GpuCounter` enums are meant to be expanded. Platforms must not break if new counters are added.

cpu_profiler.h

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2019 ARM Limited.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#pragma once
+
+#include "value.h"
+
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+
+namespace hwcpipe
+{
+// The available CPU counters. Profiler implementations will support a subset of them.
+enum class CpuCounter
+{
+	Cycles,
+	Instructions,
+	CacheReferences,
+	CacheMisses,
+	BranchInstructions,
+	BranchMisses,
+
+	MaxValue
+};
+
+// Mapping from CPU counter names to enum values. Used for JSON initialization.
+const std::unordered_map<std::string, CpuCounter> cpu_counter_names{
+    {"Cycles", CpuCounter::Cycles},
+    {"Instructions", CpuCounter::Instructions},
+    {"CacheReferences", CpuCounter::CacheReferences},
+    {"CacheMisses", CpuCounter::CacheMisses},
+    {"BranchInstructions", CpuCounter::BranchInstructions},
+    {"BranchMisses", CpuCounter::BranchMisses},
+};
+
+// A hash function for CpuCounter values
+struct CpuCounterHash
+{
+	template <typename T>
+	std::size_t operator()(T t) const
+	{
+		return static_cast<std::size_t>(t);
+	}
+};
+
+struct CpuCounterInfo
+{
+	std::string desc;
+	std::string unit;
+};
+
+// Mapping from each counter to its corresponding information (description and unit)
+const std::unordered_map<CpuCounter, CpuCounterInfo, CpuCounterHash> cpu_counter_info{
+    {CpuCounter::Cycles, {"Number of CPU cycles", "cycles"}},
+    {CpuCounter::Instructions, {"Number of CPU instructions", "instructions"}},
+    {CpuCounter::CacheReferences, {"Number of cache references", "references"}},
+    {CpuCounter::CacheMisses, {"Number of cache misses", "misses"}},
+    {CpuCounter::BranchInstructions, {"Number of branch instructions", "instructions"}},
+    {CpuCounter::BranchMisses, {"Number of branch misses", "misses"}},
+};
+
+typedef std::unordered_set<CpuCounter, CpuCounterHash> CpuCounterSet;
+typedef std::unordered_map<CpuCounter, Value, CpuCounterHash>
+    CpuMeasurements;
+
+/** An interface for classes that collect CPU performance data. */
+class CpuProfiler
+{
+  public:
+	virtual ~CpuProfiler() = default;
+
+	// Returns the enabled counters
+	virtual const CpuCounterSet &enabled_counters() const = 0;
+
+	// Returns the counters that the platform supports
+	virtual const CpuCounterSet &supported_counters() const = 0;
+
+	// Sets the enabled counters after initialization
+	virtual void set_enabled_counters(CpuCounterSet counters) = 0;
+
+	// Starts a profiling session
+	virtual void run() = 0;
+
+	// Sample the counters. Returns a map of measurements for the counters
+	// that are both available and enabled.
+	// A profiling session must be running when sampling the counters.
+	virtual const CpuMeasurements &sample() = 0;
+
+	// Stops the active profiling session
+	virtual void stop() = 0;
+};
+
+}        // namespace hwcpipe