Refactors topdown service to support multiple types of calculations and adds support for Sapphire Rapids

CMakeLists.txt

@@ -82,6 +82,18 @@ add_caliper_option(WITH_VARIORUM  "Enable Variorum support" FALSE)
 add_caliper_option(WITH_UMPIRE    "Enable Umpire statistics support" FALSE)
 add_caliper_option(WITH_CRAYPAT   "Enable CrayPAT region forwarding support" FALSE)
 add_caliper_option(WITH_LDMS      "Enable LDMS forwarder" FALSE)
+add_caliper_option(WITH_PAPI_RDPMC "Declare that PAPI is built to use rdpmc for reading counters. Does nothing if PAPI support is not enabled." TRUE)
+
+if (WITH_PAPI_RDPMC)
+  set(CALIPER_WITH_PAPI_RDPMC TRUE)
+endif ()
+
+
+set(WITH_ARCH "" CACHE STRING "Enable features specific to the provided archspec CPU architecture name")
+if (NOT WITH_ARCH STREQUAL "")
+  string(TOLOWER ${WITH_ARCH} LOWER_WITH_ARCH)
+  set(CALIPER_HAVE_ARCH "${LOWER_WITH_ARCH}")
+endif ()
 
 add_caliper_option(USE_EXTERNAL_GOTCHA "Use pre-installed gotcha instead of building our own" FALSE)
 
@@ -633,6 +645,7 @@ message(STATUS "Build type                : ${CMAKE_BUILD_TYPE}")
 message(STATUS "Compiler                  : ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION} (${CMAKE_CXX_COMPILER})")
 message(STATUS "Python interpreter        : ${Python_EXECUTABLE}")
 message(STATUS "System                    : ${CMAKE_SYSTEM} (${CMAKE_SYSTEM_PROCESSOR})")
+message(STATUS "Architecture              : ${CALIPER_HAVE_ARCH}")
 message(STATUS "Install dir               : ${CMAKE_INSTALL_PREFIX}")
 message(STATUS "Build shared libs         : ${BUILD_SHARED_LIBS}")
 message(STATUS "Build Caliper tools       : ${WITH_TOOLS}")

caliper-config.h.in

@@ -26,6 +26,10 @@
 #cmakedefine CALIPER_HAVE_UMPIRE
 #cmakedefine CALIPER_HAVE_CRAYPAT
 #cmakedefine CALIPER_HAVE_LDMS
+#cmakedefine CALIPER_HAVE_ARCH "@CALIPER_HAVE_ARCH@"
+#ifdef CALIPER_HAVE_PAPI
+#cmakedefine CALIPER_WITH_PAPI_RDPMC
+#endif
 
 #cmakedefine CALIPER_REDUCED_CONSTEXPR_USAGE
 

doc/sphinx/PythonSupport.rst

@@ -0,0 +1,45 @@
+Python support
+==============
+
+Caliper provides Python bindings based on `pybind11 <https://pybind11.readthedocs.io/en/stable/>`_
+for the annotation and :code:`ConfigManager` APIs. To build Caliper with Python support, enable
+the :code:`WITH_PYTHON_BINDINGS` option in the CMake configuration:
+
+.. code-block:: sh
+
+    $ cmake -DWITH_PYTHON_BINDINGS=On ..
+
+Using the Python module
+-----------------------
+
+The Python module requires pybind11 and an installation of Python that both supports
+pybind11 and provides development headers (e.g., :code:`Python.h`) and libraries
+(e.g., :code:`libpython3.8.so`).
+
+The Caliper Python module is installed in either :code:`lib/pythonX.Y/site-packages/` and/or
+:code:`lib64/pythonX.Y/site-packages` in the Caliper installation directory. In these paths,
+:code:`X.Y` corresponds to the major and minor version numbers of the Python installation used.
+Additionally, :code:`lib/` and :code:`lib64/` will be used in accordance with the configuration
+of the Python installed. To better understand the rules for where Python modules are installed, 
+see `this thread <https://discuss.python.org/t/understanding-site-packages-directories/12959>`_
+from the Python Software Foundation Discuss.
+
+To use the Caliper Python module, simply add the directories above to :code:`PYTHONPATH` or
+:code:`sys.path`. Note that the module will be automatically added to :code:`PYTHONPATH` when
+loading the Caliper package with Spack if the :code:`python` variant is enabled.
+The module can then be imported with :code:`import pycaliper`.
+
+Caliper Python API
+------------------
+
+The Caliper Python API supports a significant subset of the C and C++ annotation APIs.
+The simplest options are the :code:`pycaliper.begin_region()` and :code:`pycaliper.end_region()`
+functions. Caliper's Python API also provides the :code:`pycaliper.annotate_function` decorator
+as a higher-level way of annotating functions.
+
+The Python API also supports the Caliper :code:`ConfigManager` API (:doc:`ConfigManagerAPI`).
+The example is examples/apps/py-example.py demonstrates the annotation and
+:code:`ConfigManager` APIs for Python:
+
+.. literalinclude:: ../../examples/apps/py-example.py
+   :language: Python

doc/sphinx/index.rst

