Update correlation id definition + status strings + const active contexts (#127)

* Update include/rocprofiler

- remove rocprofiler_external_correlation_id_t
- redefine rocprofiler_correlation_id_t to include internal id and external user data
- associate rocprofiler_push_external_correlation_id and rocprofiler_pop_external_correlation_id with a context

* Update include/rocprofiler/rocprofiler.h

- rocprofiler_get_status_name
- rocprofiler_get_status_string

* Update lib/rocprofiler/rocprofiler.cpp

- implement rocprofiler_get_status_name and rocprofiler_get_status_string

* Update lib/rocprofiler/tests/status.cpp

- unit test for status string and name

* Update lib/rocprofiler/tests/registration.cpp

- update to new rocprofiler_correlation_id_t

* Update samples

- update to new rocprofiler_correlation_id_t

* Add lib/rocprofiler/external_correlation.cpp

- placeholder for external correlation push/pop

* Update lib/rocprofiler/hsa/agent_cache.cpp

- slight tweak to when HSA_AMD_AGENT_INFO_NEAREST_CPU is defined

* Update context implementation and hsa.cpp

- get_active_contexts is array of const context pointers
- update hsa_api_impl<Idx>::functor to new rocprofiler_correlation_id_t

* Update include/rocprofiler/fwd.h

- add ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT
- reorder enum for consistency

* Update include/rocprofiler/external_correlation.h

- doxygen comments
- thread id parameter

* Update include/rocprofiler/rocprofiler.h

- add rocprofiler_get_thread_id function (needed for external corr id)

* Update lib/common/synchronized.hpp

- explicit LockedType
- define all copy/move ctor and assignment
- update rlock/wlock/ulock to support arguments and return values
- Support additional template parameter for special case of synchronized instance which is the mapped type of a sychronized map

* Update lib/rocprofiler/external_correlation.cpp

- implement rocprofiler_{push,pop}_external_correlation_id

* Update lib/rocprofiler/CMakeLists.txt

- external_correlation.hpp

* Update lib/rocprofiler/rocprofiler.cpp

- status string for ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT
- implement rocprofiler_get_thread_id

* Update lib/rocprofiler/tests (external correlation)

- add external_correlation unit tests

* Update include/rocprofiler/callback_tracing.h

- doxygen comments
- callback invoked in callback tracing has user_data pointer passed to it

* Update samples/api_callback_tracing/client.cpp

- add rocprofiler_user_data_t* to tool_tracing_callback

* Update lib/rocprofiler/tests/registration.cpp

- add rocprofiler_user_data_t* to tool_tracing_callback

* Update lib/rocprofiler/context/context.{hpp,cpp}

- update correlation_tracing_service
  - external_correlation instance
  - rename get_unique_record_id to get_unique_internal_id

* Update lib/tests/common/demangling.cpp

- tweak mangled definitions due to changing function get_unique_record_id to get_unique_internal_id

* Update lib/rocprofiler/hsa/hsa.cpp

- handle updates to external correlation id
- handle updates to callback signature in callback tracing

* Update CMakeLists.txt

- CMAKE_BUILD_TYPE=Coverage defines CODECOV=1

* Update samples/api_callback_tracing/client.cpp

source/include/rocprofiler/buffer_tracing.h

@@ -200,8 +200,7 @@ typedef struct
 {
     rocprofiler_service_buffer_tracing_kind_t kind;
     rocprofiler_correlation_id_t              correlation_id;
-    rocprofiler_external_correlation_id_t     external_correlation_id;
-} rocprofiler_buffer_tracing_external_correlation_record_t;
+} rocprofiler_buffer_tracing_correlation_record_t;
 
 /**
  * @brief Callback function for mapping @ref rocprofiler_service_buffer_tracing_kind_t ids to

source/include/rocprofiler/callback_tracing.h

@@ -132,10 +132,26 @@ typedef struct
 } rocprofiler_callback_tracer_code_object_register_host_kernel_symbol_data_t;
 
 /**
- * @brief API Tracing callback function.
+ * @brief API Tracing callback function. This function is invoked twice per API function: once
+ * before the function is invoked and once after the function is invoked.  The external correlation
+ * id value within the record is assigned the value at the top of the external correlation id stack.
+ * It is permissible to invoke @ref rocprofiler_push_external_correlation_id within the enter phase;
+ * when a new external correlation id is pushed during the enter phase, rocprofiler will use that
+ * external correlation id for any async events and provide the new external correlation id during
+ * the exit callback... In other words, pushing a new external correlation id within the enter
+ * callback will result in that external correlation id value in the exit callback (which may or may
+ * not be different from the external correlation id value in the enter callback). If a tool pushes
+ * new external correlation ids in the enter phase, it is recommended to pop the external
+ * correlation id in the exit callback.
+ *
+ * @param record [in] Callback record data
+ * @param user_data [in,out] This paramter can be used to retain information in between the enter
+ * and exit phases.
+ * @param callback_data [in] User data provided when configuring the callback tracing service
  */
 typedef void (*rocprofiler_callback_tracing_cb_t)(rocprofiler_callback_tracing_record_t record,
-                                                  void*                                 user_data);
+                                                  rocprofiler_user_data_t*              user_data,
+                                                  void* callback_data) ROCPROFILER_NONNULL(2);
 
 /**
  * @brief Callback function for mapping @ref rocprofiler_service_callback_tracing_kind_t ids to
@@ -180,15 +196,31 @@ typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)(
     void*                                       data);
 
 /**
- * @brief Configure Callback Tracing Service.
+ * @brief Configure Callback Tracing Service. The callback tracing service provides two synchronous
+ * callbacks around an API function on the same thread as the application which is invoking the API
+ * function. This function can only be invoked once per @ref
+ * rocprofiler_service_callback_tracing_kind_t value, i.e. it can be invoked once for the HSA API,
+ * once for the HIP API, and so on but it will fail if it is invoked for the HSA API twice. Please
+ * note, the callback API does have the potentially non-trivial overhead of copying the function
+ * arguments into the record. If you are willing to let rocprofiler record the timestamps, do not
+ * require synchronous notifications of the API calls, and want to lowest possible overhead, use the
+ * @see BUFFER_TRACING_SERVICE.
  *
- * @param [in] context_id
- * @param [in] kind
- * @param [in] operations
- * @param [in] operations_count
- * @param [in] callback
- * @param [in] callback_args
- * @return ::rocprofiler_status_t
+ * @param [in] context_id Context to associate the service with
+ * @param [in] kind The domain of the callback tracing service
+ * @param [in] operations Array of operations in the domain (i.e. enum values which identify
+ * specific API functions). If this is null, all API functions in the domain will be traced
+ * @param [in] operations_count If the operations array is non-null, set this to the size of the
+ * array.
+ * @param [in] callback The function to invoke before and after an API function
+ * @param [in] callback_args Data provided to every invocation of the callback function
+ * @return ::rocprofiler_status_t Will return @ref ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED if
+ * invoked outside of the initialization function in @ref rocprofiler_tool_configure_result_t
+ * provided to rocprofiler via @ref rocprofiler_configure function. Will return @ref
+ * ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the provided context is not valid/registered. Will
+ * return @ref ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED if the same @ref
+ * rocprofiler_service_callback_tracing_kind_t value is provided more than once (per context) -- in
+ * other words, we do not support overriding or combining the operations in separate function calls.
  *
  */
 rocprofiler_status_t ROCPROFILER_API

