Tagging APIs from hsa_ext_amd.h for Doxygen

Change-Id: I2ab2358985442647cedbd99eca5b1140cb0b0680
Signed-off-by: David Yat Sin <David.YatSin@amd.com>

runtime/docs/api-reference/api.rst

@@ -17,7 +17,7 @@ Architected Queuing Language
    :content-only:
    :inner:
 
-Code Objects [**DEPRECATED**]
+Code objects [**DEPRECATED**]
 #############################
 .. doxygengroup:: code-object
    :content-only:
@@ -29,25 +29,25 @@ Executable
    :content-only:
    :inner:
 
-Finalization Extensions
+Finalization extensions
 #######################
 .. doxygengroup:: ext-alt-finalizer-extensions
    :content-only:
    :inner:
 
-Finalization Program
+Finalization program
 ####################
 .. doxygengroup:: ext-alt-finalizer-program
    :content-only:
    :inner:
 
-Images And Samplers
+Images and samplers
 ###################
 .. doxygengroup:: ext-images
    :content-only:
    :inner:
 
-Instruction Set Architecture
+Instruction set architecture
 ############################
 .. doxygengroup:: instruction-set-architecture
    :content-only:
@@ -65,7 +65,7 @@ Queues
    :content-only:
    :inner:
 
-Runtime Notifications
+Runtime notifications
 #####################
 .. doxygengroup:: status
    :content-only:
@@ -77,8 +77,22 @@ Signals
    :content-only:
    :inner:
 
-System And Agent Information
+System and agent information
 ############################
 .. doxygengroup:: agentinfo
    :content-only:
    :inner:
+
+Profiling
+###############
+.. doxygengroup:: profile
+   :content-only:
+   :inner:
+
+Error codes
+#############
+.. doxygengroup:: error-codes
+   :content-only:
+   :inner:
+
+

runtime/hsa-runtime/inc/hsa.h

