diff --git a/projects/rocprofiler-sdk/.github/workflows/docs.yml b/projects/rocprofiler-sdk/.github/workflows/docs.yml index 615a634168..97fb24ad60 100644 --- a/projects/rocprofiler-sdk/.github/workflows/docs.yml +++ b/projects/rocprofiler-sdk/.github/workflows/docs.yml @@ -47,10 +47,13 @@ jobs: - name: Create Docs Directory run: mkdir -p docs - - name: Update Docs + - name: Install Conda environment working-directory: source/docs run: | conda env create -n rocprofiler-docs -f environment.yml + - name: Build Docs + working-directory: source/docs + run: | source activate conda activate rocprofiler-docs ../scripts/update-docs.sh diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/buffer_tracing.h b/projects/rocprofiler-sdk/source/include/rocprofiler/buffer_tracing.h index a6e7c4460d..43c21e69cd 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/buffer_tracing.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/buffer_tracing.h @@ -242,15 +242,16 @@ rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * - * @param kind [in] Buffer tracing domain - * @param name [out] If non-null and the name is a constant string that does not require dynamic + * @param [in] kind Buffer tracing domain + * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr - * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of + * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) - * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND if the - * domain id is not valid. Returns @ref ROCPROFILER_STATUS_SUCCESS for a valid domain regardless if - * there is a constant string or not. + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Returned if the domain id is not valid + * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if a valid domain, regardless if there is a + * constant string or not. */ rocprofiler_status_t rocprofiler_query_buffer_tracing_kind_name(rocprofiler_service_buffer_tracing_kind_t kind, @@ -262,18 +263,20 @@ rocprofiler_query_buffer_tracing_kind_name(rocprofiler_service_buffer_tracing_ki * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * - * @param kind [in] Buffer tracing domain - * @param operation [in] Enumeration id value which maps to a specific API function or event type - * @param name [out] If non-null and the name is a constant string that does not require dynamic + * @param [in] kind Buffer tracing domain + * @param [in] operation Enumeration id value which maps to a specific API function or event type + * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr - * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of + * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) - * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND on an invalid - * domain id. Returns @ref ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND if the operation number is - * not recognized for the given domain. Returns @ref ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if - * rocprofiler does not support providing the operation name within this domain. Returns @ref - * ROCPROFILER_STATUS_SUCCESS for valid domain and operation regardless of whether there is a + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND An invalid domain id + * @retval ::ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND The operation number is not recognized for + * the given domain + * @retval ::ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED Rocprofiler does not support providing the + * operation name within this domain + * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain and operation, regardless of whether there is a * constant string or not. */ rocprofiler_status_t diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/callback_tracing.h b/projects/rocprofiler-sdk/source/include/rocprofiler/callback_tracing.h index 20d80c35af..31dffd713f 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/callback_tracing.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/callback_tracing.h @@ -183,10 +183,10 @@ typedef struct * 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 + * @param [in] record Callback record data + * @param [in,out] user_data 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 + * @param [in] callback_data User data provided when configuring the callback tracing service */ typedef void (*rocprofiler_callback_tracing_cb_t)(rocprofiler_callback_tracing_record_t record, rocprofiler_user_data_t* user_data, @@ -215,13 +215,13 @@ typedef int (*rocprofiler_callback_tracing_kind_operation_cb_t)( * This function will be invoked for each argument. * @see rocprofiler_iterate_callback_tracing_operation_args * - * @param kind [in] domain - * @param operation [in] associated domain operation - * @param arg_number [in] the argument number, starting at zero - * @param arg_name [in] the name of the argument in the prototype (or rocprofiler union) - * @param arg_value_str [in] conversion of the argument to a string, e.g. operator<< overload - * @param arg_value_addr [in] the address of the argument stored by rocprofiler. - * @param data [in] user data + * @param [in] kind domain + * @param [in] operation associated domain operation + * @param [in] arg_number the argument number, starting at zero + * @param [in] arg_name the name of the argument in the prototype (or rocprofiler union) + * @param [in] arg_value_str conversion of the argument to a string, e.g. operator<< overload + * @param [in] arg_value_addr the address of the argument stored by rocprofiler. + * @param [in] data user data */ typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)( rocprofiler_service_callback_tracing_kind_t kind, @@ -251,11 +251,12 @@ typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)( * 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 + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Invoked outside of the initialization + * function in @ref rocprofiler_tool_configure_result_t provided to rocprofiler via @ref + * rocprofiler_configure function + * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND The provided context is not valid/registered + * @retval ::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. * @@ -273,13 +274,13 @@ rocprofiler_configure_callback_tracing_service(rocprofiler_context_id_t context_ * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * - * @param kind [in] Callback tracing domain - * @param name [out] If non-null and the name is a constant string that does not require dynamic + * @param [in] kind Callback tracing domain + * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr - * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of + * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) - * @return rocprofiler_status_t + * @return ::rocprofiler_status_t */ rocprofiler_status_t rocprofiler_query_callback_tracing_kind_name(rocprofiler_service_callback_tracing_kind_t kind, @@ -291,16 +292,17 @@ rocprofiler_query_callback_tracing_kind_name(rocprofiler_service_callback_tracin * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * - * @param kind [in] Callback tracing domain - * @param operation [in] Enumeration id value which maps to a specific API function or event type - * @param name [out] If non-null and the name is a constant string that does not require dynamic + * @param [in] kind Callback tracing domain + * @param [in] operation Enumeration id value which maps to a specific API function or event type + * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr - * @param name_len [out] If non-null, this will be assigned the length of the name (regardless of + * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) - * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND if the - * domain id is not valid. Returns @ref ROCPROFILER_STATUS_SUCCESS for a valid domain regardless if - * there is a constant string or not. + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Domain id is not valid + * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain provided, regardless if there is a constant + * string or not. */ rocprofiler_status_t rocprofiler_query_callback_tracing_kind_operation_name( @@ -310,20 +312,13 @@ rocprofiler_query_callback_tracing_kind_operation_name( uint64_t* name_len) ROCPROFILER_API; /** - * @brief Iterate over all the mappings of the callback tracing kinds and get a callback with the id - * mapped to a constant string. The strings provided in the arg will be valid pointers for the - * entire duration of the program. It is recommended to call this function once and cache this data - * in the client instead of making multiple on-demand calls. + * @brief Iterate over all the mappings of the callback tracing kinds and get a callback for each + * kind. * * @param [in] callback Callback function invoked for each enumeration value in @ref * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback - * @return rocprofiler_status_t Returns @ref ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND on an invalid - * domain id. Returns @ref ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND if the operation number is - * not recognized for the given domain. Returns @ref ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if - * rocprofiler does not support providing the operation name within this domain. Returns @ref - * ROCPROFILER_STATUS_SUCCESS for valid domain and operation regardless of whether there is a - * constant string or not. + * @return ::rocprofiler_status_t */ rocprofiler_status_t ROCPROFILER_API rocprofiler_iterate_callback_tracing_kinds(rocprofiler_callback_tracing_kind_cb_t callback, @@ -331,15 +326,16 @@ rocprofiler_iterate_callback_tracing_kinds(rocprofiler_callback_tracing_kind_cb_ /** * @brief Iterates over all the mappings of the operations for a given @ref - * rocprofiler_service_callback_tracing_kind_t and invokes the callback with the kind, operation id, - * and the string mapping to the operation id. The strings provided in the callback arg will be - * valid pointers for the entire duration of the program. It is recommended to call this function - * once per kind, and cache this data in the client instead of making multiple on-demand calls. + * rocprofiler_service_callback_tracing_kind_t and invokes the callback with the kind id, operation + * id, and user-provided data. * * @param [in] kind which tracing callback kind operations to iterate over * @param [in] callback Callback function invoked for each operation associated with @ref * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Invalid domain id + * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain */ rocprofiler_status_t ROCPROFILER_API rocprofiler_iterate_callback_tracing_kind_operations( diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/context.h b/projects/rocprofiler-sdk/source/include/rocprofiler/context.h index 9e5dfa4b16..9054d1d432 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/context.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/context.h @@ -43,7 +43,7 @@ ROCPROFILER_EXTERN_C_INIT /** * @brief Create context. * - * @param context_id [out] Context identifier + * @param [out] context_id Context identifier * @return ::rocprofiler_status_t */ rocprofiler_status_t ROCPROFILER_API diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/counters.h b/projects/rocprofiler-sdk/source/include/rocprofiler/counters.h index 3bd4b33114..b11c03dbbc 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/counters.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/counters.h @@ -52,7 +52,7 @@ rocprofiler_query_counter_name(rocprofiler_counter_id_t counter_id, const char** * @param [in] agent rocprofiler agent * @param [in] counter_id counter id (obtained from iterate_agent_supported_counters) * @param [out] instance_count number of instances the counter has - * @return rocprofiler_status_t + * @return ::rocprofiler_status_t */ rocprofiler_status_t ROCPROFILER_API rocprofiler_query_counter_instance_count(rocprofiler_agent_t agent, diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/external_correlation.h b/projects/rocprofiler-sdk/source/include/rocprofiler/external_correlation.h index 9c3034d5b4..94419bd603 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/external_correlation.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/external_correlation.h @@ -34,17 +34,16 @@ ROCPROFILER_EXTERN_C_INIT * @{ */ -/** @} */ - /** * @brief Push default value for `external` field in @ref rocprofiler_correlation_id_t onto stack. * - * @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 + * @param [in] context Associated context + * @param [in] tid thread identifier. @see rocprofiler_get_thread_id + * @param [in] external_correlation_id 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. + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist + * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid */ rocprofiler_status_t ROCPROFILER_API rocprofiler_push_external_correlation_id(rocprofiler_context_id_t context, @@ -54,15 +53,18 @@ rocprofiler_push_external_correlation_id(rocprofiler_context_id_t context, /** * @brief Pop default value for `external` field in @ref rocprofiler_correlation_id_t off of stack * - * @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. + * @param [in] context Associated context + * @param [in] tid thread identifier. @see rocprofiler_get_thread_id + * @param [out] external_correlation_id Correlation id data popped off the stack + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist + * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid */ rocprofiler_status_t ROCPROFILER_API 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 diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/fwd.h b/projects/rocprofiler-sdk/source/include/rocprofiler/fwd.h index 12232b76f3..2be3c03b6e 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/fwd.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/fwd.h @@ -388,8 +388,8 @@ typedef struct * @brief Function for computing the unsigned 64-bit hash value in @ref rocprofiler_record_header_t * from a category and kind (two unsigned 32-bit values) * - * @param category [in] a value from @ref rocprofiler_buffer_category_t - * @param kind [in] depending on the category, this is the domain value, e.g., @ref + * @param [in] category a value from @ref rocprofiler_buffer_category_t + * @param [in] kind depending on the category, this is the domain value, e.g., @ref * rocprofiler_service_buffer_tracing_kind_t value * @return uint64_t hash value of category and kind */ diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/internal_threading.h b/projects/rocprofiler-sdk/source/include/rocprofiler/internal_threading.h index 8a5060b4b4..4c9d373e04 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/internal_threading.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/internal_threading.h @@ -71,12 +71,12 @@ typedef void (*rocprofiler_internal_thread_library_cb_t)(rocprofiler_internal_th * caller is responsible for ignoring these callbacks if they want to ignore them beyond a certain * point in the application. * - * @param precreate [in] Callback invoked immediately before a new internal thread is created - * @param postcreate [in] Callback invoked immediately after a new internal thread is created - * @param libs [in] Bitwise-or of libraries, e.g. `ROCPROFILER_LIBRARY | ROCPROFILER_MARKER_LIBRARY` + * @param [in] precreate Callback invoked immediately before a new internal thread is created + * @param [in] postcreate Callback invoked immediately after a new internal thread is created + * @param [in] libs Bitwise-or of libraries, e.g. `ROCPROFILER_LIBRARY | ROCPROFILER_MARKER_LIBRARY` * means the callbacks will be invoked whenever rocprofiler and/or the marker library create * internal threads but not when the HSA or HIP libraries create internal threads. - * @param data [in] Data shared between callbacks + * @param [in] data Data shared between callbacks */ rocprofiler_status_t ROCPROFILER_API rocprofiler_at_internal_thread_create(rocprofiler_internal_thread_library_cb_t precreate, diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler/registration.h b/projects/rocprofiler-sdk/source/include/rocprofiler/registration.h index 500e23e85c..5032b7071a 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler/registration.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler/registration.h @@ -74,7 +74,7 @@ typedef struct * * @param [out] status 0 indicates rocprofiler has not been initialized (i.e. configured), 1 * indicates rocprofiler has been initialized, -1 indicates rocprofiler is currently initializing. - * @return rocprofiler_status_t + * @return ::rocprofiler_status_t */ rocprofiler_status_t rocprofiler_is_initialized(int* status) ROCPROFILER_API; @@ -84,7 +84,7 @@ rocprofiler_is_initialized(int* status) ROCPROFILER_API; * * @param [out] status 0 indicates rocprofiler has not been finalized, 1 indicates rocprofiler has * been finalized, -1 indicates rocprofiler is currently finalizing. - * @return rocprofiler_status_t + * @return ::rocprofiler_status_t */ rocprofiler_status_t rocprofiler_is_finalized(int* status) ROCPROFILER_API; diff --git a/projects/rocprofiler-sdk/source/lib/rocprofiler/counters.cpp b/projects/rocprofiler-sdk/source/lib/rocprofiler/counters.cpp index 12b8a1c00d..7ea22f27c4 100644 --- a/projects/rocprofiler-sdk/source/lib/rocprofiler/counters.cpp +++ b/projects/rocprofiler-sdk/source/lib/rocprofiler/counters.cpp @@ -37,7 +37,7 @@ rocprofiler_query_counter_name(rocprofiler_counter_id_t counter_id, const char** * * @param [in] counter_id * @param [out] instance_count - * @return rocprofiler_status_t + * @return ::rocprofiler_status_t */ rocprofiler_status_t ROCPROFILER_API rocprofiler_query_counter_instance_count(rocprofiler_agent_t agent,