@@ -66,6 +66,7 @@ This section lists how-to articles for various use cases.
    SampleProfiling
    ThirdPartyTools
    FortranSupport
+   PythonSupport
 
 Reference documentation
 -------------------------------

src/caliper/ConfigManager.cpp

@@ -7,8 +7,8 @@
 
 #include "caliper/common/Log.h"
 
-#include "../src/common/util/parse_util.h"
 #include "../src/common/util/format_util.h"
+#include "../src/common/util/parse_util.h"
 
 #include "../services/Services.h"
 
@@ -33,50 +33,18 @@ extern const char* builtin_cuda_option_specs;
 extern const char* builtin_rocm_option_specs;
 extern const char* builtin_pcp_option_specs;
 extern const char* builtin_umpire_option_specs;
-extern const char* builtin_papi_option_specs;
 extern const char* builtin_kokkos_option_specs;
 
+extern const char* builtin_papi_hsw_option_specs;
+extern const char* builtin_papi_spr_option_specs;
+
 extern void add_submodule_controllers_and_services();
 
 } // namespace cali
 
 namespace
 {
 
-const char* builtin_option_specs_list[] =
-{
-    builtin_base_option_specs,
-#ifdef CALIPER_HAVE_GOTCHA
-    builtin_gotcha_option_specs,
-#endif
-#ifdef CALIPER_HAVE_MPI
-    builtin_mpi_option_specs,
-#endif
-#ifdef CALIPER_HAVE_OMPT
-    builtin_openmp_option_specs,
-#endif
-#ifdef CALIPER_HAVE_CUPTI
-    builtin_cuda_option_specs,
-#endif
-#if defined(CALIPER_HAVE_ROCTRACER) || defined(CALIPER_HAVE_ROCPROFILER)
-    builtin_rocm_option_specs,
-#endif
-#ifdef CALIPER_HAVE_LIBDW
-    builtin_libdw_option_specs,
-#endif
-#ifdef CALIPER_HAVE_PAPI
-    builtin_papi_option_specs,
-#endif
-#ifdef CALIPER_HAVE_PCP
-    builtin_pcp_option_specs,
-#endif
-#ifdef CALIPER_HAVE_UMPIRE
-    builtin_umpire_option_specs,
-#endif
-    builtin_kokkos_option_specs,
-    nullptr
-};
-
 ChannelController* make_basic_channel_controller(
     const char*                   name,
     const config_map_t&           initial_cfg,
@@ -139,7 +107,8 @@ ConfigManager::arglist_t merge_new_elements(ConfigManager::arglist_t& to, const
             return p.first == v.first;
         });
 
-        if (it == to.end() || p.first == "metadata") // hacky but we want to allow multiple entries for metadata
+        if (it == to.end() || p.first == "metadata") // hacky but we want to allow multiple entries
+                                                     // for metadata
             to.push_back(p);
     }
 
@@ -903,6 +872,8 @@ struct ConfigManager::ConfigManagerImpl {
     bool        m_error     = false;
     std::string m_error_msg = "";
 
+    std::vector<const char*> builtin_option_specs_list;
+
     std::map<std::string, arglist_t> m_default_parameters_for_spec;
 
     arglist_t m_default_parameters;
@@ -1406,9 +1377,48 @@ struct ConfigManager::ConfigManagerImpl {
     }
 
     ConfigManagerImpl()
+        : builtin_option_specs_list({
+              builtin_base_option_specs,
+#ifdef CALIPER_HAVE_GOTCHA
+                  builtin_gotcha_option_specs,
+#endif
+#ifdef CALIPER_HAVE_MPI
+                  builtin_mpi_option_specs,
+#endif
+#ifdef CALIPER_HAVE_OMPT
+                  builtin_openmp_option_specs,
+#endif
+#ifdef CALIPER_HAVE_CUPTI
+                  builtin_cuda_option_specs,
+#endif
+#if defined(CALIPER_HAVE_ROCTRACER) || defined(CALIPER_HAVE_ROCPROFILER)
+                  builtin_rocm_option_specs,
+#endif
+#ifdef CALIPER_HAVE_LIBDW
+                  builtin_libdw_option_specs,
+#endif
+#ifdef CALIPER_HAVE_PCP
+                  builtin_pcp_option_specs,
+#endif
+#ifdef CALIPER_HAVE_UMPIRE
+                  builtin_umpire_option_specs,
+#endif
+                  builtin_kokkos_option_specs
+          })
     {
-        for (const char** spec_p = builtin_option_specs_list; *spec_p; ++spec_p)
-            add_global_option_specs(*spec_p);
+#ifdef CALIPER_HAVE_PAPI
+#ifdef CALIPER_HAVE_ARCH
+        if (CALIPER_HAVE_ARCH == "sapphirerapids") {
+            builtin_option_specs_list.push_back(builtin_papi_spr_option_specs);
+        } else {
+            builtin_option_specs_list.push_back(builtin_papi_hsw_option_specs);
+        }
+#else
+        builtin_option_specs_list.push_back(builtin_papi_hsw_option_specs);
+#endif
+#endif
+        for (const char* spec_p : builtin_option_specs_list)
+            add_global_option_specs(spec_p);
     }
 };