@@ -112,7 +112,7 @@
 extern "C" {
 #endif  /* __cplusplus */
 
-/** \defgroup status Runtime Notifications
+/** \addtogroup error-codes Error codes
  *  @{
  */
 

runtime/hsa-runtime/inc/hsa_ext_amd.h

@@ -196,6 +196,10 @@ typedef struct hsa_amd_barrier_value_packet_s {
 
 /** @} */
 
+/** \defgroup error-codes Error codes
+ *  @{
+ */
+
 /**
  * @brief Enumeration constants added to ::hsa_status_t.
  *
@@ -242,6 +246,12 @@ enum {
   HSA_STATUS_ERROR_RESOURCE_BUSY = 46,
 };
 
+/** @} */
+
+/** \addtogroup memory Memory
+ *  @{
+ */
+
 /**
  * @brief IOMMU version supported
  */
@@ -523,6 +533,7 @@ typedef enum hsa_amd_coherency_type_s {
   HSA_AMD_COHERENCY_TYPE_NONCOHERENT = 1
 } hsa_amd_coherency_type_t;
 
+
 /**
  * @brief Get the coherency type of the fine grain region of an agent.
  *
@@ -564,6 +575,12 @@ hsa_status_t HSA_API hsa_amd_coherency_get_type(hsa_agent_t agent,
 hsa_status_t HSA_API hsa_amd_coherency_set_type(hsa_agent_t agent,
                                                 hsa_amd_coherency_type_t type);
 
+/** @} */
+
+/** \defgroup profile Profiling
+ *  @{
+ */
+
 /**
  * @brief Structure containing profiling dispatch time information.
  *
@@ -721,6 +738,12 @@ hsa_status_t HSA_API
                                                     uint64_t agent_tick,
                                                     uint64_t* system_tick);
 
+/** @} */
+
+/** \defgroup status Runtime notifications
+ *  @{
+ */
+
 /**
  * @brief Signal attribute flags.
  */
@@ -883,6 +906,24 @@ hsa_status_t HSA_API
                                  hsa_signal_value_t value,
                                  hsa_amd_signal_handler handler, void* arg);
 
+/**
+ * @brief Wait for any signal-condition pair to be satisfied.
+ *
+ * @details Allows waiting for any of several signal and conditions pairs to be
+ * satisfied. The function returns the index into the list of signals of the
+ * first satisfying signal-condition pair. The value of the satisfying signal's
+ * value is returned in satisfying_value unless satisfying_value is NULL. This
+ * function provides only relaxed memory semantics.
+ */
+uint32_t HSA_API
+    hsa_amd_signal_wait_any(uint32_t signal_count, hsa_signal_t* signals,
+                            hsa_signal_condition_t* conds,
+                            hsa_signal_value_t* values, uint64_t timeout_hint,
+                            hsa_wait_state_t wait_hint,
+                            hsa_signal_value_t* satisfying_value);
+
+/** @} */
+
 /**
  * @brief Call a function asynchronously
  *
@@ -910,21 +951,65 @@ hsa_status_t HSA_API
 hsa_status_t HSA_API
     hsa_amd_async_function(void (*callback)(void* arg), void* arg);
 
-/**
- * @brief Wait for any signal-condition pair to be satisfied.
- *
- * @details Allows waiting for any of several signal and conditions pairs to be
- * satisfied. The function returns the index into the list of signals of the
- * first satisfying signal-condition pair. The value of the satisfying signal's
- * value is returned in satisfying_value unless satisfying_value is NULL. This
- * function provides only relaxed memory semantics.
+/** \addtogroup ext-images Images and samplers
+ *  @{
  */
-uint32_t HSA_API
-    hsa_amd_signal_wait_any(uint32_t signal_count, hsa_signal_t* signals,
-                            hsa_signal_condition_t* conds,
-                            hsa_signal_value_t* values, uint64_t timeout_hint,
-                            hsa_wait_state_t wait_hint,
-                            hsa_signal_value_t* satisfying_value);
+
+/**
+ * @brief Encodes an opaque vendor specific image format.  The length of data
+ * depends on the underlying format.  This structure must not be copied as its
+ * true length can not be determined.
+ */
+typedef struct hsa_amd_image_descriptor_s {
+  /*
+  Version number of the descriptor
+  */
+  uint32_t version;
+
+  /*
+  Vendor and device PCI IDs for the format as VENDOR_ID<<16|DEVICE_ID.
+  */
+  uint32_t deviceID;
+
+  /*
+  Start of vendor specific data.
+  */
+  uint32_t data[1];
+} hsa_amd_image_descriptor_t;
+
+/**
+ * @brief Creates an image from an opaque vendor specific image format.
+ * Does not modify data at image_data.  Intended initially for
+ * accessing interop images.
+ *
+ * @param agent[in] Agent on which to create the image
+ *
+ * @param[in] image_descriptor[in] Vendor specific image format
+ *
+ * @param[in] image_data Pointer to image backing store
+ *
+ * @param[in] access_permission Access permissions for the image object
+ *
+ * @param[out] image Created image object.
+ *
+ * @retval HSA_STATUS_SUCCESS Image created successfully
+ *
+ * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
+ *
+ * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
+ * necessary resources
+ *
+ * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT Bad or mismatched descriptor,
+ * null image_data, or mismatched access_permission.
+ */
+hsa_status_t HSA_API hsa_amd_image_create(
+    hsa_agent_t agent,
+    const hsa_ext_image_descriptor_t *image_descriptor,
+    const hsa_amd_image_descriptor_t *image_layout,
+    const void *image_data,
+    hsa_access_permission_t access_permission,
+    hsa_ext_image_t *image
+);
 
 /**
  * @brief Query image limits.
@@ -951,6 +1036,12 @@ hsa_status_t HSA_API hsa_amd_image_get_info_max_dim(hsa_agent_t agent,
                                                     hsa_agent_info_t attribute,
                                                     void* value);
 
+/** @} */
+
+/** \addtogroup queue Queues
+ *  @{
+ */
+
 /**
  * @brief Set a queue's CU affinity mask.
  *
@@ -1015,6 +1106,12 @@ hsa_status_t HSA_API hsa_amd_queue_cu_set_mask(const hsa_queue_t* queue,
 hsa_status_t HSA_API hsa_amd_queue_cu_get_mask(const hsa_queue_t* queue, uint32_t num_cu_mask_count,
                                                uint32_t* cu_mask);
 
+/** @} */
+
+/** \addtogroup memory Memory
+ *  @{
+ */
+
 /**
  * @brief Memory segments associated with a memory pool.
  */
@@ -1935,62 +2032,6 @@ hsa_status_t HSA_API hsa_amd_interop_map_buffer(uint32_t num_agents,
  */
 hsa_status_t HSA_API hsa_amd_interop_unmap_buffer(void* ptr);
 
-/**
- * @brief Encodes an opaque vendor specific image format.  The length of data
- * depends on the underlying format.  This structure must not be copied as its
- * true length can not be determined.
- */
-typedef struct hsa_amd_image_descriptor_s {
-  /*
-  Version number of the descriptor
-  */
-  uint32_t version;
-
-  /*
-  Vendor and device PCI IDs for the format as VENDOR_ID<<16|DEVICE_ID.
-  */
-  uint32_t deviceID;
-
-  /*
-  Start of vendor specific data.
-  */
-  uint32_t data[1];
-} hsa_amd_image_descriptor_t;
-
-/**
- * @brief Creates an image from an opaque vendor specific image format.
- * Does not modify data at image_data.  Intended initially for
- * accessing interop images.
- *
- * @param agent[in] Agent on which to create the image
- *
- * @param[in] image_descriptor[in] Vendor specific image format
- *
- * @param[in] image_data Pointer to image backing store
- *
- * @param[in] access_permission Access permissions for the image object
- *
- * @param[out] image Created image object.
- *
- * @retval HSA_STATUS_SUCCESS Image created successfully
- *
- * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
- *
- * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
- * necessary resources
- *
- * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT Bad or mismatched descriptor,
- * null image_data, or mismatched access_permission.
- */
-hsa_status_t HSA_API hsa_amd_image_create(
-    hsa_agent_t agent,
-    const hsa_ext_image_descriptor_t *image_descriptor,
-    const hsa_amd_image_descriptor_t *image_layout,
-    const void *image_data,
-    hsa_access_permission_t access_permission,
-    hsa_ext_image_t *image
-);
-
 /**
  * @brief Denotes the type of memory in a pointer info query.
  */
@@ -2232,6 +2273,12 @@ hsa_status_t HSA_API hsa_amd_ipc_memory_attach(
  */
 hsa_status_t HSA_API hsa_amd_ipc_memory_detach(void* mapped_ptr);
 
+/** @} */
+
+/** \addtogroup status Runtime notifications
+ *  @{
+ */
+
 /**
  * @brief 256-bit process independent identifier for a ROCr IPC signal.
  */
@@ -2446,6 +2493,12 @@ typedef hsa_status_t (*hsa_amd_system_event_callback_t)(const hsa_amd_event_t* e
 hsa_status_t HSA_API hsa_amd_register_system_event_handler(hsa_amd_system_event_callback_t callback,
                                                    void* data);
 
+/** @} */
+
+/** \addtogroup queue Queues
+ *  @{
+ */
+
 /**
  * @brief Per-queue dispatch and wavefront scheduling priority.
  */
@@ -2483,6 +2536,12 @@ typedef enum hsa_amd_queue_priority_s {
 hsa_status_t HSA_API hsa_amd_queue_set_priority(hsa_queue_t* queue,
                                                 hsa_amd_queue_priority_t priority);
 
+/** @} */
+
+/** \addtogroup memory Memory
+ *  @{
+ */
+
 /**
  * @brief Deallocation notifier function type.
  */
@@ -2718,6 +2777,12 @@ hsa_status_t hsa_amd_svm_prefetch_async(void* ptr, size_t size, hsa_agent_t agen
                                         uint32_t num_dep_signals, const hsa_signal_t* dep_signals,
                                         hsa_signal_t completion_signal);
 
+/** @} */
+
+/** \addtogroup profile Profiling
+ *  @{
+ */
+
 /**
  * @brief Acquire Stream Performance Monitor on an agent
  *
@@ -2770,6 +2835,13 @@ hsa_status_t hsa_amd_spm_release(hsa_agent_t preferred_agent);
 hsa_status_t hsa_amd_spm_set_dest_buffer(hsa_agent_t preferred_agent, size_t size_in_bytes,
                                          uint32_t* timeout, uint32_t* size_copied, void* dest,
                                          bool* is_data_loss);
+
+/** @} */
+
+/** \addtogroup memory Memory
+ *  @{
+ */
+
 /**
  * @brief Obtains an OS specific, vendor neutral, handle to a memory allocation.
  *
@@ -3143,6 +3215,12 @@ hsa_status_t hsa_amd_vmem_get_alloc_properties_from_handle(
     hsa_amd_vmem_alloc_handle_t memory_handle, hsa_amd_memory_pool_t* pool,
     hsa_amd_memory_type_t* type);
 
+/** @} */
+
+/** \addtogroup queue Queues
+ *  @{
+ */
+
 /**
  * @brief Set the asynchronous scratch limit threshold on all the queues for this agent.
  * Dispatches that are enqueued on HW queues on this agent that are smaller than threshold will not
@@ -3210,6 +3288,8 @@ typedef enum hsa_amd_log_flag_s {
  */
 hsa_status_t hsa_amd_enable_logging(uint8_t* flags, void* file);
 
+/** @} */
+
 #ifdef __cplusplus
 }  // end extern "C" block
 #endif