source/include/rocprofiler/external_correlation.h

@@ -37,23 +37,32 @@ ROCPROFILER_EXTERN_C_INIT
 /** @} */
 
 /**
- * @brief ROCProfiler Push External Correlation ID.
+ * @brief Push default value for `external` field in @ref rocprofiler_correlation_id_t onto stack.
  *
- * @param external_correlation_id
- * @return rocprofiler_status_t
+ * @param context [in] Associated context
+ * @param tid [in] thread identifier. @see rocprofiler_get_thread_id
+ * @param external_correlation_id [in] User data to place in external field in @ref
+ * rocprofiler_correlation_id_t
+ * @return rocprofiler_status_t Returns ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the context
+ * does not exist. Returns ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT if thread id is not valid.
  */
 rocprofiler_status_t ROCPROFILER_API
-rocprofiler_push_external_correlation_id(
-    rocprofiler_external_correlation_id_t external_correlation_id);
+rocprofiler_push_external_correlation_id(rocprofiler_context_id_t context,
+                                         rocprofiler_thread_id_t  tid,
+                                         rocprofiler_user_data_t  external_correlation_id);
 
 /**
- * @brief ROCProfiler Push External Correlation ID.
+ * @brief Pop default value for `external` field in @ref rocprofiler_correlation_id_t off of stack
  *
- * @param external_correlation_id
- * @return rocprofiler_status_t
+ * @param context [in] Associated context
+ * @param tid [in] thread identifier. @see rocprofiler_get_thread_id
+ * @param external_correlation_id [out] Correlation id data popped off the stack
+ * @return rocprofiler_status_t Returns ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND if the context
+ * does not exist. Returns ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT if thread id is not valid.
  */
 rocprofiler_status_t ROCPROFILER_API
