ATT Doc updates. Fix trace-decode return error. (#406)

* Doc updates. Some cleanup.

* Formatting

---------

Co-authored-by: Giovanni Baraldi <gbaraldi@amd.com>

source/include/rocprofiler-sdk/experimental/thread-trace/trace_decoder.h

@@ -28,21 +28,24 @@
 ROCPROFILER_EXTERN_C_INIT
 
 /**
- * @defgroup THREAD_TRACE Thread Trace Decoding
- * @brief Provides API calls to decode thread trace data
- *
+ * @defgroup THREAD_TRACE Thread Trace Service
+ * @brief ROCprof-trace-decoder wrapper. Provides API calls to decode thread trace shader data.
  * @{
  */
 
+/**
+ * @brief Handle containing a loaded rocprof-trace-decoder and a decoder state.
+ */
 typedef struct rocprofiler_thread_trace_decoder_handle_t
 {
     uint64_t handle;
 } rocprofiler_thread_trace_decoder_handle_t;
 
 /**
- * @brief Initializes Trace Decoder library
+ * @brief Initializes Trace Decoder library with a library search path
  * @param[out] handle Handle to created decoder instance.
  * @param[in] path Path to trace decoder library location (e.g. /opt/rocm/lib).
+ * @return ::rocprofiler_status_t
  * @retval ::ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE Library not found
  * @retval ::ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI Library found but version not supported
  * @retval ::ROCPROFILER_STATUS_SUCCESS Handle created
@@ -52,7 +55,7 @@ rocprofiler_thread_trace_decoder_create(rocprofiler_thread_trace_decoder_handle_
                                         const char* path) ROCPROFILER_API ROCPROFILER_NONNULL(1, 2);
 
 /**
- * @brief Deletes handle created by rocprofiler_thread_trace_decoder_create
+ * @brief Deletes handle created by ::rocprofiler_thread_trace_decoder_create
  * @param[in] handle Handle to destroy
  */
 void
@@ -60,12 +63,21 @@ rocprofiler_thread_trace_decoder_destroy(rocprofiler_thread_trace_decoder_handle
     ROCPROFILER_API;
 
 /**
- * @brief Loads a code object binary to match with Thread Trace
+ * @brief Loads a code object binary to match with Thread Trace.
+ * The size, data and load_* are reported by rocprofiler-sdk's code object tracing service.
+ * Used for the decoder library to know what code objects to look into when decoding shader data.
+ * Not all application code objects are required to be reported here, only the ones containing code
+ * executed at the time the shader data was collected by thread_trace services.
+ * If a code object not reported here is encountered while decoding shader data, a record of type
+ * INFO_STITCH_INCOMPLETE will be generated and instructions will not be reported with a PC address.
+ *
  * @param[in] handle Handle to decoder instance.
  * @param[in] load_id Code object load ID.
  * @param[in] load_addr Code object load address.
  * @param[in] load_size Code object load size.
- * @param[in] data Code object binary data. Must be at least load_size bytes.
+ * @param[in] data Code object binary data.
+ * @param[in] size Code object binary data size.
+ * @return ::rocprofiler_status_t
  * @retval ::ROCPROFILER_STATUS_ERROR Unable to load code object.
  * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Invalid handle
  * @retval ::ROCPROFILER_STATUS_SUCCESS Code object loaded
@@ -79,9 +91,10 @@ rocprofiler_thread_trace_decoder_codeobj_load(rocprofiler_thread_trace_decoder_h
                                               uint64_t size) ROCPROFILER_API ROCPROFILER_NONNULL(5);
 
 /**
- * @brief Unloads a code object binary
+ * @brief Unloads a code object binary.
  * @param[in] handle Handle to decoder instance.
  * @param[in] load_id Code object load ID to remove.
+ * @return ::rocprofiler_status_t
  * @retval ::ROCPROFILER_STATUS_ERROR Code object not loaded.
  * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Invalid handle
  * @retval ::ROCPROFILER_STATUS_SUCCESS Code object unloaded
@@ -91,8 +104,8 @@ rocprofiler_thread_trace_decoder_codeobj_unload(rocprofiler_thread_trace_decoder
                                                 uint64_t load_id) ROCPROFILER_API;
 
 /**
- * @brief Callback for rocprofiler to return traces back to rocprofiler.
- * @param[in] trace_type_id One of rocprofiler_thread_trace_decoder_record_type_t
+ * @brief Callback for rocprof-trace-decoder to return decoder traces back to user.
+ * @param[in] record_type_id One of ::rocprofiler_thread_trace_decoder_record_type_t
  * @param[in] trace_events A pointer to sequence of events, of size trace_size.
  * @param[in] trace_size The number of events in the trace.
  * @param[in] userdata Arbitrary data pointer to be sent back to the user via callback.
@@ -104,12 +117,22 @@ typedef void (*rocprofiler_thread_trace_decoder_callback_t)(
     void*                                          userdata);
 
 /**
- * @brief Iterate over all event coordinates for a given agent_t and event_t.
- * @param[in] se_data_callback Callback to return shader engine data from.
+ * @brief Decodes shader data returned by ::rocprofiler_thread_trace_shader_data_callback_t.
+ * Use ::rocprofiler_thread_trace_decoder_codeobj_load to add references to loaded code objects
+ * during the trace.
+ * A ::rocprofiler_thread_trace_decoder_callback_t returns decoded data back to user. The first
+ * record is always of type ::ROCPROFILER_THREAD_TRACE_DECODER_RECORD_GFXIP.
+ *
+ * @param[in] handle Decoder handle
  * @param[in] callback Decoded trace data returned to user.
  * @param[in] data Thread trace binary data.
  * @param[in] size Thread trace binary size.
  * @param[in] userdata Userdata passed back to caller via callback.
+ * @return ::rocprofiler_status_t
+ * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT invalid argument
+ * @retval ::ROCPROFILER_STATUS_ERROR_AGENT_ARCH_NOT_SUPPORTED arch not supported
+ * @retval ::ROCPROFILER_STATUS_ERROR generic error
+ * @retval ::ROCPROFILER_STATUS_SUCCESS on success
  */
 rocprofiler_status_t
 rocprofiler_trace_decode(rocprofiler_thread_trace_decoder_handle_t   handle,
@@ -119,7 +142,8 @@ rocprofiler_trace_decode(rocprofiler_thread_trace_decoder_handle_t   handle,
                          void* userdata) ROCPROFILER_API ROCPROFILER_NONNULL(2, 3);
 
 /**
- * @brief Returns the description of a rocprofiler_thread_trace_decoder_info_t record.
+ * @brief Returns the string description of a ::rocprofiler_thread_trace_decoder_info_t record.
+ * @param[in] handle Decoder handle
  * @param[in] info The decoder info received
  * @retval null terminated string as description of "info".
  */
@@ -128,4 +152,6 @@ rocprofiler_thread_trace_decoder_info_string(rocprofiler_thread_trace_decoder_ha
                                              rocprofiler_thread_trace_decoder_info_t   info)
     ROCPROFILER_API;
 
+/** @} */
+
 ROCPROFILER_EXTERN_C_FINI