Documentation, sanitizers, and PTL submodule (#71)

* Update scripts/thread-sanitizer-suppr.txt - ignore data race occasionally triggered by libamdhip64.so * Update external/CMakeLists.txt - configure PTL to use locks in task queues * Update PTL submodule - tweal to task queues to prevent data race from std::list next pointer * Add scripts/setup-sanitizer-env.sh - bash script that exports the {ASAN,LSAN,TSAN}_OPTIONS used by run-ci.py * Update include/rocprofiler (doxygen) - fix doxygen grouping * Update docs workflow - change concurrency group to be specific to workflow + ref - this prevents separate PRs triggering this workflow from cancelling each other
2023-09-20 23:14:25 -05:00
@@ -27,7 +27,10 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup AGENTS Agent Information
+/**
+ * @defgroup AGENTS Agent Information
+ * @brief needs brief description
+ *
 * @{
 */

@@ -27,7 +27,10 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup AGENT_PROFILE_COUNTING_SERVICE Agent Profile Counting Service
+/**
+ * @defgroup AGENT_PROFILE_COUNTING_SERVICE Agent Profile Counting Service
+ * @brief needs brief description
+ *
 * @{
 */

@@ -27,7 +27,10 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup BUFFER_HANDLING Buffer
+/**
+ * @defgroup BUFFER_HANDLING Buffer Handling
+ * @brief Creation, destruction, and flushing of buffers populated with data from rocprofiler
+ *
 * @{
 *
 * Every Buffer is associated with a specific service kind.
@@ -27,9 +27,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup BUFFER_TRACING_SERVICE Asynchronous Tracing Service
- *
- *  Receive callbacks for batches of records from an internal (background) thread
+/**
+ * @defgroup BUFFER_TRACING_SERVICE Asynchronous Tracing Service
+ * @brief Receive callbacks for batches of records from an internal (background) thread
 *
 * @{
 */
@@ -28,9 +28,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup CALLBACK_TRACING_SERVICE Synchronous Tracing Services
- *
- *  Receive immediate callbacks on the calling thread
+/**
+ * @defgroup CALLBACK_TRACING_SERVICE Synchronous Tracing Services
+ * @brief Receive immediate callbacks on the calling thread
 *
 * @{
 */
@@ -28,7 +28,10 @@
 ROCPROFILER_EXTERN_C_INIT

 /**
- * @defgroup CONTEXT_OPERATIONS Context
+ * @defgroup CONTEXT_OPERATIONS Context Handling
+ * @brief Associate services with a handle. This handle is used to activate/deactivate the services
+ * during the application runtime.
+ *
 * @{
 */

@@ -28,7 +28,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup COUNTERS Hardware counters
+/**
+ * @defgroup COUNTERS Hardware counters Information
+ * @brief Query functions related to hardware counters
 * @{
 */

@@ -22,9 +22,10 @@

 #pragma once

-/** @defgroup SYMBOL_VERSIONING_GROUP Symbol Versions
+/**
+ * @defgroup SYMBOL_VERSIONING_GROUP Symbol Versions
 *
- * The names used for the shared library versioned symbols.
+ * @brief The names used for the shared library versioned symbols.
 *
 * Every function is annotated with one of the version macros defined in this
 * section.  Each macro specifies a corresponding symbol version string.  After
@@ -30,8 +30,10 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup DISPATCH_PROFILE_COUNTING_SERVICE Dispatch Profile Counting
- * Service
+/**
+ * @defgroup DISPATCH_PROFILE_COUNTING_SERVICE Dispatch Profile Counting Service
+ * @brief Per-dispatch hardware counter collection service
+ *
 * @{
 */

@@ -29,8 +29,7 @@ ROCPROFILER_EXTERN_C_INIT

 /**
 * @defgroup EXTERNAL_CORRELATION External Correlation IDs
- *
- *  User-defined correlation identifiers to supplement rocprofiler generated correlation ids
+ * @brief User-defined correlation identifiers to supplement rocprofiler generated correlation ids
 *
 * @{
 */
@@ -37,8 +37,8 @@ ROCPROFILER_EXTERN_C_INIT

 /**
 * @defgroup BASIC_DATA_TYPES Basic data types
+ * @brief Basic data types and typedefs
 *
- * Basic data types and typedefs
 * @{
 */

@@ -290,8 +290,8 @@ typedef struct
 } rocprofiler_external_correlation_id_t;

 /**
+ * @struct rocprofiler_buffer_id_t
 * @brief Buffer ID.
- * @addtogroup BUFFER_HANDLING
 */
 typedef struct
 {
@@ -27,9 +27,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup INTERNAL_THREADING Internal thread handling
- *
- * Callbacks before and after threads created internally by libraries
+/**
+ * @defgroup INTERNAL_THREADING Internal Thread Handling
+ * @brief Callbacks before and after threads created internally by libraries
 *
 * @{
 */
@@ -28,7 +28,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup PC_SAMPLING_SERVICE PC Sampling Service
+/**
+ * @defgroup PC_SAMPLING_SERVICE PC Sampling
+ * @brief Enabling PC (Program Counter) Sampling for GPU Activity
 * @{
 */

@@ -28,7 +28,9 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup PROFILE_CONFIG Profile Configurations
+/**
+ * @defgroup PROFILE_CONFIG Profile Configurations
+ * @brief Group one or more hardware counters into a unique handle
 *
 * @{
 */
@@ -26,18 +26,44 @@
 #include <stdint.h>

 #include "rocprofiler/defines.h"
+#include "rocprofiler/fwd.h"

-/** @defgroup VERSIONING_GROUP Library Versioning
- *
- * Version information about the interface and the associated installed
- * library.
+/**
+ * @defgroup VERSIONING_GROUP Library Versioning
+ * @brief Version information about the interface and the associated installed library.
 *
 * The semantic version of the interface following semver.org rules. A context
 * that uses this interface is only compatible with the installed library if
 * the major version numbers match and the interface minor version number is
 * less than or equal to the installed library minor version number.
+ *
+ * @{
 */

+#include "rocprofiler/version.h"
+
+ROCPROFILER_EXTERN_C_INIT
+
+/**
+ * @fn rocprofiler_status_t rocprofiler_get_version(uint32_t* major, uint32_t* minor, uint32_t*
+ * patch)
+ * @brief Query the version of the installed library.
+ *
+ * Return the version of the installed library.  This can be used to check if
+ * it is compatible with this interface version.  This function can be used
+ * even when the library is not initialized.
+ *
+ * @param [out] major The major version number is stored if non-NULL.
+ * @param [out] minor The minor version number is stored if non-NULL.
+ * @param [out] patch The patch version number is stored if non-NULL.
+ */
+rocprofiler_status_t
+rocprofiler_get_version(uint32_t* major, uint32_t* minor, uint32_t* patch) ROCPROFILER_API;
+
+ROCPROFILER_EXTERN_C_FINI
+
+/** @} */
+
 #include "rocprofiler/agent.h"
 #include "rocprofiler/agent_profile.h"
 #include "rocprofiler/buffer.h"
@@ -47,42 +73,29 @@
 #include "rocprofiler/counters.h"
 #include "rocprofiler/dispatch_profile.h"
 #include "rocprofiler/external_correlation.h"
-#include "rocprofiler/fwd.h"
 #include "rocprofiler/hip.h"
 #include "rocprofiler/hsa.h"
 #include "rocprofiler/marker.h"
 #include "rocprofiler/pc_sampling.h"
 #include "rocprofiler/profile_config.h"
 #include "rocprofiler/spm.h"
-#include "rocprofiler/version.h"

 ROCPROFILER_EXTERN_C_INIT

 /**
- * @brief Query the version of the installed library.
+ * @defgroup MISCELLANEOUS_GROUP Miscellaneous Utility Functions
 *
- * Return the version of the installed library.  This can be used to check if
- * it is compatible with this interface version.  This function can be used
- * even when the library is not initialized.
- *
- * @param [out] major The major version number is stored if non-NULL.
- * @param [out] minor The minor version number is stored if non-NULL.
- * @param [out] patch The patch version number is stored if non-NULL.
- * @addtogroup VERSIONING_GROUP
- */
-rocprofiler_status_t
-rocprofiler_get_version(uint32_t* major, uint32_t* minor, uint32_t* patch) ROCPROFILER_API;
-
-/**
- * @defgroup MISCELLANEOUS_GROUP Miscellaneous utility functions
+ * @{
 */

 /**
+ * @fn rocprofiler_status_t rocprofiler_get_timestamp(rocprofiler_timestamp_t* ts)
 * @brief Get the timestamp value that rocprofiler uses
 * @param [out] ts Output address of the rocprofiler timestamp value
- * @addtogroup MISCELLANEOUS_GROUP
 */
 rocprofiler_status_t
 rocprofiler_get_timestamp(rocprofiler_timestamp_t* ts) ROCPROFILER_API ROCPROFILER_NONNULL(1);

+/** @} */
+
 ROCPROFILER_EXTERN_C_FINI
@@ -47,45 +47,45 @@

 #include <stdint.h>

-ROCPROFILER_EXTERN_C_INIT /* __cplusplus */
-
-    /** @defgroup rocprofiler_plugins ROCProfiler Plugin API Specification
-     * @{
-     */
-
-    /** @defgroup initialization_group Initialization and Finalization
-     * @ingroup rocprofiler_plugins
-     *
-     * The ROCProfiler Plugin API must be initialized before using any of the
-     * operations to report trace data, and finalized after the last trace data has
-     * been reported.
-     *
-     * @{
-     */
-
-    /**
-     * Initialize plugin.
-     * Must be called before any other operation.
-     *
-     * @param[in] rocprofiler_major_version The major version of the ROCProfiler API
-     * being used by the ROCProfiler Tool. An error is reported if this does not
-     * match the major version of the ROCProfiler API used to build the plugin
-     * library. This ensures compatibility of the trace data format.
-     * @param[in] rocprofiler_minor_version The minor version of the ROCProfiler API
-     * being used by the ROCProfiler Tool. An error is reported if the
-     * @p rocprofiler_major_version matches and this is greater than the minor
-     * version of the ROCProfiler API used to build the plugin library. This ensures
-     * compatibility of the trace data format.
-     * @param[in] data Pointer to the data passed to the ROCProfiler Plugin by the tool
-     * @return Returns 0 on success and -1 on error.
-     */
-    ROCPROFILER_EXPORT int
-    rocprofiler_plugin_initialize(uint32_t rocprofiler_major_version,
-                                  uint32_t rocprofiler_minor_version,
-                                  void*    data);
+ROCPROFILER_EXTERN_C_INIT

 /**
- * Finalize plugin.
+ * @defgroup ROCPROFILER_PLUGINS ROCProfiler Plugin API Specification
+ * @{
+ */
+
+/**
+ * @defgroup INITIALIZATION_GROUP Initialization and Finalization
+ * @brief The ROCProfiler Plugin API must be initialized before using any of the
+ * operations to report trace data, and finalized after the last trace data has
+ * been reported.
+ * @ingroup ROCPROFILER_PLUGINS
+ *
+ * @{
+ */
+
+/**
+ * @brief Initialize plugin. Must be called before any other operation.
+ *
+ * @param[in] rocprofiler_major_version The major version of the ROCProfiler API
+ * being used by the ROCProfiler Tool. An error is reported if this does not
+ * match the major version of the ROCProfiler API used to build the plugin
+ * library. This ensures compatibility of the trace data format.
+ * @param[in] rocprofiler_minor_version The minor version of the ROCProfiler API
+ * being used by the ROCProfiler Tool. An error is reported if the
+ * @p rocprofiler_major_version matches and this is greater than the minor
+ * version of the ROCProfiler API used to build the plugin library. This ensures
+ * compatibility of the trace data format.
+ * @param[in] data Pointer to the data passed to the ROCProfiler Plugin by the tool
+ * @return Returns 0 on success and -1 on error.
+ */
+ROCPROFILER_EXPORT int
+rocprofiler_plugin_initialize(uint32_t rocprofiler_major_version,
+                              uint32_t rocprofiler_minor_version,
+                              void*    data);
+
+/**
+ * @brief Finalize plugin.
 * This must be called after ::rocprofiler_plugin_initialize and after all
 * profiling data has been reported by
 * rocprofiler_plugin_write_kernel_records
@@ -95,9 +95,11 @@ rocprofiler_plugin_finalize();

 /** @} */

-/** @defgroup profiling_record_write_functions Profiling data reporting
- * @ingroup rocprofiler_plugins
- * Operations to output profiling data.
+/**
+ * @defgroup profiling_record_write_functions Profiling data reporting
+ * @brief Operations to output profiling data.
+ * @ingroup ROCPROFILER_PLUGINS
+ *
 * @{
 */

@@ -119,7 +121,7 @@ rocprofiler_plugin_write_buffer_records(rocprofiler_context_id_t      context_id
                                        size_t                        num_headers);

 /**
- * Report Synchronous Record.
+ * @brief Report Synchronous Record.
 *
 * @param[in] record Synchronous Tracer record.
 * @return Returns 0 on success and -1 on error.
@@ -129,7 +131,6 @@ ROCPROFILER_EXPORT int
 rocprofiler_plugin_write_record(rocprofiler_record_header_t record);

 /** @} */
-
 /** @} */

 ROCPROFILER_EXTERN_C_FINI
@@ -27,7 +27,10 @@

 ROCPROFILER_EXTERN_C_INIT

-/** @defgroup SPM_SERVICE SPM Service
+/**
+ * @defgroup SPM_SERVICE SPM Service
+ * @brief Streaming Performance Monitoring
+ *
 * @{
 */