-rocprofiler_pop_external_correlation_id(
-    rocprofiler_external_correlation_id_t* external_correlation_id);
+rocprofiler_pop_external_correlation_id(rocprofiler_context_id_t context,
+                                        rocprofiler_thread_id_t  tid,
+                                        rocprofiler_user_data_t* external_correlation_id);
 
 ROCPROFILER_EXTERN_C_FINI

source/include/rocprofiler/fwd.h

@@ -54,6 +54,8 @@ typedef enum  // NOLINT(performance-enum-size)
     ROCPROFILER_STATUS_ERROR_DOMAIN_NOT_FOUND,     ///< Domain identifier is invalid
     ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND,  ///< Operation identifier is invalid for domain
     ROCPROFILER_STATUS_ERROR_THREAD_NOT_FOUND,     ///< No valid thread for given thread id
+    ROCPROFILER_STATUS_ERROR_AGENT_NOT_FOUND,      ///< Agent identifier not found
+    ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND,    ///< Counter identifier does not exist
     ROCPROFILER_STATUS_ERROR_CONTEXT_ERROR,        ///> Generalized context error
     ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID,      ///< Context configuration is not valid
     ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_STARTED,  ///< Context was not started (maybe already
@@ -69,8 +71,8 @@ typedef enum  // NOLINT(performance-enum-size)
     ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED,             ///< Function is not implemented
     ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI,  ///< Data structure provided by user is incompatible
                                                 ///< with current version of rocprofiler
-    ROCPROFILER_STATUS_ERROR_AGENT_NOT_FOUND,   ///< Agent not found
-    ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND,  ///< Counter does not exist
+    ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT,  ///< Function invoked with one or more invalid
+                                                ///< arguments
     ROCPROFILER_STATUS_LAST,
 } rocprofiler_status_t;
 
@@ -282,17 +284,10 @@ typedef struct
  */
 typedef struct
 {
-    uint64_t id;
+    uint64_t                internal;
+    rocprofiler_user_data_t external;
 } rocprofiler_correlation_id_t;
 
-/**
- * @brief ROCProfiler External Correlation ID.
- */
-typedef struct
-{
-    uint64_t id;
-} rocprofiler_external_correlation_id_t;
-
 /**
  * @struct rocprofiler_buffer_id_t
  * @brief Buffer ID.
@@ -332,13 +327,12 @@ typedef struct
  */
 typedef struct rocprofiler_callback_tracing_record_t
 {
+    rocprofiler_context_id_t                    context_id;
     rocprofiler_thread_id_t                     thread_id;
     rocprofiler_correlation_id_t                correlation_id;
-    rocprofiler_external_correlation_id_t       external_correlation_id;
     rocprofiler_service_callback_tracing_kind_t kind;
     uint32_t                                    operation;
     rocprofiler_service_callback_phase_t        phase;
-    rocprofiler_user_data_t                     data;
     void*                                       payload;
 } rocprofiler_callback_tracing_record_t;
 

source/include/rocprofiler/rocprofiler.h

@@ -97,6 +97,32 @@ ROCPROFILER_EXTERN_C_INIT
 rocprofiler_status_t
 rocprofiler_get_timestamp(rocprofiler_timestamp_t* ts) ROCPROFILER_API ROCPROFILER_NONNULL(1);
 
+/**
+ * @fn rocprofiler_status_t rocprofiler_get_thread_id(rocprofiler_thread_id_t* tid)
+ * @brief Get the identifier value of the current thread that is used by rocprofiler
+ * @param [out] tid Output address of the rocprofiler thread id value
+ */
+rocprofiler_status_t
+rocprofiler_get_thread_id(rocprofiler_thread_id_t* tid) ROCPROFILER_API ROCPROFILER_NONNULL(1);
+
+/**
+ * @fn const char* rocprofiler_get_status_name(rocprofiler_status_t status)
+ * @brief Return the string encoding of @ref rocprofiler_status_t value
+ * @param [in] status error code value
+ * @return Will return a nullptr if invalid/unsupported @ref rocprofiler_status_t value is provided.
+ */
+const char*
+rocprofiler_get_status_name(rocprofiler_status_t status) ROCPROFILER_API;
+
+/**
+ * @fn const char* rocprofiler_get_status_string(rocprofiler_status_t status)
+ * @brief Return the message associated with @ref rocprofiler_status_t value
+ * @param [in] status error code value
+ * @return Will return a nullptr if invalid/unsupported @ref rocprofiler_status_t value is provided.
+ */
+const char*
+rocprofiler_get_status_string(rocprofiler_status_t status) ROCPROFILER_API;
+
 /** @} */
 
 ROCPROFILER_EXTERN_C_FINI