TheRock/rocm-systems/projects/rocr-runtime/runtime/hsa-runtime/inc/hsa_ext_amd.h

////////////////////////////////////////////////////////////////////////////////
//
// The University of Illinois/NCSA
// Open Source License (NCSA)
//
// Copyright (c) 2014-2026, Advanced Micro Devices, Inc. All rights reserved.
//
// Developed by:
//
//                 AMD Research and AMD HSA Software Development
//
//                 Advanced Micro Devices, Inc.
//
//                 www.amd.com
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal with the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
//  - Redistributions of source code must retain the above copyright notice,
//    this list of conditions and the following disclaimers.
//  - Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimers in
//    the documentation and/or other materials provided with the distribution.
//  - Neither the names of Advanced Micro Devices, Inc,
//    nor the names of its contributors may be used to endorse or promote
//    products derived from this Software without specific prior written
//    permission.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
// OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS WITH THE SOFTWARE.
//
////////////////////////////////////////////////////////////////////////////////

// HSA AMD extension.

#ifndef HSA_RUNTIME_EXT_AMD_H_
#define HSA_RUNTIME_EXT_AMD_H_

#include "hsa.h"
#include "hsa_ext_image.h"
#include "hsa_ven_amd_pc_sampling.h"
#include "amd_launch_descriptor.h"

/**
 * - 1.0 - initial version
 * - 1.1 - dmabuf export
 * - 1.2 - hsa_amd_memory_async_copy_on_engine
 * - 1.3 - HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_EXTENDED_SCOPE_FINE_GRAINED pool
 * - 1.4 - Virtual Memory API
 * - 1.5 - hsa_amd_agent_info: HSA_AMD_AGENT_INFO_MEMORY_PROPERTIES
 * - 1.6 - Virtual Memory API: hsa_amd_vmem_address_reserve_align
 * - 1.7 - hsa_amd_signal_wait_all
 * - 1.8 - hsa_amd_memory_get_preferred_copy_engine
 * - 1.9 - hsa_amd_portable_export_dmabuf_v2
 * - 1.10 - hsa_amd_vmem_address_reserve: HSA_AMD_VMEM_ADDRESS_NO_REGISTER
 * - 1.11 - hsa_amd_agent_info_t: HSA_AMD_AGENT_INFO_CLOCK_COUNTERS
 * - 1.12 - hsa_amd_pointer_info: HSA_EXT_POINTER_TYPE_HSA_VMEM and HSA_EXT_POINTER_TYPE_RESERVED_ADDR
 * - 1.13 - hsa_amd_pointer_info: Added new registered field to hsa_amd_pointer_info_t
 * - 1.14 - hsa_amd_ais_file_write, hsa_amd_ais_file_read
 * - 1.15 - hsa_amd_register_system_event_handler: HSA_AMD_SYSTEM_SHUTDOWN
 * - 1.16 - hsa_amd_counted_queue APIs
 * - 1.17 - hsa_amd_memory_async_batch_copy
 * - 1.18 - hsa_amd_pointer_info: Added alloc_flags field to hsa_amd_pointer_info_t
 * - 1.19 - hsa_amd_agent_preload
 * - 1.20 - Memory batch discard API: hsa_amd_svm_discard_batch_async
 * - 1.21 - hsa_amd_signal_get_event_id
 * - 1.22 - hsa_amd_queue_get_info: per-queue VM fault state queries
 * - 1.23 - hsa_amd_agent_info_t: HSA_AMD_AGENT_INFO_MAX_DATA_PREFETCH_REGIONS
 * - 1.24 - hsa_amd_external_semaphore_handle_open/hsa_amd_external_semaphore_handle_close
 * - 1.25 - hsa_amd_vmem_export_fabric_handle, hsa_amd_vmem_import_fabric_handle
 * - 1.26 - hsa_amd_queue_create: batch queue creation with descriptor
 * - 1.27 - hsa_amd_queue_signal_external_semaphore, hsa_amd_queue_wait_external_semaphore
 * - 1.28 - hsa_amd_agent_info_t: HSA_AMD_AGENT_INFO_HOST_ALLOC_DMABUF_SUPPORTED
 * - 1.29 - hsa_amd_image_create_v2, hsa_amd_interop_map_buffer_with_size
 * - 1.30 - hsa_amd_queue_get_info: engine type and SDMA engine ID
 */
#define HSA_AMD_INTERFACE_VERSION_MAJOR 1
#define HSA_AMD_INTERFACE_VERSION_MINOR 30

#ifdef __cplusplus
extern "C" {
#endif

/** \addtogroup aql Architected Queuing Language
 *  @{
 */

/**
 * @brief Macro to set a flag within uint8_t[8] types.
 */
static inline void hsa_flag_set64(uint8_t* value, uint32_t bit) {
  unsigned int index = bit / 8;
  unsigned int subBit = bit % 8;
  (((uint8_t*)value)[index]) |= (1 << subBit);
}

/**
 * @brief Macro to determine whether a flag is set within uint8_t[8] types.
 */
static inline bool hsa_flag_isset64(uint8_t* value, uint32_t bit) {
  unsigned int index = bit / 8;
  unsigned int subBit = bit % 8;
  return ((uint8_t*)value)[index] & (1 << subBit);
}

/**
 * @brief A fixed-size type used to represent ::hsa_signal_condition_t constants.
 */
typedef uint32_t hsa_signal_condition32_t;

/**
 * @brief AMD vendor specific packet type.
 */
typedef enum {
  /**
   * Packet used by agents to delay processing of subsequent packets until a
   * configurable condition is satisfied by an HSA signal.  Only kernel dispatch
   * queues created from AMD GPU Agents support this packet.
   */
  HSA_AMD_PACKET_TYPE_BARRIER_VALUE = 2,

  /**
   * Extended kernel dispatch packet that supports clusters, an explicit
   * dependency signal, and additional performance-oriented features.
   */
  HSA_AMD_PACKET_TYPE_EXT_KERNEL_DISPATCH = 3,

  /* Reserved for a packet that is not yet released */
  HSA_AMD_PACKET_TYPE_RESERVED200 = 200,
} hsa_amd_packet_type_t;

/**
 * @brief A fixed-size type used to represent ::hsa_amd_packet_type_t constants.
 */
typedef uint8_t hsa_amd_packet_type8_t;

/**
 * @brief AMD vendor specific AQL packet header
 */
typedef struct hsa_amd_packet_header_s {
  /**
   * Packet header. Used to configure multiple packet parameters such as the
   * packet type. The parameters are described by ::hsa_packet_header_t.
   */
  uint16_t header;

  /**
   * Format of the vendor specific packet.
   */
  hsa_amd_packet_type8_t AmdFormat;

  /**
   * Reserved. Must be 0 unless explicitly stated otherwise per packet.
   *
   * HSA_AMD_PACKET_TYPE_EXT_KERNEL_DISPATCH uses this for the setup field.
   */
  uint8_t reserved;
} hsa_amd_vendor_packet_header_t;

/**
 * @brief AMD barrier value packet.  Halts packet processing and waits for
 * (signal_value & ::mask) ::cond ::value to be satisfied, where signal_value
 * is the value of the signal ::signal.
 */
typedef struct hsa_amd_barrier_value_packet_s {
  /**
   * AMD vendor specific packet header.
   */
  hsa_amd_vendor_packet_header_t header;

  /**
   * Reserved. Must be 0.
   */
  uint32_t reserved0;

  /**
   * Dependent signal object. A signal with a handle value of 0 is
   * allowed and is interpreted by the packet processor a satisfied
   * dependency.
   */
  hsa_signal_t signal;

  /**
   * Value to compare against.
   */
  hsa_signal_value_t value;

  /**
   * Bit mask to be combined by bitwise AND with ::signal's value.
   */
  hsa_signal_value_t mask;

  /**
   * Comparison operation.  See ::hsa_signal_condition_t.
   */
  hsa_signal_condition32_t cond;

  /**
   * Reserved. Must be 0.
   */
  uint32_t reserved1;

  /**
   * Reserved. Must be 0.
   */
  uint64_t reserved2;

  /**
   * Reserved. Must be 0.
   */
  uint64_t reserved3;

  /**
   * Signal used to indicate completion of the job. The application can use the
   * special signal handle 0 to indicate that no signal is used.
   */
  hsa_signal_t completion_signal;
} hsa_amd_barrier_value_packet_t;

/**
 * @brief Enumeration constants corresponding to the sub-fields of
 * @ref hsa_amd_ext_perf_hint_t. Their values are equal to the offset (in bits)
 * inside the overall hint structure.
 */
typedef enum {
  HSA_AMD_EXT_PERF_HINT_GROUP_MEM_CARVEOUT = 0,
  HSA_AMD_EXT_PERF_HINT_REVERSE_DISPATCH_ORDER = 7,
} hsa_amd_ext_perf_hint_subfield_t;

/**
 * @brief Width (in bits) of the sub-fields in @ref hsa_amd_ext_perf_hint_t.
 */
typedef enum {
  HSA_AMD_EXT_PERF_HINT_WIDTH_GROUP_MEM_CARVEOUT = 7,
  HSA_AMD_EXT_PERF_HINT_WIDTH_REVERSE_DISPATCH_ORDER = 1,
} hsa_amd_ext_perf_hint_subfield_width_t;

/**
 * @brief Performance hints used by @ref hsa_amd_ext_kernel_dispatch_packet_t.
 *
 * The sub-fields of this packet give performance optimization hints to
 * an agent, associated with a grid dispatch. The values of the sub-fields in
 * this packet are only hints; the agent may choose to ignore them.
 */
typedef union {
  struct {
    /**
     * Group-memory-available storage in each compute unit that is requested to
     * be reserved for group memory. In agents that can reconfigure CU storage
     * to be used for other purposes (e.g., caches), this hints to the agent
     * what fraction of that storage should be reserved for group memory.
     * Increasing this value may increase the number of workgroups that can be
     * simultaneously active on a compute unit.
     *
     * This 7b field can hold 0-127. A value of 0 allows the agent to decide
     * the configuration. The remaining encodings [1, 127] represent a range
     * from 0% (no group memory) to 100% (maximum group memory).
     *
     * Setting the requested amount lower than the group memory a single
     * workgroup needs will not cause the dispatch to fail; the hint may
     * instead be ignored or raised by the agent to a level necessary to allow
     * at least one workgroup to run in the compute units.​
     */
    uint8_t group_mem_carveout : 7;

    /**
     * Boolean that hints to the hardware that the agent may benefit from
     * making workgroups active in reverse order.
     *
     * The HSA Platform System Architecture Specification Version 1.2
     * (Section 2.11) implies that agents generally launch from lowest flattened
     * workgroup ID to higher. Setting this hint to 1 indicates that this
     * dispatch may benefit from launching highest-to-lower.
     *
     * Setting this bit to 1 will remove kernel dispatch forward progress
     * guarantees from the associated dispatch.
     *
     * Legal values are 0 and 1.​
     */
    uint8_t reverse_dispatch_order : 1;
  };

  uint8_t hint_val;
} hsa_amd_ext_perf_hint_t;

/**
 * @brief AMD extended kernel dispatch packet.
 */
typedef struct hsa_amd_ext_kernel_dispatch_packet_s {
  /**
   * Packet header. Used to configure multiple packet parameters such as the
   * packet type. The parameters are described by hsa_packet_header_t.
   *
   * The hsa_packet_type_t in this header must be
   * HSA_PACKET_TYPE_VENDOR_SPECIFIC.​
   */
  uint16_t header;

  /**
   * AMD vendor-specific packet type. Used to configure which vendor packet this
   * is. The parameters are described by hsa_amd_packet_type_t. This packet is
   * of type HSA_AMD_PACKET_TYPE_EXT_KERNEL_DISPATCH.​
   */
  hsa_amd_packet_type8_t amd_format;

  /**
   * Dispatch setup parameters. Used to configure kernel dispatch parameters
   * such as the number of dimensions in the grid. The parameters are described
   * by hsa_kernel_dispatch_packet_setup_t.​
   */
  uint8_t setup;

  /**
   * X dimension of work-group, in work-items. Must be greater than 0.​
   */
  uint16_t workgroup_size_x;

  /**
   * Y dimension of work-group, in work-items. Must be greater than 0. If the
   * grid has 1 dimension, the only valid value is 1.​
   */
  uint16_t workgroup_size_y;

  /**
   * Z dimension of work-group, in work-items. Must be greater than 0. If the
   * grid has 1 or 2 dimensions, the only valid value is 1.​
   */
  uint16_t workgroup_size_z;

  /**
   * Reserved. Must be 0.​
   */
  uint16_t reserved0;

  /**
   * X dimension of grid, in clusters. Must be greater than 0.​
   */
  uint32_t cluster_count_x;

  /**
   * Y dimension of grid, in clusters. Must be greater than 0.​ If the grid has
   * 1 dimension, the only valid value is 1.​
   */
  uint16_t cluster_count_y;

  /**
   * Z dimension of grid, in clusters. Must be greater than 0.​ If the grid has
   * 1 or 2 dimensions, the only valid value is 1.​
   */
  uint16_t cluster_count_z;

  /**
   * X dimension of cluster, in workgroups. Must be greater than 0.​
   */
  uint8_t cluster_size_x;

  /**
   * Y dimension of cluster, in workgroups. Must be greater than 0.​​ If the grid
   * has 1 dimension, the only valid value is 1.​
   */
  uint8_t cluster_size_y;

  /**
   * Z dimension of cluster, in workgroups. Must be greater than 0.​​ If the grid
   * has 1 or 2 dimensions, the only valid value is 1.​
   */
  uint8_t cluster_size_z;

  /**
   * Performance hints for the grid dispatched using this packet. The values in
   * these fields are only hints, and the agent may choose to do nothing with
   * them. The parameters are described by hsa_amd_ext_perf_hint_t.​
   */
  hsa_amd_ext_perf_hint_t perf_hint;

  /**
   * Size in bytes of private memory allocation request (per work-item).​
   */
  uint32_t private_segment_size;

  /**
   * Size in bytes of group memory allocation request (per work-group).
   *
   * Must not be less than the sum of the group memory used by the kernel (and
   * the functions it calls directly or indirectly) and the dynamically
   * allocated group segment variables.​
   */
  uint32_t group_segment_size;

  /**
   * Opaque handle to a code object that includes an implementation-defined
   * executable code for the kernel.​
   */
  uint64_t kernel_object;

  /**
   * Pointer to a buffer containing the kernel arguments. May be NULL. The
   * buffer must be allocated using hsa_memory_allocate, and must not be
   * modified once the kernel dispatch packet is enqueued until the dispatch
   * has completed execution.​
   */
  void* kernarg_address;

  /**
   * Dependent signal object. This signal is read in the launch phase.​
   *
   * The packet processor does not exit the launch phase for this packet, and
   * thus does not perform the requested acquire fence scope’s actions, until
   * the signal has been observed with the value 0.​
   *
   * A signal handle value of 0 is allowed and is interpreted by the packet
   * processor as a satisfied dependency.​
   */
  hsa_signal_t dep_signal;

  /**
   * Signal used to indicate completion of the job. The application can use the
   * special signal handle 0 to indicate that no signal is used.​
   */
  hsa_signal_t completion_signal;
} hsa_amd_ext_kernel_dispatch_packet_t;

/** @} */

/** \defgroup error-codes Error codes
 *  @{
 */

/**
 * @brief Sub-fields of the @a header field that is present in any metadata
 * packet. The offset (with respect to the address of @a header) of a sub-field
 * is identical to its enumeration constant. The width of each sub-field is
 * determined by the corresponding value in ::hsa_packet_header_width_t. The
 * offset and the width are expressed in bits.
 */
typedef enum {
  /**
   * Packet type. The value of this sub-field must be one of
   * ::hsa_packet_type_t. If the type is ::HSA_PACKET_TYPE_VENDOR_SPECIFIC, the
   * packet layout is vendor-specific.
   */
  HSA_AMD_METADATA_PACKET_HEADER_TYPE = 0,
  /**
   * Reserved
   */
  HSA_AMD_METADATA_PACKET_HEADER_RESERVED = 8,
  /**
   * Packet version major.
   */
  HSA_AMD_METADATA_PACKET_HEADER_VERSION_MAJOR = 24,
  /**
   * Packet version minor.
   */
  HSA_AMD_METADATA_PACKET_HEADER_VERSION_MINOR = 27,
} hsa_amd_metadata_packet_header_t;

/**
 * @brief Width (in bits) of the sub-fields in ::hsa_amd_metadata_packet_header_t.
 */
typedef enum hsa_amd_metadata_packet_header_width_s {
  HSA_AMD_METADATA_PACKET_HEADER_WIDTH_TYPE = 8,
  HSA_AMD_METADATA_PACKET_HEADER_WIDTH_RESERVED = 16,
  HSA_AMD_METADATA_PACKET_HEADER_WIDTH_VERSION_MAJOR = 3,
  HSA_AMD_METADATA_PACKET_HEADER_WIDTH_VERSION_MINOR = 5,
} hsa_amd_metadata_packet_header_width_t;

/**
 * @brief Number of valid kernarg preload d-words in meta-data packet
 */
typedef struct hsa_amd_metadata_preload_s {
  /* The number of dwords from the kernarg segment to preload into User SGPRs */
  uint16_t length : 7;
  /* Offset in dwords into the kernarg segment to begin preloading data into User SGPRs */
  uint16_t offset : 9;
} hsa_amd_metadata_preload_t;

/**
 * @brief AMD meta-data Kernel Dispatch Descriptor fields
 */
typedef struct hsa_amd_metadata_kernel_descriptor_s {
  int64_t kernel_code_entry_byte_offset;
  uint8_t reserved1[20];
  uint32_t compute_pgm_rsrc3;
  uint32_t compute_pgm_rsrc1;
  uint32_t compute_pgm_rsrc2;
  uint16_t kernel_code_properties;
  hsa_amd_metadata_preload_t kernarg_preload;
  uint8_t reserved2[4];
} hsa_amd_metadata_kernel_descriptor_t;

/**
 * @brief AMD meta-data Kernel Dispatch packet.
 */
typedef struct hsa_amd_metadata_kernel_dispatch_packet_s {
  /**
   * Packet header. Used to configure multiple packet parameters such as the
   * packet type. The parameters are described by hsa_amd_metadata_packet_header_t.
   */
  uint32_t header0;
  /**
   * Event ID. HW ID of the completion signal. This corresponds to the event_id
   * of amd_signal_t
   */
  uint32_t event_id;
  /**
   * Kernel descriptor pre-load fields
   */
  hsa_amd_metadata_kernel_descriptor_t kernel_descriptor;
  /**
   * Reserved. Must be 0.
   */
  uint8_t reserved0[8];
  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header1;
  /**
   * Kernarg preload 0 through 14
   */
  uint32_t kernarg_preload_0_14[15];
  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header2;
  /**
   * Kernarg preload 15 through 29
   */
  uint32_t kernarg_preload_15_29[15];
  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header3;
  /**
   * Kernarg preload 30 through 31
   */
  uint32_t kernarg_preload_30_31[2];
  union {
    /**
     * Reserved. Must be 0.
     */
    uint8_t reserved1[52];
    /**
     * Launch descriptor. Overlays the former reserved1[52] area.
     * Zero-initialised means version=0 (NONE) — CP treats as "no descriptor".
     */
    amd_launch_descriptor_t launch_descriptor;
  };
} hsa_amd_metadata_kernel_dispatch_packet_t;

/**
 * @brief AMD meta-data Kernel Dispatch packet.
 */
typedef struct hsa_amd_metadata_barrier_packet_s {
  /**
   * Packet header. Used to configure multiple packet parameters such as the
   * packet type. The parameters are described by hsa_amd_metadata_packet_header_t.
   */
  uint32_t header0;
  /**
   * Event ID. HW ID of the completion signal. This corresponds to the event_id
   * of amd_signal_t
   */
  uint32_t event_id;
  /**
   * Reserved. Must be 0.
   */
  uint8_t reserved0[56];

  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header1;
  /**
   * Reserved. Must be 0.
   */
  uint8_t reserved1[60];
  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header2;
  /**
   * Reserved. Must be 0.
   */
  uint8_t reserved2[60];
  /**
   * Packet header. Must be same value as header0
   */
  uint32_t header3;
  /**
   * Reserved. Must be 0.
   */
  uint8_t reserved3[60];
} hsa_amd_metadata_barrier_packet_t;

/**
 * @brief Enumeration constants added to ::hsa_status_t.
 *
 * @remark Additions to hsa_status_t
 */
enum {
  /**
   * The memory pool is invalid.
   */
  HSA_STATUS_ERROR_INVALID_MEMORY_POOL = 40,

  /**
   * Agent accessed memory beyond the maximum legal address.
   */
  HSA_STATUS_ERROR_MEMORY_APERTURE_VIOLATION = 41,

  /**
   * Agent executed an invalid shader instruction.
   */
  HSA_STATUS_ERROR_ILLEGAL_INSTRUCTION = 42,

  /**
   * Agent attempted to access an inaccessible address.
   * See hsa_amd_register_system_event_handler and
   * HSA_AMD_GPU_MEMORY_FAULT_EVENT for more information on illegal accesses.
   */
  HSA_STATUS_ERROR_MEMORY_FAULT = 43,

  /**
   * The CU mask was successfully set but the mask attempted to enable a CU
   * which was disabled for the process.  CUs disabled for the process remain
   * disabled.
   */
  HSA_STATUS_CU_MASK_REDUCED = 44,

  /**
   * Exceeded number of VGPRs available on this agent
   */
  HSA_STATUS_ERROR_OUT_OF_REGISTERS = 45,

  /**
   * Resource is busy or temporarily unavailable
   */
  HSA_STATUS_ERROR_RESOURCE_BUSY = 46,

  /**
   * Request is not supported by this system
   */
  HSA_STATUS_ERROR_NOT_SUPPORTED = 47,

  /**
   * Xnack is disabled on this system, but required
   * by the requested operation.
   */
  HSA_STATUS_ERROR_XNACK_DISABLED = 48,

  /**
   * The kernel dispatch packet parameters exceed hardware limits for this
   * agent (e.g. register usage, work-group dimensions, or other dispatch
   * constraints enforced by the command processor).
   */
  HSA_STATUS_ERROR_INVALID_DISPATCH_PARAMETERS = 49,

  /**
   * Underlying resource is a valid resource, but it is not ready to be used.
   */
  HSA_STATUS_ERROR_RESOURCE_NOT_READY = 50,
};

/** @} */

/** \addtogroup memory Memory
 *  @{
 */

/**
 * @brief Dispatch dimension limits
 */
typedef struct hsa_amd_dim3_s {
    uint64_t x;
    uint64_t y;
    uint64_t z;
} hsa_amd_dim3_t;

/**
 * @brief IOMMU version supported
 */
typedef enum {
  /**
   * IOMMU not supported
   */
  HSA_IOMMU_SUPPORT_NONE = 0,
  /* IOMMU V1 support is not relevant to user applications, so not reporting it */
  /**
   * IOMMU V2 supported
   */
  HSA_IOMMU_SUPPORT_V2 = 1,
} hsa_amd_iommu_version_t;

/**
 * @brief Structure containing information on the agent's clock counters.
 */
typedef struct hsa_amd_clock_counters_s {
  uint64_t gpu_clock_counter;
  uint64_t cpu_clock_counter;
  uint64_t system_clock_counter;
  uint64_t system_clock_frequency;
} hsa_amd_clock_counters_t;

/**
 * @brief Agent attributes.
 */
typedef enum hsa_amd_agent_info_s {
  /**
   * Chip identifier. The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_CHIP_ID = 0xA000,
  /**
   * Size of a cacheline in bytes. The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_CACHELINE_SIZE = 0xA001,
  /**
   * The number of compute unit available in the agent. The type of this
   * attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT = 0xA002,
  /**
   * The maximum clock frequency of the agent in MHz. The type of this
   * attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_MAX_CLOCK_FREQUENCY = 0xA003,
  /**
   * Internal driver node identifier. The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_DRIVER_NODE_ID = 0xA004,
  /**
   * Max number of watch points on memory address ranges to generate exception
   * events when the watched addresses are accessed.  The type of this
   * attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_MAX_ADDRESS_WATCH_POINTS = 0xA005,
  /**
   * Agent BDF_ID, named LocationID in thunk. The type of this attribute is
   * uint32_t.
   */
  HSA_AMD_AGENT_INFO_BDFID = 0xA006,
  /**
   * Memory Interface width, the return value type is uint32_t.
   * This attribute is deprecated.
   */
  HSA_AMD_AGENT_INFO_MEMORY_WIDTH = 0xA007,
  /**
   * Max Memory Clock, the return value type is uint32_t.
   */
  HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY = 0xA008,
  /**
   * Board name of Agent - populated from MarketingName of Kfd Node
   * The value is an Ascii string of 64 chars.
   */
  HSA_AMD_AGENT_INFO_PRODUCT_NAME = 0xA009,
  /**
   * Maximum number of waves possible in a Compute Unit.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_MAX_WAVES_PER_CU = 0xA00A,
  /**
   * Number of SIMD's per compute unit CU
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_SIMDS_PER_CU = 0xA00B,
  /**
   * Number of Shader Engines (SE) in Gpu
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_SHADER_ENGINES = 0xA00C,
  /**
   * Number of Shader Arrays Per Shader Engines in Gpu
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_SHADER_ARRAYS_PER_SE = 0xA00D,
  /**
   * Address of the HDP flush registers.  Use of these registers does not conform to the HSA memory
   * model and should be treated with caution.
   * The type of this attribute is hsa_amd_hdp_flush_t.
   */
  HSA_AMD_AGENT_INFO_HDP_FLUSH = 0xA00E,
  /**
   * PCIe domain for the agent.  Pairs with HSA_AMD_AGENT_INFO_BDFID
   * to give the full physical location of the Agent.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_DOMAIN = 0xA00F,
  /**
   * Queries for support of cooperative queues.  See ::HSA_QUEUE_TYPE_COOPERATIVE.
   * The type of this attribute is bool.
   */
  HSA_AMD_AGENT_INFO_COOPERATIVE_QUEUES = 0xA010,
  /**
   * Queries UUID of an agent. The value is an Ascii string with a maximum
   * of 21 chars including NUL. The string value consists of two parts: header
   * and body. The header identifies device type (GPU, CPU, DSP) while body
   * encodes UUID as a 16 digit hex string
   *
   * Agents that do not support UUID will return the string "GPU-XX" or
   * "CPU-XX" or "DSP-XX" depending upon their device type ::hsa_device_type_t
   */
  HSA_AMD_AGENT_INFO_UUID = 0xA011,
  /**
   * Queries for the ASIC revision of an agent. The value is an integer that
   * increments for each revision. This can be used by user-level software to
   * change how it operates, depending on the hardware version. This allows
   * selective workarounds for hardware errata.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_ASIC_REVISION = 0xA012,
  /**
   * Queries whether or not the host can directly access SVM memory that is
   * physically resident in the agent's local memory.
   * The type of this attribute is bool.
   */
  HSA_AMD_AGENT_INFO_SVM_DIRECT_HOST_ACCESS = 0xA013,
  /**
   * Some processors support more CUs than can reliably be used in a cooperative
   * dispatch.  This queries the count of CUs which are fully enabled for
   * cooperative dispatch.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_COOPERATIVE_COMPUTE_UNIT_COUNT = 0xA014,
  /**
   * Queries the amount of memory available in bytes accross all global pools
   * owned by the agent.
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_AGENT_INFO_MEMORY_AVAIL = 0xA015,
  /**
   * Timestamp value increase rate, in Hz. The timestamp (clock) frequency is
   * in the range 1-400MHz.
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_AGENT_INFO_TIMESTAMP_FREQUENCY = 0xA016,
  /**
   * Queries for the ASIC family ID of an agent.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_ASIC_FAMILY_ID = 0xA107,
  /**
   * Queries for the Packet Processor(CP Firmware) ucode version of an agent.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_UCODE_VERSION = 0xA108,
  /**
   * Queries for the SDMA engine ucode of an agent.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_SDMA_UCODE_VERSION = 0xA109,
  /**
   * Queries the number of SDMA engines.
   * If HSA_AMD_AGENT_INFO_NUM_SDMA_XGMI_ENG query returns non-zero,
   * this query returns the the number of SDMA engines optimized for
   * host to device bidirectional traffic.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_SDMA_ENG = 0xA10A,
  /**
   * Queries the number of additional SDMA engines optimized for D2D xGMI copies.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_SDMA_XGMI_ENG = 0xA10B,
  /**
   * Queries for version of IOMMU supported by agent.
   * The type of this attribute is hsa_amd_iommu_version_t.
   */
  HSA_AMD_AGENT_INFO_IOMMU_SUPPORT = 0xA110,
  /**
   * Queries for number of XCCs within the agent.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_NUM_XCC = 0xA111,
  /**
   * Queries for driver unique identifier.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_AGENT_INFO_DRIVER_UID = 0xA112,
  /**
   * Returns the hsa_agent_t of the nearest CPU agent
   * The type of this attribute is hsa_agent_t.
   */
  HSA_AMD_AGENT_INFO_NEAREST_CPU = 0xA113,
  /**
   * Bit-mask indicating memory properties of this agent. A memory property is set if the flag bit
   * is set at that position. User may use the hsa_flag_isset64 macro to verify whether a flag
   * is set. The type of this attribute is uint8_t[8].
   */
  HSA_AMD_AGENT_INFO_MEMORY_PROPERTIES = 0xA114,
  /**
   * Bit-mask indicating AQL Extensions supported by this agent. An AQL extension is set if the flag
   * bit is set at that position. User may use the hsa_flag_isset64 macro to verify whether a flag
   * is set. The type of this attribute is uint8_t[8].
   */
  HSA_AMD_AGENT_INFO_AQL_EXTENSIONS = 0xA115,
  /**
   * Maximum allowed value in bytes for scratch limit for this agent. This amount
   * is shared accross all queues created on this agent.
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_AGENT_INFO_SCRATCH_LIMIT_MAX = 0xA116,
  /**
   * Current scratch limit threshold in bytes for this agent. This limit can be
   * modified using the hsa_amd_agent_set_async_scratch_limit call.
   * - AQL dispatches that require scratch-memory above this threshold will trigger a
   *   scratch use-once.
   * - AQL dispatches using less scratch-memory than this threshold, ROCr will
   *   permanently assign the allocated scratch memory to the queue handling the dispatch.
   *   This memory can be reclaimed by calling hsa_amd_agent_set_async_scratch_limit
   *   with a lower threshold by current value.
   *
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_AGENT_INFO_SCRATCH_LIMIT_CURRENT = 0xA117,
  /**
   * Queries the driver for clock counters of the agent.
   * The type of this attribute is hsa_amd_clock_counters_t.
   */
  HSA_AMD_AGENT_INFO_CLOCK_COUNTERS = 0xA118,
  /**
   * The agent uses PM4 emulation mode.
   */
  HSA_AMD_AGENT_INFO_PM4_EMULATION = 0xA119,
  /**
   * Queries for the LUID that identifies a hardware node. The LUID is only
   * valid on Windows. The type of this attribute is LUID.
   */
  HSA_AMD_AGENT_INFO_LUID = 0xA11A,
  /**
   * The agent supports expert scheduling mode. The type of this attribute is bool.
   */
  HSA_AMD_AGENT_INFO_HAS_EXPERT_SCHED_MODE = 0xA11B,
  /**
   * Queries the secondary CUID (128-bit UUID (16 bytes) in UUIDv8 format)
   * of a CPU/GPU agent. The type of this attribute is uint8_t[16].
   */
  HSA_AMD_AGENT_INFO_CUID = 0xA11C,
  /*
   * Maximum number of work-groups across all dimensions for non-clustered dispatches.
   * Returns uint64_t into value output
   */
  HSA_AMD_AGENT_INFO_KERNEL_WG_MAX_SIZE = 0xA11D,
  /**
   * Maximum number of clusters in each dimension for clustered dispatches.
   * Returns hsa_amd_dim3_t into value output.
   */
  HSA_AMD_AGENT_INFO_KERNEL_CLUSTER_MAX_DIM = 0xA11E,
  /*
   * Maximum number of clusters across all dimensions for clustered dispatches
   * Returns uint64_t into value output
   */
  HSA_AMD_AGENT_INFO_KERNEL_CLUSTER_MAX_SIZE = 0xA11F,
  /*
   * Maximum number of workgroups in a cluster in each dimension
   * Returns hsa_amd_dim3_t into value output
   */
  HSA_AMD_AGENT_INFO_CLUSTER_MAX_DIM = 0xA120,
  /*
   * Maximum number of workgroups in a cluster across all dimensions
   * Returns uint64_t into value output
   */
  HSA_AMD_AGENT_INFO_CLUSTER_MAX_SIZE = 0xA121,
  /*
   * Maximum number of work-groups in each dimension for non-clustered dispatches.
   * Returns hsa_amd_dim3_t into value output.
   */
  HSA_AMD_AGENT_INFO_KERNEL_WG_MAX_DIM = 0xA122,
  /*
   * Maximum number of L2 data prefetch regions supported per kernel dispatch.
   * Returns uint32_t. Zero if the device does not support dynamic data prefetch.
   */
  HSA_AMD_AGENT_INFO_MAX_DATA_PREFETCH_REGIONS = 0xA123,
  /**
   * Queries whether the agent supports virtual memory API operations on
   * host memory that can be exported as a DMA-BUF file descriptor.
   * For CPU agents: indicates host memory can be allocated and exported.
   * For GPU agents: indicates the GPU can access such host-allocated memory.
   * The type of this attribute is bool.
   */
  HSA_AMD_AGENT_INFO_HOST_ALLOC_DMABUF_SUPPORTED = 0xA124,
} hsa_amd_agent_info_t;

/**
 * @brief Agent memory properties attributes
 */
typedef enum hsa_amd_agent_memory_properties_s {
  HSA_AMD_MEMORY_PROPERTY_AGENT_IS_APU = (1 << 0),
} hsa_amd_agent_memory_properties_t;

/**
 * @brief Agent AQL info properties attributes
 */
typedef enum hsa_amd_agent_aql_properties_s {
  HSA_AMD_AQL_PROPERTY_EXT_DISPATCH = (1 << 0),
} hsa_amd_agent_aql_properties_t;

/**
 * @brief SDMA engine IDs unique by single set bit position.
 */
typedef enum hsa_amd_sdma_engine_id {
  HSA_AMD_SDMA_ENGINE_0 = 0x1,
  HSA_AMD_SDMA_ENGINE_1 = 0x2,
  HSA_AMD_SDMA_ENGINE_2 = 0x4,
  HSA_AMD_SDMA_ENGINE_3 = 0x8,
  HSA_AMD_SDMA_ENGINE_4 = 0x10,
  HSA_AMD_SDMA_ENGINE_5 = 0x20,
  HSA_AMD_SDMA_ENGINE_6 = 0x40,
  HSA_AMD_SDMA_ENGINE_7 = 0x80,
  HSA_AMD_SDMA_ENGINE_8 = 0x100,
  HSA_AMD_SDMA_ENGINE_9 = 0x200,
  HSA_AMD_SDMA_ENGINE_10 = 0x400,
  HSA_AMD_SDMA_ENGINE_11 = 0x800,
  HSA_AMD_SDMA_ENGINE_12 = 0x1000,
  HSA_AMD_SDMA_ENGINE_13 = 0x2000,
  HSA_AMD_SDMA_ENGINE_14 = 0x4000,
  HSA_AMD_SDMA_ENGINE_15 = 0x8000
} hsa_amd_sdma_engine_id_t;

typedef struct hsa_amd_hdp_flush_s {
  uint32_t* HDP_MEM_FLUSH_CNTL;
  uint32_t* HDP_REG_FLUSH_CNTL;
} hsa_amd_hdp_flush_t;

/**
 * @brief Region attributes.
 */
#ifdef __cplusplus
typedef enum hsa_amd_region_info_s : int {
#else
typedef enum hsa_amd_region_info_s {
#endif
  /**
   * Determine if host can access the region. The type of this attribute
   * is bool.
   */
  HSA_AMD_REGION_INFO_HOST_ACCESSIBLE = 0xA000,
  /**
   * Base address of the region in flat address space.
   */
  HSA_AMD_REGION_INFO_BASE = 0xA001,
  /**
   * Memory Interface width, the return value type is uint32_t.
   * This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_WIDTH.
   */
  HSA_AMD_REGION_INFO_BUS_WIDTH = 0xA002,
  /**
   * Max Memory Clock, the return value type is uint32_t.
   * This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY.
   */
  HSA_AMD_REGION_INFO_MAX_CLOCK_FREQUENCY = 0xA003,
} hsa_amd_region_info_t;

/**
 * @brief Coherency attributes of fine grain region.
 */
typedef enum hsa_amd_coherency_type_s {
  /**
   * Coherent region.
   */
  HSA_AMD_COHERENCY_TYPE_COHERENT = 0,
  /**
   * Non coherent region.
   */
  HSA_AMD_COHERENCY_TYPE_NONCOHERENT = 1
} hsa_amd_coherency_type_t;


/**
 * @brief dmabuf attributes
 */
#ifdef __cplusplus
typedef enum hsa_amd_dma_buf_mapping_type_s : int {
#else
typedef enum hsa_amd_dma_buf_mapping_type_s {
#endif
  HSA_AMD_DMABUF_MAPPING_TYPE_NONE = 0,
  HSA_AMD_DMABUF_MAPPING_TYPE_PCIE = 1
} hsa_amd_dma_buf_mapping_type_t;
/**
 * @brief Get the coherency type of the fine grain region of an agent.
 *
 * @param[in] agent A valid agent.
 *
 * @param[out] type Pointer to a memory location where the HSA runtime will
 * store the coherency type of the fine grain region.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p type is NULL.
 */
hsa_status_t HSA_API hsa_amd_coherency_get_type(hsa_agent_t agent,
                                                hsa_amd_coherency_type_t* type);

/**
 * @brief Set the coherency type of the fine grain region of an agent.
 * Deprecated.  This is supported on KV platforms.  For backward compatibility
 * other platforms will spuriously succeed.
 *
 * @param[in] agent A valid agent.
 *
 * @param[in] type The coherency type to be set.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p type is invalid.
 */
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.
 *
 * Times are reported as ticks in the domain of the HSA system clock.
 * The HSA system clock tick and frequency is obtained via hsa_system_get_info.
 */
typedef struct hsa_amd_profiling_dispatch_time_s {
  /**
   * Dispatch packet processing start time.
   */
  uint64_t start;
  /**
   * Dispatch packet completion time.
   */
  uint64_t end;
} hsa_amd_profiling_dispatch_time_t;

/**
 * @brief Structure containing profiling async copy time information.
 *
 * Times are reported as ticks in the domain of the HSA system clock.
 * The HSA system clock tick and frequency is obtained via hsa_system_get_info.
 */
typedef struct hsa_amd_profiling_async_copy_time_s {
  /**
   * Async copy processing start time.
   */
  uint64_t start;
  /**
   * Async copy completion time.
   */
  uint64_t end;
} hsa_amd_profiling_async_copy_time_t;

/**
 * @brief Enable or disable profiling capability of a queue.
 *
 * @param[in] queue A valid queue.
 *
 * @param[in] enable 1 to enable profiling. 0 to disable profiling.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE The queue is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p queue is NULL.
 */
hsa_status_t HSA_API
    hsa_amd_profiling_set_profiler_enabled(hsa_queue_t* queue, int enable);

/**
 * @brief Enable or disable asynchronous memory copy profiling.
 *
 * @details The runtime will provide the copy processing start timestamp and
 * completion timestamp of each call to hsa_amd_memory_async_copy if the
 * async copy profiling is enabled prior to the call to
 * hsa_amd_memory_async_copy. The completion signal object is used to
 * hold the last async copy start and end timestamp. The client can retrieve
 * these timestamps via call to hsa_amd_profiling_get_async_copy_time.
 *
 * @param[in] enable True to enable profiling. False to disable profiling.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Failed on allocating resources
 * needed to profile the asynchronous copy.
 */
hsa_status_t HSA_API
    hsa_amd_profiling_async_copy_enable(bool enable);

/**
 * @brief Flags for hsa_amd_agent_preload.
 *
 * @details By default, hsa_amd_agent_preload preloads all resources.
 * These flags can be used to skip specific resources.
 */
typedef enum hsa_amd_agent_preload_flag_s {
  /**
   * Skip preloading clock synchronization data.
   */
  HSA_AMD_AGENT_PRELOAD_SKIP_CLOCK_SYNC = (1 << 0),
  /**
   * Skip preloading blit kernel objects.
   */
  HSA_AMD_AGENT_PRELOAD_SKIP_BLITS = (1 << 1)
} hsa_amd_agent_preload_flag_t;

/**
 * @brief Performance hint to preload agent resources.
 *
 * @details Trigger early initialization of agent resources. By default,
 * all resources are preloaded. Use flags to skip specific resources.
 *
 * @param[in] agent The agent to preload resources for. Must be a GPU agent.
 *
 * @param[in] flags A bitwise OR of ::hsa_amd_agent_preload_flag_t values
 * specifying which resources to skip.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid or not a GPU.
 */
hsa_status_t HSA_API hsa_amd_agent_preload(hsa_agent_t agent, uint64_t flags);

/**
 * @brief Retrieve packet processing time stamps.
 *
 * @param[in] agent The agent with which the signal was last used.  For
 * instance, if the profiled dispatch packet is dispatched onto queue Q,
 * which was created on agent A, then this parameter must be A.
 *
 * @param[in] signal A signal used as the completion signal of the dispatch
 * packet to retrieve time stamps from.  This dispatch packet must have been
 * issued to a queue with profiling enabled and have already completed.  Also
 * the signal must not have yet been used in any other packet following the
 * completion of the profiled dispatch packet.
 *
 * @param[out] time Packet processing timestamps in the HSA system clock
 * domain.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL The signal is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p time is NULL.
 */
hsa_status_t HSA_API hsa_amd_profiling_get_dispatch_time(
    hsa_agent_t agent, hsa_signal_t signal,
    hsa_amd_profiling_dispatch_time_t* time);

/**
 * @brief Retrieve asynchronous copy timestamps.
 *
 * @details Async copy profiling is enabled via call to
 * hsa_amd_profiling_async_copy_enable.
 *
 * @param[in] signal A signal used as the completion signal of the call to
 * hsa_amd_memory_async_copy.
 *
 * @param[out] time Async copy processing timestamps in the HSA system clock
 * domain.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL The signal is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p time is NULL.
 */
hsa_status_t HSA_API hsa_amd_profiling_get_async_copy_time(
    hsa_signal_t signal, hsa_amd_profiling_async_copy_time_t* time);

/**
 * @brief Computes the frequency ratio and offset between the agent clock and
 * HSA system clock and converts the agent's tick to HSA system domain tick.
 *
 * @param[in] agent The agent used to retrieve the agent_tick. It is user's
 * responsibility to make sure the tick number is from this agent, otherwise,
 * the behavior is undefined.
 *
 * @param[in] agent_tick The tick count retrieved from the specified @p agent.
 *
 * @param[out] system_tick The translated HSA system domain clock counter tick.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p system_tick is NULL;
 */
hsa_status_t HSA_API
    hsa_amd_profiling_convert_tick_to_system_domain(hsa_agent_t agent,
                                                    uint64_t agent_tick,
                                                    uint64_t* system_tick);

/** @} */

/** \defgroup status Runtime notifications
 *  @{
 */

/**
 * @brief Signal attribute flags.
 */
typedef enum {
  /**
   * Signal will only be consumed by AMD GPUs.  Limits signal consumption to
   * AMD GPU agents only.  Ignored if @p num_consumers is not zero (all agents).
   */
  HSA_AMD_SIGNAL_AMD_GPU_ONLY = 1,
  /**
   * Signal may be used for interprocess communication.
   * IPC signals can be read, written, and waited on from any process.
   * Profiling using an IPC enabled signal is only supported in a single process
   * at a time.  Producing profiling data in one process and consuming it in
   * another process is undefined.
   */
  HSA_AMD_SIGNAL_IPC = 2,
} hsa_amd_signal_attribute_t;

/**
 * @brief Create a signal with specific attributes.
 *
 * @param[in] initial_value Initial value of the signal.
 *
 * @param[in] num_consumers Size of @p consumers. A value of 0 indicates that
 * any agent might wait on the signal.
 *
 * @param[in] consumers List of agents that might consume (wait on) the
 * signal. If @p num_consumers is 0, this argument is ignored; otherwise, the
 * HSA runtime might use the list to optimize the handling of the signal
 * object. If an agent not listed in @p consumers waits on the returned
 * signal, the behavior is undefined. The memory associated with @p consumers
 * can be reused or freed after the function returns.
 *
 * @param[in] attributes Requested signal attributes.  Multiple signal attributes
 * may be requested by combining them with bitwise OR.  Requesting no attributes
 * (@p attributes == 0) results in the same signal as would have been obtained
 * via hsa_signal_create.
 *
 * @param[out] signal Pointer to a memory location where the HSA runtime will
 * store the newly created signal handle. Must not be NULL.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate
 * the required resources.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p signal is NULL, @p
 * num_consumers is greater than 0 but @p consumers is NULL, or @p consumers
 * contains duplicates.
 */
hsa_status_t HSA_API hsa_amd_signal_create(hsa_signal_value_t initial_value, uint32_t num_consumers,
                                           const hsa_agent_t* consumers, uint64_t attributes,
                                           hsa_signal_t* signal);

/**
 * @brief Returns a pointer to the value of a signal.
 *
 * Use of this API does not modify the lifetime of ::signal and any
 * hsa_signal_value_t retrieved by this API has lifetime equal to that of
 * ::signal.
 *
 * This API is intended for partial interoperability with non-HSA compatible
 * devices and should not be used where HSA interfaces are available.
 *
 * Use of the signal value must comply with use restritions of ::signal.
 * Use may result in data races if the operations performed are not platform
 * atomic.  Use with HSA_AMD_SIGNAL_AMD_GPU_ONLY or HSA_AMD_SIGNAL_IPC
 * attributed signals is required.
 *
 * @param[in] Signal handle to extract the signal value pointer from.
 *
 * @param[out] Location where the extracted signal value pointer will be placed.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL signal is not a valid hsa_signal_t
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT value_ptr is NULL.
 */
hsa_status_t hsa_amd_signal_value_pointer(hsa_signal_t signal,
                                          volatile hsa_signal_value_t** value_ptr);

/**
 * @brief Asyncronous signal handler function type.
 *
 * @details Type definition of callback function to be used with
 * hsa_amd_signal_async_handler. This callback is invoked if the associated
 * signal and condition are met. The callback receives the value of the signal
 * which satisfied the associated wait condition and a user provided value. If
 * the callback returns true then the callback will be called again if the
 * associated signal and condition are satisfied again. If the callback returns
 * false then it will not be called again.
 *
 * @param[in] value Contains the value of the signal observed by
 * hsa_amd_signal_async_handler which caused the signal handler to be invoked.
 *
 * @param[in] arg Contains the user provided value given when the signal handler
 * was registered with hsa_amd_signal_async_handler
 *
 * @retval true resumes monitoring the signal with this handler (as if calling
 * hsa_amd_signal_async_handler again with identical parameters)
 *
 * @retval false stops monitoring the signal with this handler (handler will
 * not be called again for this signal)
 *
 */
typedef bool (*hsa_amd_signal_handler)(hsa_signal_value_t value, void* arg);

/**
 * @brief Register asynchronous signal handler function.
 *
 * @details Allows registering a callback function and user provided value with
 * a signal and wait condition. The callback will be invoked if the associated
 * signal and wait condition are satisfied. Callbacks will be invoked serially
 * but in an arbitrary order so callbacks should be independent of each other.
 * After being invoked a callback may continue to wait for its associated signal
 * and condition and, possibly, be invoked again. Or the callback may stop
 * waiting. If the callback returns true then it will continue waiting and may
 * be called again. If false then the callback will not wait again and will not
 * be called again for the associated signal and condition. It is possible to
 * register the same callback multiple times with the same or different signals
 * and/or conditions. Each registration of the callback will be treated entirely
 * independently.
 *
 * @param[in] signal hsa signal to be asynchronously monitored
 *
 * @param[in] cond condition value to monitor for
 *
 * @param[in] value signal value used in condition expression
 *
 * @param[in] handler asynchronous signal handler invoked when signal's
 * condition is met
 *
 * @param[in] arg user provided value which is provided to handler when handler
 * is invoked
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL signal is not a valid hsa_signal_t
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT handler is invalid (NULL)
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime is out of
 * resources or blocking signals are not supported by the HSA driver component.
 *
 */
hsa_status_t HSA_API
    hsa_amd_signal_async_handler(hsa_signal_t signal,
                                 hsa_signal_condition_t cond,
                                 hsa_signal_value_t value,
                                 hsa_amd_signal_handler handler, void* arg);

/**
 * @brief Wait for all signal-condition pairs to be satisfied.
 *
 * @details Allows waiting for all of several signal and condition pairs to be
 * satisfied. The function returns 0 if all signals met their conditions and -1
 * on a timeout. The value of each signal's satisfying value is returned in
 * satisfying_value unless satisfying_value is nullptr. NULL and invalid signals
 * are considered to have value 0 and their conditions already satisfied. This
 * function provides only relaxed memory semantics.
 */
uint32_t HSA_API hsa_amd_signal_wait_all(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_values);

/**
 * @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 function returns
 * std::numeric_limits<uint32_t>::max() if no valid signal is provided. The value
 * of the satisfying signal's value is returned in satisfying_value, unless
 * satisfying_value is nullptr or there's no valid signal in the signal-condition
 * pairs. NULL and invalid signals are ignored. 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 Get the underlying event-id for a HSA signal
 *
 * @details Returns the underlying HW event ID for an existing HSA signal.
 *
 * @param[in] signal The HSA signal
 * @param[out] event_id The returned event_id. The returned event_id may be 0
 * if the HSA signal is not a HW backed signal.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The signal is invalid
 */
hsa_status_t HSA_API
  hsa_amd_signal_get_event_id(hsa_signal_t signal, uint32_t *event_id);

/** @} */

/**
 * @brief Call a function asynchronously
 *
 * @details Provides access to the runtime's asynchronous event handling thread
 * for general asynchronous functions.  Functions queued this way are executed
 * in the same manner as if they were a signal handler who's signal is
 * satisfied.
 *
 * @param[in] callback asynchronous function to be invoked
 *
 * @param[in] arg user provided value which is provided to handler when handler
 * is invoked
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT handler is invalid (NULL)
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime is out of
 * resources or blocking signals are not supported by the HSA driver component.
 *
 */
hsa_status_t HSA_API
    hsa_amd_async_function(void (*callback)(void* arg), void* arg);

/** \addtogroup ext-images Images and samplers
 *  @{
 */

/**
 * @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 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 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 Vendor specific image format
 *
 * @param[in] image_layout Opaque vendor-specific image layout descriptor (may be NULL
 *                         when image metadata is not available from an interop source)
 *
 * @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_v2(
    hsa_agent_t agent,
    const hsa_ext_image_descriptor_v2_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.
 *
 * @param[in] agent A valid agent.
 *
 * @param[in] attribute HSA image info attribute to query.
 *
 * @param[out] value Pointer to an application-allocated buffer where to store
 * the value of the attribute. If the buffer passed by the application is not
 * large enough to hold the value of @p attribute, the behavior is undefined.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE @p value is NULL or @p attribute <
 * HSA_EXT_AGENT_INFO_IMAGE_1D_MAX_ELEMENTS or @p attribute >
 * HSA_EXT_AGENT_INFO_IMAGE_ARRAY_MAX_LAYERS.
 *
 */
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.
 *
 * @details Enables the queue to run on only selected CUs.  The given mask is
 * combined by bitwise AND with any device wide mask in HSA_CU_MASK before
 * being applied.
 * If num_cu_mask_count is 0 then the request is interpreted as a request to
 * enable all CUs and no cu_mask array need be given.
 *
 * @param[in] queue A pointer to HSA queue.
 *
 * @param[in] num_cu_mask_count Size of CUMask bit array passed in, in bits.
 *
 * @param[in] cu_mask Bit-vector representing the CU mask.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_CU_MASK_REDUCED The function was successfully executed
 * but the given mask attempted to enable a CU which was disabled by
 * HSA_CU_MASK.  CUs disabled by HSA_CU_MASK remain disabled.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE @p queue is NULL or invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p num_cu_mask_count is not
 * a multiple of 32 or @p num_cu_mask_count is not 0 and cu_mask is NULL.
 * Devices with work group processors must even-index contiguous pairwise
 * CU enable e.g. 0x33(b'110011) is valid while 0x5(0x101) and 0x6(b'0110)
 * are invalid.
 *
 */
hsa_status_t HSA_API hsa_amd_queue_cu_set_mask(const hsa_queue_t* queue,
                                               uint32_t num_cu_mask_count,
                                               const uint32_t* cu_mask);

/**
 * @brief Retrieve a queue's CU affinity mask.
 *
 * @details Returns the first num_cu_mask_count bits of a queue's CU mask.
 * Ensure that num_cu_mask_count is at least as large as
 * HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT to retrieve the entire mask.
 *
 * @param[in] queue A pointer to HSA queue.
 *
 * @param[in] num_cu_mask_count Size of CUMask bit array passed in, in bits.
 *
 * @param[out] cu_mask Bit-vector representing the CU mask.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE @p queue is NULL or invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p num_cu_mask_count is 0, not
 * a multiple of 32 or @p cu_mask is NULL.
 *
 */
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.
 */
typedef enum {
  /**
   * Global segment. Used to hold data that is shared by all agents.
   */
  HSA_AMD_SEGMENT_GLOBAL = 0,
  /**
   * Read-only segment. Used to hold data that remains constant during the
   * execution of a kernel.
   */
  HSA_AMD_SEGMENT_READONLY = 1,
  /**
   * Private segment. Used to hold data that is local to a single work-item.
   */
  HSA_AMD_SEGMENT_PRIVATE = 2,
  /**
   * Group segment. Used to hold data that is shared by the work-items of a
   * work-group.
   */
  HSA_AMD_SEGMENT_GROUP = 3,
} hsa_amd_segment_t;

/**
 * @brief A memory pool encapsulates physical storage on an agent
 * along with a memory access model.
 *
 * @details A memory pool encapsulates a physical partition of an agent's
 * memory system along with a memory access model.  Division of a single
 * memory system into separate pools allows querying each partition's access
 * path properties (see ::hsa_amd_agent_memory_pool_get_info). Allocations
 * from a pool are preferentially bound to that pool's physical partition.
 * Binding to the pool's preferential physical partition may not be
 * possible or persistent depending on the system's memory policy
 * and/or state which is beyond the scope of HSA APIs.
 *
 * For example, a multi-node NUMA memory system may be represented by multiple
 * pool's with each pool providing size and access path information for the
 * partition it represents.  Allocations from a pool are preferentially bound
 * to the pool's partition (which in this example is a NUMA node) while
 * following its memory access model. The actual placement may vary or migrate
 * due to the system's NUMA policy and state, which is beyond the scope of
 * HSA APIs.
 */
typedef struct hsa_amd_memory_pool_s {
  /**
   * Opaque handle.
   */
  uint64_t handle;
} hsa_amd_memory_pool_t;

typedef enum hsa_amd_memory_pool_global_flag_s {
  /**
   * The application can use allocations in the memory pool to store kernel
   * arguments, and provide the values for the kernarg segment of
   * a kernel dispatch.
   */
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_KERNARG_INIT = 1,
  /**
   * Updates to memory in this pool conform to HSA memory consistency model.
   * If this flag is set, then ::HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED
   * must not be set.
   */
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_FINE_GRAINED = 2,
  /**
   * Writes to memory in this pool can be performed by a single agent at a time.
   */
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED = 4,

  /** Updates to memory in this memory pool have extended scope, acting as
   * system-scope atomics for variables in memory regions of this type.
   * Note: On non-compliant systems, device-specific actions may be required
   * for system-scope coherence. */
  HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_EXTENDED_SCOPE_FINE_GRAINED = 8,

} hsa_amd_memory_pool_global_flag_t;

typedef enum hsa_amd_memory_pool_location_s {
    /**
     * This memory pool resides on the host (CPU)
     */
    HSA_AMD_MEMORY_POOL_LOCATION_CPU = 0,
    /**
     * This memory pool resides on a GPU
     */
    HSA_AMD_MEMORY_POOL_LOCATION_GPU = 1
} hsa_amd_memory_pool_location_t;

/**
 * @brief Memory pool features.
 */
typedef enum {
  /**
  * Segment where the memory pool resides. The type of this attribute is
  * ::hsa_amd_segment_t.
  */
  HSA_AMD_MEMORY_POOL_INFO_SEGMENT = 0,
  /**
  * Flag mask. The value of this attribute is undefined if the value of
  * ::HSA_AMD_MEMORY_POOL_INFO_SEGMENT is not ::HSA_AMD_SEGMENT_GLOBAL. The type
  * of
  * this attribute is uint32_t, a bit-field of
  * ::hsa_amd_memory_pool_global_flag_t
  * values.
  */
  HSA_AMD_MEMORY_POOL_INFO_GLOBAL_FLAGS = 1,
  /**
  * Size of this pool, in bytes. The type of this attribute is size_t.
  */
  HSA_AMD_MEMORY_POOL_INFO_SIZE = 2,
  /**
  * Indicates whether memory in this pool can be allocated using
  * ::hsa_amd_memory_pool_allocate. The type of this attribute is bool.
  *
  * The value of this flag is always false for memory pools in the group and
  * private segments.
  */
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED = 5,
  /**
   * Allocation granularity of buffers allocated by
   * ::hsa_amd_memory_pool_allocate
   * in this memory pool. The size of a buffer allocated in this pool is a
   * multiple of the value of this attribute. While this is the minimum size of
   * allocation allowed, it is recommened to use
   * HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE to obtain the recommended
   * allocation granularity size for this pool.
   * The value of this attribute is only defined if
   * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for
   * this pool. The type of this attribute is size_t.
   */
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE = 6,
  /**
   * Alignment of buffers allocated by ::hsa_amd_memory_pool_allocate in this
   * pool. The value of this attribute is only defined if
   * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool, and
   * must be a power of 2. The type of this attribute is size_t.
   */
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT = 7,
  /**
   * This memory_pool can be made directly accessible by all the agents in the
   * system (::hsa_amd_agent_memory_pool_get_info does not return
   * ::HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED for any agent). The type of this
   * attribute is bool.
   */
  HSA_AMD_MEMORY_POOL_INFO_ACCESSIBLE_BY_ALL = 15,
  /**
   * Maximum aggregate allocation size in bytes. The type of this attribute
   * is size_t.
   */
  HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE = 16,
  /**
   * Location of this memory pool. The type of this attribute
   * is hsa_amd_memory_pool_location_t.
   */
  HSA_AMD_MEMORY_POOL_INFO_LOCATION = 17,
  /**
   * Internal block size for allocations. This would also be the recommended
   * granularity size for allocations as this prevents internal fragmentation.
   * The value of this attribute is only defined if
   * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool.
   * The size of this attribute is size_t.
   */
  HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE = 18,
} hsa_amd_memory_pool_info_t;

/**
 * @brief Memory pool flag used to specify allocation directives
 *
 */
typedef enum hsa_amd_memory_pool_flag_s {
  /**
   * Allocates memory that conforms to standard HSA memory consistency model
   */
  HSA_AMD_MEMORY_POOL_STANDARD_FLAG = 0,
  /**
   * Allocates fine grain memory type where memory ordering is per point to point
   * connection. Atomic memory operations on these memory buffers are not
   * guaranteed to be visible at system scope.
   */
  HSA_AMD_MEMORY_POOL_PCIE_FLAG = (1 << 0),
  /**
   *  Allocates physically contiguous memory
   */
  HSA_AMD_MEMORY_POOL_CONTIGUOUS_FLAG = (1 << 1),
  /**
   *  Allocates executable memory
   */
  HSA_AMD_MEMORY_POOL_EXECUTABLE_FLAG = (1 << 2),
  /**
   *  Allocates uncached memory
   */
  HSA_AMD_MEMORY_POOL_UNCACHED_FLAG = (1 << 3),
} hsa_amd_memory_pool_flag_t;

/**
 * @brief Get the current value of an attribute of a memory pool.
 *
 * @param[in] memory_pool A valid memory pool.
 *
 * @param[in] attribute Attribute to query.
 *
 * @param[out] value Pointer to a application-allocated buffer where to store
 * the value of the attribute. If the buffer passed by the application is not
 * large enough to hold the value of @p attribute, the behavior is undefined.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 */
hsa_status_t HSA_API
    hsa_amd_memory_pool_get_info(hsa_amd_memory_pool_t memory_pool,
                                 hsa_amd_memory_pool_info_t attribute,
                                 void* value);

/**
 * @brief Iterate over the memory pools associated with a given agent, and
 * invoke an application-defined callback on every iteration.
 *
 * @details An agent can directly access buffers located in some memory pool, or
 * be enabled to access them by the application (see ::hsa_amd_agents_allow_access),
 * yet that memory pool may not be returned by this function for that given
 * agent.
 *
 * A memory pool of fine-grained type must be associated only with the host.
 *
 * @param[in] agent A valid agent.
 *
 * @param[in] callback Callback to be invoked on the same thread that called
 * ::hsa_amd_agent_iterate_memory_pools, serially, once per memory pool that is
 * associated with the agent.  The HSA runtime passes two arguments to the
 * callback: the memory pool, and the application data.  If @p callback
 * returns a status other than ::HSA_STATUS_SUCCESS for a particular iteration,
 * the traversal stops and ::hsa_amd_agent_iterate_memory_pools returns that status
 * value.
 *
 * @param[in] data Application data that is passed to @p callback on every
 * iteration. May be NULL.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p callback is NULL.
 */
hsa_status_t HSA_API hsa_amd_agent_iterate_memory_pools(
    hsa_agent_t agent,
    hsa_status_t (*callback)(hsa_amd_memory_pool_t memory_pool, void* data),
    void* data);

/**
 * @brief Allocate a block of memory (or buffer) in the specified pool.
 *
 * @param[in] memory_pool Memory pool where to allocate memory from. The memory
 * pool must have the ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED flag set.
 *
 * @param[in] size Allocation size, in bytes. Must not be zero. This value is
 * rounded up to the nearest multiple of
 * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE in @p memory_pool.
 *
 * @param[in] flags A bit-field that is used to specify allocation
 * directives.
 *
 * @param[out] ptr Pointer to the location where to store the base virtual
 * address of
 * the allocated block. The returned base address is aligned to the value of
 * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT in @p memory_pool. If the
 * allocation fails, the returned value is undefined.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES No memory is available.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL The memory pool is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION The host is not allowed to
 * allocate memory in @p memory_pool, or @p size is greater than
 * the value of HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE in @p memory_pool.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr is NULL, or @p size is 0,
 * or flags is not 0.
 *
 */
hsa_status_t HSA_API
    hsa_amd_memory_pool_allocate(hsa_amd_memory_pool_t memory_pool, size_t size,
                                 uint32_t flags, void** ptr);

/**
 * @brief Deallocate a block of memory previously allocated using
 * ::hsa_amd_memory_pool_allocate.
 *
 * @param[in] ptr Pointer to a memory block. If @p ptr does not match a value
 * previously returned by ::hsa_amd_memory_pool_allocate, the behavior is undefined.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 */
hsa_status_t HSA_API hsa_amd_memory_pool_free(void* ptr);

/**
 * @brief Asynchronously copy a block of memory from the location pointed to by
 * @p src on the @p src_agent to the memory block pointed to by @p dst on the @p
 * dst_agent.
 * Because the DMA engines used may not be in the same coherency domain, the caller must ensure
 * that buffers are system-level coherent. In general this requires the sending device to have
 * released the buffer to system scope prior to executing the copy API and the receiving device
 * must execute a system scope acquire fence prior to use of the destination buffer.
 *
 * @param[out] dst Buffer where the content is to be copied.
 *
 * @param[in] dst_agent Agent associated with the @p dst. The agent must be able to directly
 * access both the source and destination buffers in their current locations.
 * May be zero in which case the runtime will attempt to discover the destination agent.
 * Discovery may have variable and/or high latency.
 *
 * @param[in] src A valid pointer to the source of data to be copied. The source
 * buffer must not overlap with the destination buffer, otherwise the copy will succeed
 * but contents of @p dst is undefined.
 *
 * @param[in] src_agent Agent associated with the @p src. The agent must be able to directly
 * access both the source and destination buffers in their current locations.
 * May be zero in which case the runtime will attempt to discover the destination agent.
 * Discovery may have variable and/or high latency.
 *
 * @param[in] size Number of bytes to copy. If @p size is 0, no copy is
 * performed and the function returns success. Copying a number of bytes larger
 * than the size of the buffers pointed by @p dst or @p src results in undefined
 * behavior.
 *
 * @param[in] num_dep_signals Number of dependent signals. Can be 0.
 *
 * @param[in] dep_signals List of signals that must be waited on before the copy
 * operation starts. The copy will start after every signal has been observed with
 * the value 0. The dependent signal should not include completion signal from
 * hsa_amd_memory_async_copy operation to be issued in future as that can result
 * in a deadlock. If @p num_dep_signals is 0, this argument is ignored.
 *
 * @param[in] completion_signal Signal used to indicate completion of the copy
 * operation. When the copy operation is finished, the value of the signal is
 * decremented. The runtime indicates that an error has occurred during the copy
 * operation by setting the value of the completion signal to a negative
 * number. The signal handle must not be 0.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. The
 * application is responsible for checking for asynchronous error conditions
 * (see the description of @p completion_signal).
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT An agent is invalid or no discovered agent has access.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL @p completion_signal is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The source or destination
 * pointers are NULL, or the completion signal is 0.
 */
hsa_status_t HSA_API
    hsa_amd_memory_async_copy(void* dst, hsa_agent_t dst_agent, const void* src,
                              hsa_agent_t src_agent, size_t size,
                              uint32_t num_dep_signals,
                              const hsa_signal_t* dep_signals,
                              hsa_signal_t completion_signal);

/**
 * @brief Asynchronously copy a block of memory from the location pointed to by
 * @p src on the @p src_agent to the memory block pointed to by @p dst on the @p
 * dst_agent on engine_id.
 *
 * WARNING: Concurrent use of this call with hsa_amd_memory_async_copy can result
 * in resource conflicts as HSA runtime will auto assign engines with the latter
 * call.  Approach using both calls concurrently with caution.
 *
 * All param definitions are identical to hsa_amd_memory_async_copy with the
 * exception of engine_id and force_copy_on_sdma.
 *
 * @param[in] - engine_id Target engine defined by hsa_amd_sdma_engine_id_t.
 * Client should use hsa_amd_memory_copy_engine_status first to get the ID
 * availability.
 *
 * @param[in] - force_copy_on_sdma By default, blit kernel copies are used when
 * dst_agent == src_agent.  Setting this to true will force the copy over SDMA1.
 *
 * All return definitions are identical to hsa_amd_memory_async_copy with the
 * following ammendments:
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The source or destination
 * pointers are NULL, or the completion signal is 0 or engine_id is improperly
 * bounded.
 */
hsa_status_t HSA_API
    hsa_amd_memory_async_copy_on_engine(void* dst, hsa_agent_t dst_agent, const void* src,
                              hsa_agent_t src_agent, size_t size,
                              uint32_t num_dep_signals,
                              const hsa_signal_t* dep_signals,
                              hsa_signal_t completion_signal,
                              hsa_amd_sdma_engine_id_t engine_id,
                              bool force_copy_on_sdma);

/**
 * @brief Type of memory copy operation within a batch.
 */
typedef enum {
  HSA_AMD_MEMORY_COPY_OP_LINEAR               = 0,  /**< Linear copy (num_entries==0: single; num_entries>0: multi) */
  HSA_AMD_MEMORY_COPY_OP_LINEAR_BROADCAST     = 1,  /**< Linear broadcast: single src -> multiple dsts */
  HSA_AMD_MEMORY_COPY_OP_LINEAR_SWAP          = 2,  /**< Linear swap: exchange contents of src and dst */
  HSA_AMD_MEMORY_COPY_OP_LINEAR_INDIRECT_SRC     = 3,  /**< Source address resolved via indirection */
  HSA_AMD_MEMORY_COPY_OP_LINEAR_INDIRECT_DST     = 4,  /**< Destination address resolved via indirection */
  HSA_AMD_MEMORY_COPY_OP_LINEAR_INDIRECT_SRCDST  = 5,  /**< Both src and dst resolved via indirection */
} hsa_amd_memory_copy_op_type_t;

/**
 * @brief Wait comparison functions for copy operations.
 *
 * Maps to the SDMA WAIT_FUNCTION field. The SDMA engine polls
 * (*wait.addr & wait.mask) against wait.value using the specified
 * comparison before starting the copy.  Orthogonal to operation type:
 * any copy can optionally wait.
 */
typedef enum {
  HSA_AMD_MEMORY_COPY_WAIT_ALWAYS = 0,  /**< Always pass (no wait) */
  HSA_AMD_MEMORY_COPY_WAIT_LT     = 1,  /**< Less than */
  HSA_AMD_MEMORY_COPY_WAIT_LE     = 2,  /**< Less than or equal */
  HSA_AMD_MEMORY_COPY_WAIT_EQ     = 3,  /**< Equal */
  HSA_AMD_MEMORY_COPY_WAIT_NE     = 4,  /**< Not equal */
  HSA_AMD_MEMORY_COPY_WAIT_GE     = 5,  /**< Greater than or equal */
  HSA_AMD_MEMORY_COPY_WAIT_GT     = 6,  /**< Greater than */
} hsa_amd_memory_copy_wait_function_t;

/**
 * @brief Signal operations for copy completion notification.
 *
 * Maps to the SDMA SIGNAL_OPERATION field. After the copy completes,
 * the SDMA engine performs the specified atomic operation on signal.addr.
 * This is a raw GPU-side signal, separate from the HSA completion_signal.
 */
typedef enum {
  HSA_AMD_MEMORY_COPY_SIGNAL_NONE  = 0,   /**< No signal operation */
  HSA_AMD_MEMORY_COPY_SIGNAL_WRITE = 1,   /**< 64b write: *addr = data */
  HSA_AMD_MEMORY_COPY_SIGNAL_ADD   = 2,   /**< 64b add: *addr += data */
  HSA_AMD_MEMORY_COPY_SIGNAL_SUB   = 3,   /**< 64b sub: *addr -= data */
} hsa_amd_memory_copy_signal_op_t;

/**
 * @brief Version of the hsa_amd_memory_copy_op_t structure.
 *
 * Callers must set the @c version field to this value.  The runtime rejects
 * operations whose version it does not recognise.
 */
#define HSA_AMD_MEMORY_COPY_OP_VERSION 1

/**
 * @brief Describes a single copy operation within a batch.
 *
 * The @c version field must be set to @c HSA_AMD_MEMORY_COPY_OP_VERSION.
 *
 * Common fields (all operation types):
 *   version         -- must be HSA_AMD_MEMORY_COPY_OP_VERSION
 *   type            -- one of hsa_amd_memory_copy_op_type_t
 *   completion_signal -- per-operation completion signal
 *   traffic_class   -- QoS traffic class (0 = default/unspecified)
 *   reserved[]      -- must be zero
 *
 * Wait-before-copy (orthogonal, any operation type):
 *   wait.function   -- comparison function (hsa_amd_memory_copy_wait_function_t).
 *                      SDMA polls (*wait.addr & wait.mask) against wait.value using
 *                      this comparison before starting the copy.  ALWAYS (0) = no wait.
 *   wait.scope      -- coherency scope (hsa_fence_scope_t) for pre-copy memory reads:
 *                      wait address polling and indirect address resolution.
 *                      Must be 0 when function is ALWAYS and type is not INDIRECT_*.
 *   wait.addr       -- address to poll (NULL when function is ALWAYS)
 *   wait.value      -- reference value for the comparison
 *   wait.mask       -- AND mask applied to the polled value before comparison
 *
 * Signal-after-copy (orthogonal, any operation type):
 *   signal.operation -- signal operation (hsa_amd_memory_copy_signal_op_t).
 *                       NONE (0) = no signal.  This is a raw GPU-side atomic,
 *                       separate from the HSA completion_signal.
 *   signal.scope     -- coherency scope for the signal write (hsa_fence_scope_t)
 *   signal.addr      -- target address for the atomic (NULL when operation is NONE)
 *   signal.data      -- data value for the atomic operation
 *
 * Field usage per operation type:
 *
 * LINEAR (default, single copy when num_entries == 0):
 *   src, src_agent  -- source pointer and agent
 *   dst, dst_agent  -- destination pointer and agent
 *   size            -- copy size in bytes
 *   num_entries        -- 0
 *
 * LINEAR (multi-copy when num_entries > 0, one signal for all entries):
 *   src_list         -- caller-owned array of num_entries source pointers
 *   src_agent        -- common source agent (GPU or CPU); if CPU, all dst_agent_list entries must be GPU
 *   dst_list         -- caller-owned array of num_entries destination pointers
 *   dst_agent_list   -- caller-owned array of num_entries destination agents
 *   size_list        -- caller-owned array of num_entries copy sizes in bytes
 *   num_entries         -- number of entries (>= 1, <= 65536)
 *
 * LINEAR_BROADCAST (single source -> multiple destinations):
 *   src, src_agent    -- source pointer and agent (must be GPU)
 *   dst_list          -- caller-owned array of num_entries destination pointers
 *   dst_agent_list    -- caller-owned array of num_entries destination agents
 *   size              -- copy size in bytes (same for every destination)
 *   num_entries          -- number of entries in dst_list / dst_agent_list (>= 1, <= 65536)
 *
 * LINEAR_SWAP (exchange contents of two buffers, multi-entry when num_entries > 0):
 *   src_list         -- caller-owned array of num_entries source pointers
 *   src_agent        -- common agent for routing
 *   dst_list         -- caller-owned array of num_entries destination pointers
 *   dst_agent_list   -- caller-owned array of num_entries destination agents
 *   size_list        -- caller-owned array of num_entries swap sizes in bytes
 *   num_entries      -- number of entries (>= 1, <= 65536)
 *
 * LINEAR_SWAP (single, when num_entries == 0):
 *   src, src_agent  -- first buffer pointer and agent (modified in place)
 *   dst, dst_agent  -- second buffer pointer and agent (modified in place)
 *   src_size        -- size of the source region in bytes
 *   dst_size        -- size of the destination region in bytes
 *   num_entries     -- 0
 *
 * LINEAR_INDIRECT_SRC / _DST / _SRCDST: one or more indirect transfers whose
 * source and/or destination address is resolved at execution time by the
 * SDMA engine dereferencing a pointer-to-pointer slot.  The op.type chooses
 * which side is indirect: SRC -> src is void**; DST -> dst is void**;
 * SRCDST -> both are void**.  All entries in a single op share the same
 * indirect mode.
 *
 * LINEAR_INDIRECT_* (single, when num_entries == 0):
 *   src, src_agent  -- source pointer (void** for SRC/SRCDST) and agent
 *   dst, dst_agent  -- destination pointer (void** for DST/SRCDST) and agent
 *   size            -- copy size in bytes
 *   num_entries     -- 0
 *   wait.scope      -- hsa_fence_scope_t for indirect address reads
 *
 * LINEAR_INDIRECT_* (multi-entry, when num_entries > 0):
 *   src_list        -- array of num_entries void** (SRC/SRCDST) or void*
 *                      (DST) pointers
 *   dst_list        -- array of num_entries void** (DST/SRCDST) or void*
 *                      (SRC) pointers
 *   dst_agent_list  -- array of num_entries destination agents
 *   size_list       -- array of num_entries copy sizes in bytes
 *   src_agent       -- source agent (common to all entries)
 *   num_entries     -- >= 1 and <= 1024
 *   wait.scope      -- hsa_fence_scope_t for indirect address reads
 *
 * Future-proofing unions (reserved, must not be used):
 *   src_agent_list           -- reserved for future gather operations
 *   unused_size              -- must be 0 for non-SWAP types; for LINEAR multi, use size_list instead
 */
typedef struct hsa_amd_memory_copy_op_s {
  uint16_t version;                       /**< Struct version. Must be HSA_AMD_MEMORY_COPY_OP_VERSION. */
  uint16_t type;                          /**< Operation type (hsa_amd_memory_copy_op_type_t) */
  uint16_t num_entries;                    /**< Number of entries for multi-entry forms (LINEAR / SWAP / INDIRECT_*: 0 = scalar form; BROADCAST: always >= 1) */
  uint16_t traffic_class;                 /**< QoS traffic class. 0 = default/unspecified. */
  hsa_signal_t completion_signal;         /**< Completion signal for this operation */
  union {
    void* src;                            /**< Source pointer (or void** for INDIRECT_SRC/SRCDST) */
    void** src_list;                      /**< LINEAR multi: caller-owned array of num_entries source pointers */
  };
  union {
    hsa_agent_t src_agent;                /**< Source agent */
    hsa_agent_t* src_agent_list;          /**< Reserved for future use */
  };
  union {
    hsa_agent_t dst_agent;                /**< Destination agent (single-dst types) */
    hsa_agent_t* dst_agent_list;          /**< LINEAR multi / BROADCAST: caller-owned array of num_entries destination agents */
  };
  union {
    void* dst;                            /**< Destination pointer (or void** for INDIRECT_DST/SRCDST) */
    void** dst_list;                      /**< LINEAR multi / BROADCAST: caller-owned array of num_entries destination pointers */
  };
  union {
    struct {
      size_t size;                        /**< Copy size in bytes (LINEAR single / BROADCAST / INDIRECT) */
      size_t unused_size;                 /**< Must be 0 for non-SWAP types; unused for LINEAR multi */
    };
    struct {
      size_t src_size;                    /**< SWAP: source region size in bytes */
      size_t dst_size;                    /**< SWAP: destination region size in bytes */
    };
    struct {
      size_t* size_list;                  /**< LINEAR multi: caller-owned array of num_entries copy sizes */
      size_t reserved0;                   /**< Must be 0 for LINEAR multi */
    };
  };
  /** Wait-before-copy. Set to {0} to disable. */
  struct {
    uint16_t function;                    /**< Comparison (hsa_amd_memory_copy_wait_function_t) */
    uint16_t scope;                       /**< Scope (hsa_fence_scope_t) */
    uint32_t reserved;                    /**< Must be 0 */
    void*    addr;                        /**< Address to poll (NULL = no wait) */
    uint64_t value;                       /**< Reference value for wait comparison */
    uint64_t mask;                        /**< AND mask applied before comparison */
  } wait;                                 /**< Wait-before-copy descriptor */
  /** Signal-after-copy (raw GPU-side atomic, separate from completion_signal). Set to {0} to disable. */
  struct {
    uint16_t operation;                   /**< Signal op (hsa_amd_memory_copy_signal_op_t) */
    uint16_t scope;                       /**< Scope for signal write (hsa_fence_scope_t) */
    uint32_t reserved;                    /**< Must be 0 */
    void*    addr;                        /**< Target address for atomic (NULL = no signal) */
    uint64_t data;                        /**< Data value for the atomic operation */
  } signal;                               /**< Signal-after-copy descriptor */
  uint64_t reserved1[1];                  /**< Reserved for future use. Must be zero. */
} hsa_amd_memory_copy_op_t;

/**
 * @brief Submits a batch of asynchronous memory copy operations.
 *
 * @details Submits multiple memory copy operations as a batch. Each operation
 * carries its own completion signal in @c hsa_amd_memory_copy_op_t.completion_signal.
 * All operations within a single batch must share the same completion signal.
 * The caller must initialise the signal value to @p num_copy_ops before calling
 * this function; the runtime decrements it once per completed operation.
 *
 * Each operation is self-describing via its @c type field. A BROADCAST operation
 * is a single op that copies one source to multiple destinations via @c dst_list
 * and @c num_entries. A SWAP operation exchanges two buffers using @c src_size and
 * @c dst_size. SWAP operations require addresses to be 64-byte aligned for gfx94x/gfx95x
 * and 32-byte aligned for gfx1250.
 *
 * @param[in] copy_ops Array of copy operation descriptors.
 *
 * @param[in] num_copy_ops Number of copy operations in the array.
 *
 * @param[in] num_dep_signals Number of dependent signals.
 *
 * @param[in] dep_signals Array of dependent signals that all copy operations
 * must wait on before starting.
 *
 * @retval ::HSA_STATUS_SUCCESS The batch copy was submitted successfully.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT copy_ops is NULL, num_copy_ops
 * is 0, any src/dst pointers are NULL, or completion_signal is invalid.
 */
hsa_status_t HSA_API
    hsa_amd_memory_async_batch_copy(const hsa_amd_memory_copy_op_t* copy_ops,
                              uint32_t num_copy_ops,
                              uint32_t num_dep_signals,
                              const hsa_signal_t* dep_signals);

/**
 * @brief Reports the availability of SDMA copy engines.
 *
 * @param[in] dst_agent Destination agent of copy status direction.
 *
 * @param[in] src_agent Source agent of copy status direction.
 *
 * @param[out] engine_ids_mask returns available SDMA engine IDs that can be masked
 * with hsa_amd_sdma_engine_id_t.
 *
 * @retval ::HSA_STATUS_SUCCESS Agent has available SDMA engines.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Agent does not have available SDMA engines.
 *
 */
hsa_status_t HSA_API
hsa_amd_memory_copy_engine_status(hsa_agent_t dst_agent, hsa_agent_t src_agent,
                                      uint32_t *engine_ids_mask);
 /**
 * @brief Returns the preferred SDMA engine mask.
 *
 * @param[in] dst_agent Destination agent of copy status direction.
 *
 * @param[in] src_agent Source agent of copy status direction.
 *
 * @param[out] recommended_ids_mask returns available SDMA engine IDs for max bandwidth
 * that can be masked with hsa_amd_sdma_engine_id_t. Can be 0 if there is no preference
 *
 * @retval ::HSA_STATUS_SUCCESS For mask returned
 *
 */
hsa_status_t HSA_API
hsa_amd_memory_get_preferred_copy_engine(hsa_agent_t dst_agent, hsa_agent_t src_agent,
                                         uint32_t* recommended_ids_mask);

/*
[Provisional API]
Pitched memory descriptor.
All elements must be 4 byte aligned.  Pitch and slice are in bytes.
*/
typedef struct hsa_pitched_ptr_s {
  void* base;
  size_t pitch;
  size_t slice;
} hsa_pitched_ptr_t;

/*
[Provisional API]
Copy direction flag.
*/
typedef enum {
  hsaHostToHost = 0,
  hsaHostToDevice = 1,
  hsaDeviceToHost = 2,
  hsaDeviceToDevice = 3
} hsa_amd_copy_direction_t;

/*
[Provisional API]
SDMA 3D memory copy API.  The same requirements must be met by src and dst as in
hsa_amd_memory_async_copy.
Both src and dst must be directly accessible to the copy_agent during the copy, src and dst rects
must not overlap.
CPU agents are not supported.  API requires SDMA and will return an error if SDMA is not available.
Offsets and range carry x in bytes, y and z in rows and layers.
*/
hsa_status_t HSA_API hsa_amd_memory_async_copy_rect(
    const hsa_pitched_ptr_t* dst, const hsa_dim3_t* dst_offset, const hsa_pitched_ptr_t* src,
    const hsa_dim3_t* src_offset, const hsa_dim3_t* range, hsa_agent_t copy_agent,
    hsa_amd_copy_direction_t dir, uint32_t num_dep_signals, const hsa_signal_t* dep_signals,
    hsa_signal_t completion_signal);

/**
 * @brief Type of accesses to a memory pool from a given agent.
 */
typedef enum {
  /**
  * The agent cannot directly access any buffer in the memory pool.
  */
  HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED = 0,
  /**
  * The agent can directly access a buffer located in the pool; the application
  * does not need to invoke ::hsa_amd_agents_allow_access.
  */
  HSA_AMD_MEMORY_POOL_ACCESS_ALLOWED_BY_DEFAULT = 1,
  /**
  * The agent can directly access a buffer located in the pool, but only if the
  * application has previously requested access to that buffer using
  * ::hsa_amd_agents_allow_access.
  */
  HSA_AMD_MEMORY_POOL_ACCESS_DISALLOWED_BY_DEFAULT = 2
} hsa_amd_memory_pool_access_t;

/**
 * @brief Properties of the relationship between an agent a memory pool.
 */
typedef enum {
  /**
  * Hyper-transport bus type.
  */
  HSA_AMD_LINK_INFO_TYPE_HYPERTRANSPORT = 0,

  /**
  * QPI bus type.
  */
  HSA_AMD_LINK_INFO_TYPE_QPI = 1,

  /**
  * PCIe bus type.
  */
  HSA_AMD_LINK_INFO_TYPE_PCIE = 2,

  /**
  * Infiniband bus type.
  */
  HSA_AMD_LINK_INFO_TYPE_INFINBAND = 3,

  /**
  * xGMI link type.
  */
  HSA_AMD_LINK_INFO_TYPE_XGMI = 4

} hsa_amd_link_info_type_t;

/**
 * @brief Link properties when accessing the memory pool from the specified
 * agent.
 */
typedef struct hsa_amd_memory_pool_link_info_s {
  /**
  * Minimum transfer latency (rounded to ns).
  */
  uint32_t min_latency;

  /**
  * Maximum transfer latency (rounded to ns).
  */
  uint32_t max_latency;

  /**
  * Minimum link interface bandwidth in MB/s.
  */
  uint32_t min_bandwidth;

  /**
  * Maximum link interface bandwidth in MB/s.
  */
  uint32_t max_bandwidth;

  /**
  * Support for 32-bit atomic transactions.
  */
  bool atomic_support_32bit;

  /**
  * Support for 64-bit atomic transactions.
  */
  bool atomic_support_64bit;

  /**
  * Support for cache coherent transactions.
  */
  bool coherent_support;

  /**
  * The type of bus/link.
  */
  hsa_amd_link_info_type_t link_type;

  /**
   * NUMA distance of memory pool relative to querying agent
   */
  uint32_t numa_distance;
} hsa_amd_memory_pool_link_info_t;

/**
 * @brief Properties of the relationship between an agent a memory pool.
 */
typedef enum {
  /**
  * Access to buffers located in the memory pool. The type of this attribute
  * is ::hsa_amd_memory_pool_access_t.
  *
  * An agent can always directly access buffers currently located in a memory
  * pool that is associated (the memory_pool is one of the values returned by
  * ::hsa_amd_agent_iterate_memory_pools on the agent) with that agent. If the
  * buffer is currently located in a memory pool that is not associated with
  * the agent, and the value returned by this function for the given
  * combination of agent and memory pool is not
  * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED, the application still needs to invoke
  * ::hsa_amd_agents_allow_access in order to gain direct access to the buffer.
  *
  * If the given agent can directly access buffers the pool, the result is not
  * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is associated with
  * the agent, or it is of fined-grained type, the result must not be
  * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is not associated
  * with the agent, and does not reside in the global segment, the result must
  * be HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED.
  */
  HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS = 0,

  /**
  * Number of links to hop when accessing the memory pool from the specified
  * agent. The value of this attribute is zero if the memory pool is associated
  * with the agent, or if the access type is
  * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. The type of this attribute is
  * uint32_t.
  */
  HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS = 1,

  /**
  * Details of each link hop when accessing the memory pool starting from the
  * specified agent. The type of this attribute is an array size of
  * HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS with each element containing
  * ::hsa_amd_memory_pool_link_info_t.
  */
  HSA_AMD_AGENT_MEMORY_POOL_INFO_LINK_INFO = 2

} hsa_amd_agent_memory_pool_info_t;

/**
 * @brief Get the current value of an attribute of the relationship between an
 * agent and a memory pool.
 *
 * @param[in] agent Agent.
 *
 * @param[in] memory_pool Memory pool.
 *
 * @param[in] attribute Attribute to query.
 *
 * @param[out] value Pointer to a application-allocated buffer where to store
 * the value of the attribute. If the buffer passed by the application is not
 * large enough to hold the value of @p attribute, the behavior is undefined.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 */
hsa_status_t HSA_API hsa_amd_agent_memory_pool_get_info(
    hsa_agent_t agent, hsa_amd_memory_pool_t memory_pool,
    hsa_amd_agent_memory_pool_info_t attribute, void* value);

/**
 * @brief Enable direct access to a buffer from a given set of agents.
 *
 * @details
 *
 * Upon return, only the listed agents and the agent associated with the
 * buffer's memory pool have direct access to the @p ptr.
 *
 * Any agent that has access to the buffer before and after the call to
 * ::hsa_amd_agents_allow_access will also have access while
 * ::hsa_amd_agents_allow_access is in progress.
 *
 * The caller is responsible for ensuring that each agent in the list
 * must be able to access the memory pool containing @p ptr
 * (using ::hsa_amd_agent_memory_pool_get_info with ::HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS attribute),
 * otherwise error code is returned.
 *
 * @param[in] num_agents Size of @p agents.
 *
 * @param[in] agents List of agents. If @p num_agents is 0, this argument is
 * ignored.
 *
 * @param[in] flags A list of bit-field that is used to specify access
 * information in a per-agent basis. This is currently reserved and must be NULL.
 *
 * @param[in] ptr A buffer previously allocated using ::hsa_amd_memory_pool_allocate.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p num_agents is 0, or @p agents
 * is NULL, @p flags is not NULL, or attempting to enable access to agent(s)
 * because @p ptr is allocated from an inaccessible pool.
 *
 */
hsa_status_t HSA_API
    hsa_amd_agents_allow_access(uint32_t num_agents, const hsa_agent_t* agents,
                                const uint32_t* flags, const void* ptr);

/**
 * @brief Query if buffers currently located in some memory pool can be
 * relocated to a destination memory pool.
 *
 * @details If the returned value is non-zero, a migration of a buffer to @p
 * dst_memory_pool using ::hsa_amd_memory_migrate may nevertheless fail due to
 * resource limitations.
 *
 * @param[in] src_memory_pool Source memory pool.
 *
 * @param[in] dst_memory_pool Destination memory pool.
 *
 * @param[out] result Pointer to a memory location where the result of the query
 * is stored. Must not be NULL. If buffers currently located in @p
 * src_memory_pool can be relocated to @p dst_memory_pool, the result is
 * true.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL One of the memory pools is
 * invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p result is NULL.
 */
hsa_status_t HSA_API
    hsa_amd_memory_pool_can_migrate(hsa_amd_memory_pool_t src_memory_pool,
                                    hsa_amd_memory_pool_t dst_memory_pool,
                                    bool* result);

/**
 * @brief Relocate a buffer to a new memory pool.
 *
 * @details When a buffer is migrated, its virtual address remains the same but
 * its physical contents are moved to the indicated memory pool.
 *
 * After migration, only the agent associated with the destination pool will have access.
 *
 * The caller is also responsible for ensuring that the allocation in the
 * source memory pool where the buffer is currently located can be migrated to the
 * specified destination memory pool (using ::hsa_amd_memory_pool_can_migrate returns a value of true
 * for the source and destination memory pools), otherwise behavior is undefined.
 *
 * The caller must ensure that the buffer is not accessed while it is migrated.
 *
 * @param[in] ptr Buffer to be relocated. The buffer must have been released to system
 * prior to call this API.  The buffer will be released to system upon completion.
 *
 * @param[in] memory_pool Memory pool where to place the buffer.
 *
 * @param[in] flags A bit-field that is used to specify migration
 * information. Must be zero.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL The destination memory pool is
 * invalid.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
 * allocating the necessary resources.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p flags is not 0.
 */
hsa_status_t HSA_API hsa_amd_memory_migrate(const void* ptr,
                                            hsa_amd_memory_pool_t memory_pool,
                                            uint32_t flags);

/**
 *
 * @brief Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and
 * return a new pointer accessible by the @p agents. If the @p host_ptr overlaps with previously
 * locked memory, then the overlap area is kept locked (i.e multiple mappings are permitted). In
 * this case, the same input @p host_ptr may give different locked @p agent_ptr and when it does,
 * they are not necessarily coherent (i.e. accessing either @p agent_ptr is not equivalent).
 * Accesses to @p agent_ptr are coarse grained.
 *
 * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator.
 *
 * @param[in] size The size to be locked.
 *
 * @param[in] agents Array of agent handle to gain access to the @p host_ptr.
 * If this parameter is NULL and the @p num_agent is 0, all agents
 * in the platform will gain access to the @p host_ptr.
 *
 * @param[out] agent_ptr Pointer to the location where to store the new address.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
 * allocating the necessary resources.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT One or more agent in @p agents is
 * invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p size is 0 or @p host_ptr or
 * @p agent_ptr is NULL or @p agents not NULL but @p num_agent is 0 or @p agents
 * is NULL but @p num_agent is not 0.
 */
hsa_status_t HSA_API hsa_amd_memory_lock(void* host_ptr, size_t size,
                                         hsa_agent_t* agents, int num_agent,
                                         void** agent_ptr);

/**
 *
 * @brief Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and
 * return a new pointer accessible by the @p agents. If the @p host_ptr overlaps with previously
 * locked memory, then the overlap area is kept locked (i.e. multiple mappings are permitted).
 * In this case, the same input @p host_ptr may give different locked @p agent_ptr and when it
 * does, they are not necessarily coherent (i.e. accessing either @p agent_ptr is not equivalent).
 * Acesses to the memory via @p agent_ptr have the same access properties as memory allocated from
 * @p pool as determined by ::hsa_amd_memory_pool_get_info and ::hsa_amd_agent_memory_pool_get_info
 * (ex. coarse/fine grain, platform atomic support, link info).  Physical composition and placement
 * of the memory (ex. page size, NUMA binding) is not changed.
 *
 * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator.
 *
 * @param[in] size The size to be locked.
 *
 * @param[in] agents Array of agent handle to gain access to the @p host_ptr.
 * If this parameter is NULL and the @p num_agent is 0, all agents
 * in the platform will gain access to the @p host_ptr.
 *
 * @param[in] pool Global memory pool owned by a CPU agent.
 *
 * @param[in] flags A bit-field that is used to specify allocation
 * directives. Reserved parameter, must be 0.
 *
 * @param[out] agent_ptr Pointer to the location where to store the new address.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
 * allocating the necessary resources.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT One or more agent in @p agents is
 * invalid or can not access @p pool.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL @p pool is invalid or not owned
 * by a CPU agent.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p size is 0 or @p host_ptr or
 * @p agent_ptr is NULL or @p agents not NULL but @p num_agent is 0 or @p agents
 * is NULL but @p num_agent is not 0 or flags is not 0.
 */
hsa_status_t HSA_API hsa_amd_memory_lock_to_pool(void* host_ptr, size_t size, hsa_agent_t* agents,
                                                 int num_agent, hsa_amd_memory_pool_t pool,
                                                 uint32_t flags, void** agent_ptr);

/**
 *
 * @brief Unpin the host pointer previously pinned via ::hsa_amd_memory_lock or
 * ::hsa_amd_memory_lock_to_pool.
 *
 * @details The behavior is undefined if the host pointer being unpinned does not
 * match previous pinned address or if the host pointer was already deallocated.
 *
 * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator that was
 * pinned previously via ::hsa_amd_memory_lock or ::hsa_amd_memory_lock_to_pool.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 */
hsa_status_t HSA_API hsa_amd_memory_unlock(void* host_ptr);

/**
 * @brief Sets the first @p count of uint32_t of the block of memory pointed by
 * @p ptr to the specified @p value.
 *
 * @param[in] ptr Pointer to the block of memory to fill.
 *
 * @param[in] value Value to be set.
 *
 * @param[in] count Number of uint32_t element to be set to the value.
 *
 * @retval HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr is NULL or
 * not 4 bytes aligned
 *
 * @retval HSA_STATUS_ERROR_INVALID_ALLOCATION if the given memory
 * region was not allocated with HSA runtime APIs.
 *
 */
hsa_status_t HSA_API
    hsa_amd_memory_fill(void* ptr, uint32_t value, size_t count);

/**
 * @brief Maps an interop object into the HSA flat address space and establishes
 * memory residency.  The metadata pointer is valid during the lifetime of the
 * map (until hsa_amd_interop_unmap_buffer is called).
 * Multiple calls to hsa_amd_interop_map_buffer with the same interop_handle
 * result in multiple mappings with potentially different addresses and
 * different metadata pointers.  Concurrent operations on these addresses are
 * not coherent.  Memory must be fenced to system scope to ensure consistency,
 * between mappings and with any views of this buffer in the originating
 * software stack.
 *
 * @param[in] num_agents Number of agents which require access to the memory
 *
 * @param[in] agents List of accessing agents.
 *
 * @param[in] interop_handle interop buffer handle (FD on Linux and HANDLE on
 * Windows)
 *
 * @param [in] flags Reserved, must be 0
 *
 * @param[out] size Size in bytes of the mapped object
 *
 * @param[out] ptr Base address of the mapped object
 *
 * @param[out] metadata_size Size of metadata in bytes, may be NULL
 *
 * @param[out] metadata Pointer to metadata, may be NULL
 *
 * @retval HSA_STATUS_SUCCESS if successfully mapped
 *
 * @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 all other errors
 */
hsa_status_t HSA_API hsa_amd_interop_map_buffer(uint32_t num_agents, hsa_agent_t* agents,
                                                hsa_handle_t interop_handle, uint32_t flags,
                                                size_t* size, void** ptr, size_t* metadata_size,
                                                const void** metadata);

/**
 * @brief Maps an interop object into the HSA flat address space with a
 * caller-supplied size hint and establishes memory residency.
 * The metadata pointer is valid during the lifetime of the
 * map (until hsa_amd_interop_unmap_buffer is called).
 * Multiple calls to hsa_amd_interop_map_buffer with the same interop_handle
 * result in multiple mappings with potentially different addresses and
 * different metadata pointers.  Concurrent operations on these addresses are
 * not coherent.  Memory must be fenced to system scope to ensure consistency,
 * between mappings and with any views of this buffer in the originating
 * software stack.
 * It is identical to hsa_amd_interop_map_buffer except that @p size_hint provides
 * the known byte size of the resource to the runtime.  Use this variant when
 * the resource was created by a foreign API (e.g. D3D11 USAGE_DYNAMIC constant
 * buffer) whose KMD private data does not encode the allocation size in a
 * format the runtime can parse.  Pass 0 when the size is unknown and will be deduced.
 *
 * @param[in] num_agents Number of agents which require access to the memory
 *
 * @param[in] agents List of accessing agents.
 *
 * @param[in] interop_handle interop buffer handle (FD on Linux and HANDLE on
 * Windows)
 *
 * @param [in] flags Reserved, must be 0
 *
 * @param [in] size_hint the hinted size of the buffer.
 *
 * @param[out] size Size in bytes of the mapped object
 *
 * @param[out] ptr Base address of the mapped object
 *
 * @param[out] metadata_size Size of metadata in bytes, may be NULL
 *
 * @param[out] metadata Pointer to metadata, may be NULL
 *
 * @retval HSA_STATUS_SUCCESS if successfully mapped
 *
 * @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 all other errors
 */
hsa_status_t HSA_API hsa_amd_interop_map_buffer_with_size(
    uint32_t num_agents, hsa_agent_t* agents, hsa_handle_t interop_handle, uint32_t flags,
    size_t size_hint, size_t* size, void** ptr, size_t* metadata_size, const void** metadata);

/**
 * @brief Removes a previously mapped interop object from HSA's flat address space.
 * Ends lifetime for the mapping's associated metadata pointer.
 */
hsa_status_t HSA_API hsa_amd_interop_unmap_buffer(void* ptr);

/**
 * @brief Denotes the type of memory in a pointer info query.
 */
typedef enum {
  /*
  Memory is not known to the HSA driver.  Unallocated or unlocked system memory.
  */
  HSA_EXT_POINTER_TYPE_UNKNOWN = 0,
  /*
  Memory was allocated with an HSA memory allocator.
  */
  HSA_EXT_POINTER_TYPE_HSA = 1,
  /*
  System memory which has been locked for use with an HSA agent.

  Memory of this type is normal malloc'd memory and is always accessible to
  the CPU.  Pointer info queries may not include CPU agents in the accessible
  agents list as the CPU has implicit access.
  */
  HSA_EXT_POINTER_TYPE_LOCKED = 2,
  /*
  Memory originated in a graphics component and is shared with ROCr.
  */
  HSA_EXT_POINTER_TYPE_GRAPHICS = 3,
  /*
  Memory has been shared with the local process via ROCr IPC APIs.
  */
  HSA_EXT_POINTER_TYPE_IPC = 4,
  /*
  No backend memory but virtual address
  */
  HSA_EXT_POINTER_TYPE_RESERVED_ADDR = 5,
  /*
  Memory was allocated with an HSA virtual memory allocator
  */
  HSA_EXT_POINTER_TYPE_HSA_VMEM = 6
} hsa_amd_pointer_type_t;

/**
 * @brief Allocation flags reported by hsa_amd_pointer_info.
 *
 * These flags describe properties of the memory allocation as reported by
 * the kernel driver.  The value of this attribute is a bitmask.
 */
typedef enum hsa_amd_pointer_info_alloc_flag_s {
  /**
   * Memory was allocated with executable permission.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_EXECUTABLE = (1 << 0),
  /**
   * Memory was allocated as physically contiguous.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_CONTIGUOUS = (1 << 1),
  /**
   * Memory is non-paged (pinned/page-locked).
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_NONPAGED = (1 << 2),
  /**
   * Memory has read-only access.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_READONLY = (1 << 3),
  /**
   * Memory is accessible by the host CPU.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_HOST_ACCESS = (1 << 4),
  /**
   * Memory supports full system-scope atomic operations.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_ATOMIC_FULL = (1 << 5),
  /**
   * Memory supports partial (PCIe) atomic operations.
   */
  HSA_AMD_POINTER_INFO_ALLOC_FLAG_ATOMIC_PARTIAL = (1 << 6),
} hsa_amd_pointer_info_alloc_flag_t;

/**
 * @brief Describes a memory allocation known to ROCr.
 * Within a ROCr major version this structure can only grow.
 */
typedef struct hsa_amd_pointer_info_s {
  /*
  Size in bytes of this structure.  Used for version control within a major ROCr
  revision.  Set to sizeof(hsa_amd_pointer_info_t) prior to calling
  hsa_amd_pointer_info.  If the runtime supports an older version of pointer
  info then size will be smaller on return.  Members starting after the return
  value of size will not be updated by hsa_amd_pointer_info.
  */
  uint32_t size;
  /*
  The type of allocation referenced.
  */
  hsa_amd_pointer_type_t type;
  /*
  Base address at which non-host agents may access the allocation. This field is
  not meaningful if the type of the allocation is HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  void* agentBaseAddress;
  /*
  Base address at which the host agent may access the allocation. This field is
  not meaningful if the type of the allocation is HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  void* hostBaseAddress;
  /*
  Size of the allocation. This field is not meaningful if the type of the allocation
  is HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  size_t sizeInBytes;
  /*
  Application provided value. This field is not meaningful if the type of the
  allocation is HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  void* userData;
  /*
  Reports an agent which "owns" (ie has preferred access to) the pool in which the
  allocation was
  made.  When multiple agents share equal access to a pool (ex: multiple CPU agents, or multi-die
  GPU boards) any such agent may be returned. This field is not meaningful if
  the type of the allocation is HSA_EXT_POINTER_TYPE_UNKNOWN or if this agent is not available in
  this process, for e.g if this agent is masked using ROCR_VISIBLE_DEVICES.
  */
  hsa_agent_t agentOwner;
  /*
  Contains a bitfield of hsa_amd_memory_pool_global_flag_t values.
  Reports the effective global flags bitmask for the allocation.  This field is not
  meaningful if the type of the allocation is HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  uint32_t global_flags;

  /*
  Set to true if this allocation was registered with the underlying driver
  This field is not meaningful if the type of the allocation is
  HSA_EXT_POINTER_TYPE_UNKNOWN.
  */
  bool registered;

  /*
  Contains a bitmask of hsa_amd_pointer_info_alloc_flag_t values.
  Reports the allocation property flags for the memory as reported by the
  kernel driver.  This field is not meaningful if the type of the allocation
  is HSA_EXT_POINTER_TYPE_UNKNOWN.
  Added in version 1.18.
  */
  uint32_t alloc_flags;
} hsa_amd_pointer_info_t;

/**
 * @brief Retrieves information about the allocation referenced by the given
 * pointer.  Optionally returns the number and list of agents which can
 * directly access the allocation. In case this virtual address is unknown, the
 * pointer type returned will be HSA_EXT_POINTER_TYPE_UNKNOWN and the only fields
 * that are valid after hsa_amd_pointer_info returns are size and type.
 *
 * @param[in] ptr Pointer which references the allocation to retrieve info for.
 *
 * @param[in, out] info Pointer to structure to be filled with allocation info.
 * Data member size must be set to the size of the structure prior to calling
 * hsa_amd_pointer_info.  On return size will be set to the size of the
 * pointer info structure supported by the runtime, if smaller.  Members
 * beyond the returned value of size will not be updated by the API.
 * Must not be NULL.
 *
 * @param[in] alloc Function pointer to an allocator used to allocate the
 * @p accessible array.  If NULL @p accessible will not be returned.
 *
 * @param[out] num_agents_accessible Recieves the count of agents in
 * @p accessible.  If NULL @p accessible will not be returned.
 *
 * @param[out] accessible Recieves a pointer to the array, allocated by @p alloc,
 * holding the list of agents which may directly access the allocation.
 * May be NULL.
 *
 * @retval HSA_STATUS_SUCCESS Info retrieved 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 NULL in @p ptr or @p info.
 */
hsa_status_t HSA_API hsa_amd_pointer_info(const void* ptr,
                                          hsa_amd_pointer_info_t* info,
                                          void* (*alloc)(size_t),
                                          uint32_t* num_agents_accessible,
                                          hsa_agent_t** accessible);

/**
 * @brief Associates an arbitrary pointer with an allocation known to ROCr.
 * The pointer can be fetched by hsa_amd_pointer_info in the userData field.
 *
 * @param[in] ptr Pointer to the first byte of an allocation known to ROCr
 * with which to associate @p userdata.
 *
 * @param[in] userdata Abitrary pointer to associate with the allocation.
 *
 * @retval HSA_STATUS_SUCCESS @p userdata successfully stored.
 *
 * @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 @p ptr is not known to ROCr.
 */
hsa_status_t HSA_API hsa_amd_pointer_info_set_userdata(const void* ptr,
                                                       void* userdata);

/**
 * @brief 256-bit process independent identifier for a ROCr shared memory
 * allocation.
 */
typedef struct hsa_amd_ipc_memory_s {
  uint32_t handle[8];
} hsa_amd_ipc_memory_t;

/**
 * @brief Prepares an allocation for interprocess sharing and creates a
 * handle of type hsa_amd_ipc_memory_t uniquely identifying the allocation.  A
 * handle is valid while the allocation it references remains accessible in
 * any process.  In general applications should confirm that a shared memory
 * region has been attached (via hsa_amd_ipc_memory_attach) in the remote
 * process prior to releasing that memory in the local process.
 * Repeated calls for the same allocation may, but are not required to, return
 * unique handles. The allocation needs to be on memory on an agent of type
 * HSA_DEVICE_TYPE_GPU.
 *
 * @warning The exporter process MUST keep the allocation alive until all
 * importers have successfully called ::hsa_amd_ipc_memory_attach. If the
 * exporter frees the memory (via ::hsa_amd_memory_free or ::hsa_memory_free)
 * before importers attach, subsequent attach calls will fail with
 * HSA_STATUS_ERROR_INVALID_ARGUMENT. This follows standard IPC semantics
 * where the exporter owns memory lifetime. A debug warning is emitted if
 * exported memory is freed while the IPC handle is still active.
 *
 * @param[in] ptr Pointer to device memory allocated via ROCr APIs to prepare for
 * sharing.
 *
 * @param[in] len Length in bytes of the allocation to share.
 *
 * @param[out] handle Process independent identifier referencing the shared
 * allocation.
 *
 * @retval HSA_STATUS_SUCCESS allocation is prepared for interprocess sharing.
 *
 * @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 @p ptr does not point to the
 * first byte of an allocation made through ROCr, or len is not the full length
 * of the allocation or handle is NULL.
 */
hsa_status_t HSA_API hsa_amd_ipc_memory_create(void* ptr, size_t len,
                                               hsa_amd_ipc_memory_t* handle);

/**
 * @brief Imports shared memory into the local process and makes it accessible
 * by the given agents.  If a shared memory handle is attached multiple times
 * in a process each attach may return a different address.  Each returned
 * address is refcounted and requires a matching number of calls to
 * hsa_amd_ipc_memory_detach to release the shared memory mapping.
 *
 * @param[in] handle Pointer to the identifier for the shared memory.
 *
 * @param[in] len Length of the shared memory to import.
 * Reserved.  Must be the full length of the shared allocation in this version.
 *
 * @param[in] num_agents Count of agents in @p mapping_agents.
 * May be zero if all agents are to be allowed access.
 *
 * @param[in] mapping_agents List of agents to access the shared memory.
 * Ignored if @p num_agents is zero.
 *
 * @param[out] mapped_ptr Recieves a process local pointer to the shared memory.
 *
 * @retval HSA_STATUS_SUCCESS if memory is successfully imported.
 *
 * @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 @p handle is not valid, @p len is
 * incorrect, @p mapped_ptr is NULL, or some agent for which access was
 * requested can not access the shared memory.
 */
hsa_status_t HSA_API hsa_amd_ipc_memory_attach(
    const hsa_amd_ipc_memory_t* handle, size_t len,
    uint32_t num_agents,
    const hsa_agent_t* mapping_agents,
    void** mapped_ptr);

/**
 * @brief Decrements the reference count for the shared memory mapping and
 * releases access to shared memory imported with hsa_amd_ipc_memory_attach.
 *
 * @param[in] mapped_ptr Pointer to the first byte of a shared allocation
 * imported with hsa_amd_ipc_memory_attach.
 *
 * @retval HSA_STATUS_SUCCESS if @p mapped_ptr was imported with
 * hsa_amd_ipc_memory_attach.
 *
 * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
 *
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p mapped_ptr was not imported
 * with hsa_amd_ipc_memory_attach.
 */
hsa_status_t HSA_API hsa_amd_ipc_memory_detach(void* mapped_ptr);

/**
 * @brief External semaphore handle types (subset of Vulkan
 * VkExternalSemaphoreHandleTypeFlagBits, mapped 1:1 to
 * HSA_EXTERNAL_SEMAPHORE_HANDLE_TYPE in libhsakmt).
 */
typedef enum {
  HSA_AMD_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32     = 0,
  HSA_AMD_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_WIN32_KMT = 1,
  HSA_AMD_EXTERNAL_SEMAPHORE_HANDLE_TYPE_OPAQUE_FD        = 2,
} hsa_amd_external_semaphore_handle_type_t;

/**
 * @brief Imported external semaphore. Opaque; created by
 * hsa_amd_external_semaphore_handle_open and released by
 * hsa_amd_external_semaphore_handle_close. Internally encodes the
 * libhsakmt HSA_EXTERNAL_SEMAPHORE_HANDLE. Consumed by
 * hsa_amd_queue_signal_external_semaphore / _wait_external_semaphore.
 */
typedef struct hsa_amd_external_semaphore_s {
  uint64_t handle;
} hsa_amd_external_semaphore_t;

/**
 * @brief Descriptor passed to hsa_amd_external_semaphore_handle_open.
 */
typedef struct {
  hsa_amd_external_semaphore_handle_type_t type;
  union {
    void *win32_handle;   // valid when type == OPAQUE_WIN32 / KMT
    int   fd;             // valid when type == OPAQUE_FD
  } handle;
} hsa_amd_external_semaphore_handle_descriptor_t;

/**
 * @brief Imports a Vulkan-exported external semaphore on the given
 * agent's KMD node. The returned semaphore must be released with
 * hsa_amd_external_semaphore_handle_close.
 *
 * @param[in] agent A GPU agent whose node owns the imported syncobj.
 * @param[in] desc Descriptor naming the OS handle and its type.
 * @param[out] out_sem On success, the imported semaphore.
 *
 * @retval HSA_STATUS_SUCCESS Imported.
 * @retval HSA_STATUS_ERROR_INVALID_AGENT Agent is not a GPU, or its
 *   KMD node has no associated WDDM device.
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT desc/out_sem null, or the
 *   OS handle is null.
 * @retval HSA_STATUS_ERROR_NOT_SUPPORTED The handle type is unsupported,
 *   or libhsakmt lacks the import/destroy thunks (incl. Linux/KFD stub).
 * @retval HSA_STATUS_ERROR Underlying KMD import failed.
 */
hsa_status_t HSA_API hsa_amd_external_semaphore_handle_open(
    hsa_agent_t agent,
    const hsa_amd_external_semaphore_handle_descriptor_t *desc,
    hsa_amd_external_semaphore_t *out_sem);

/**
 * @brief Releases an imported external semaphore. Keep the handle alive
 * as long as any queued signal/wait that references it may still be
 * in flight, and as long as the higher-level (HIP / rocclr) wrapper that
 * owns the same syncobj.
 */
hsa_status_t HSA_API hsa_amd_external_semaphore_handle_close(
    hsa_amd_external_semaphore_t sem);

/**
 * @brief Submits a GPU-side signal of an imported external semaphore
 * onto @p queue, queued behind prior packets on the AQL ring. Windows
 * routes to D3DKMTSignalSynchronizationObjectFromGpu via libhsakmt;
 * Linux / KFD is currently a stub (HSA_STATUS_ERROR_NOT_SUPPORTED).
 *
 * @param queue Must be an AMD GPU AQL queue. A null, non-GPU, or
 *   non-AQL queue returns HSA_STATUS_ERROR_INVALID_QUEUE; a valid AQL
 *   queue whose node differs from the one that imported @p sem returns
 *   HSA_STATUS_ERROR_INVALID_AGENT.
 * @param sem   Handle from hsa_amd_external_semaphore_handle_open.
 * @param value Fence value written to the syncobj (passed verbatim).
 *
 * @retval HSA_STATUS_SUCCESS                Signal queued.
 * @retval HSA_STATUS_ERROR_INVALID_QUEUE    Null/invalid/non-GPU queue.
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT sem.handle is malformed.
 * @retval HSA_STATUS_ERROR_INVALID_AGENT    Queue's node has no WDDM
 *   device, or its node differs from the one that imported @p sem.
 * @retval HSA_STATUS_ERROR_NOT_SUPPORTED    libhsakmt lacks the thunk
 *   (incl. Linux/KFD stub).
 * @retval HSA_STATUS_ERROR                  KMD signal ioctl failed.
 */
hsa_status_t HSA_API hsa_amd_queue_signal_external_semaphore(
    hsa_queue_t                  *queue,
    hsa_amd_external_semaphore_t  sem,
    uint64_t                      value);

/**
 * @brief Submits a GPU-side wait on an imported external semaphore
 * onto @p queue. The wait blocks any subsequent packets on the AQL
 * ring until the imported syncobj reaches @p value. Ordering against
 * prior submissions is the caller's responsibility (rocclr's
 * host-queue worker submits commands sequentially, so the wait is
 * appended in program order ahead of subsequent submitKernel /
 * submitCopyMemory calls).
 *
 * Wired to KMD via libhsakmt's hsaKmtQueueWaitExternalSemaphore,
 * which on Windows resolves to D3DKMTWaitForSynchronizationObjectFromGpu
 * against the queue's WDDM context. Linux / KFD route is currently a
 * stub returning HSA_STATUS_ERROR_NOT_SUPPORTED.
 *
 * @param queue Must be an AMD GPU AQL queue. Null, HostQueue, and AIE
 *   queues return HSA_STATUS_ERROR_INVALID_QUEUE; a valid AQL queue
 *   whose node differs from the one that imported @p sem returns
 *   HSA_STATUS_ERROR_INVALID_AGENT.
 * @param sem   Handle returned by hsa_amd_external_semaphore_handle_open.
 * @param value Fence value to wait for. Vulkan binary semaphores
 *   conventionally use 0 / 1 but the value is passed through verbatim
 *   so timeline-style callers can pick their own.
 *
 * @retval HSA_STATUS_SUCCESS                Wait queued successfully.
 * @retval HSA_STATUS_ERROR_INVALID_QUEUE    queue is null, invalid, or
 *   not an AMD GPU AQL queue.
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT sem.handle is malformed.
 * @retval HSA_STATUS_ERROR_INVALID_AGENT    The queue's KMD node has
 *   no associated WDDM device, or it differs from the one that
 *   imported @p sem.
 * @retval HSA_STATUS_ERROR_NOT_SUPPORTED    libhsakmt lacks the thunk
 *   (incl. Linux/KFD stub).
 * @retval HSA_STATUS_ERROR                  Underlying KMD wait
 *   ioctl failed.
 */
hsa_status_t HSA_API hsa_amd_queue_wait_external_semaphore(
    hsa_queue_t                  *queue,
    hsa_amd_external_semaphore_t  sem,
    uint64_t                      value);

/** @} */

/** \addtogroup status Runtime notifications
 *  @{
 */

/**
 * @brief 256-bit process independent identifier for a ROCr IPC signal.
 */
typedef hsa_amd_ipc_memory_t hsa_amd_ipc_signal_t;

/**
 * @brief Obtains an interprocess sharing handle for a signal.  The handle is
 * valid while the signal it references remains valid in any process.  In
 * general applications should confirm that the signal has been attached (via
 * hsa_amd_ipc_signal_attach) in the remote process prior to destroying that
 * signal in the local process.
 * Repeated calls for the same signal may, but are not required to, return
 * unique handles.
 *
 * @param[in] signal Signal created with attribute HSA_AMD_SIGNAL_IPC.
 *
 * @param[out] handle Process independent identifier referencing the shared
 * signal.
 *
 * @retval HSA_STATUS_SUCCESS @p handle is ready to use for interprocess sharing.
 *
 * @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 @p signal is not a valid signal
 * created with attribute HSA_AMD_SIGNAL_IPC or handle is NULL.
 */
hsa_status_t HSA_API hsa_amd_ipc_signal_create(hsa_signal_t signal, hsa_amd_ipc_signal_t* handle);

/**
 * @brief Imports an IPC capable signal into the local process.  If an IPC
 * signal handle is attached multiple times in a process each attach may return
 * a different signal handle.  Each returned signal handle is refcounted and
 * requires a matching number of calls to hsa_signal_destroy to release the
 * shared signal.
 *
 * @param[in] handle Pointer to the identifier for the shared signal.
 *
 * @param[out] signal Recieves a process local signal handle to the shared signal.
 *
 * @retval HSA_STATUS_SUCCESS if the signal is successfully imported.
 *
 * @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 @p handle is not valid.
 */
hsa_status_t HSA_API hsa_amd_ipc_signal_attach(const hsa_amd_ipc_signal_t* handle,
                                               hsa_signal_t* signal);

/**
 * @brief GPU system event type.
 */
typedef enum hsa_amd_event_type_s {
  /*
   AMD GPU memory fault.
   */
  HSA_AMD_GPU_MEMORY_FAULT_EVENT = 0,
  /*
   AMD GPU HW Exception.
   */
  HSA_AMD_GPU_HW_EXCEPTION_EVENT,
  /*
   AMD GPU memory error.
   */
  HSA_AMD_GPU_MEMORY_ERROR_EVENT,
  /*
   System shut down
    - All other fields in hsa_amd_event_t are unused
   */
  HSA_AMD_SYSTEM_SHUTDOWN_EVENT,
} hsa_amd_event_type_t;

/**
 * @brief Flags denoting the cause of a memory fault.
 */
typedef enum {
  // Page not present or supervisor privilege.
  HSA_AMD_MEMORY_FAULT_PAGE_NOT_PRESENT = 1 << 0,
  // Write access to a read-only page.
  HSA_AMD_MEMORY_FAULT_READ_ONLY = 1 << 1,
  // Execute access to a page marked NX.
  HSA_AMD_MEMORY_FAULT_NX = 1 << 2,
  // GPU attempted access to a host only page.
  HSA_AMD_MEMORY_FAULT_HOST_ONLY = 1 << 3,
  // DRAM ECC failure.
  HSA_AMD_MEMORY_FAULT_DRAMECC = 1 << 4,
  // Can't determine the exact fault address.
  HSA_AMD_MEMORY_FAULT_IMPRECISE = 1 << 5,
  // SRAM ECC failure (ie registers, no fault address).
  HSA_AMD_MEMORY_FAULT_SRAMECC = 1 << 6,
  // GPU reset following unspecified hang.
  HSA_AMD_MEMORY_FAULT_HANG = 1U << 31
} hsa_amd_memory_fault_reason_t;

/**
 * @brief AMD GPU memory fault event data.
 */
typedef struct hsa_amd_gpu_memory_fault_info_s {
  /*
  The agent where the memory fault occurred.
  */
  hsa_agent_t agent;
  /*
  Virtual address accessed.
  */
  uint64_t virtual_address;
  /*
  Bit field encoding the memory access failure reasons. There could be multiple bits set
  for one fault.  Bits are defined in hsa_amd_memory_fault_reason_t.
  */
  uint32_t fault_reason_mask;
} hsa_amd_gpu_memory_fault_info_t;

/**
 * @brief Flags denoting the cause of a memory error.
 */
typedef enum {
  // Memory was in use by low-level HW component and cannot be released
  HSA_AMD_MEMORY_ERROR_MEMORY_IN_USE = (1 << 0),
} hsa_amd_memory_error_reason_t;

/**
 * @brief AMD GPU memory error event data.
 */
typedef struct hsa_amd_gpu_memory_error_info_s {
  /*
  The agent where the memory error occurred.
  */
  hsa_agent_t agent;
  /*
  Virtual address involved.
  */
  uint64_t virtual_address;
  /*
  Bit field encoding the memory error failure reasons. There could be multiple bits set
  for one error.  Bits are defined in hsa_amd_memory_error_reason_t.
  */
  uint32_t error_reason_mask;
} hsa_amd_gpu_memory_error_info_t;

/**
 * @brief Flags denoting the type of a HW exception
 */
typedef enum {
  // Unused for now
  HSA_AMD_HW_EXCEPTION_RESET_TYPE_OTHER = 1 << 0,
} hsa_amd_hw_exception_reset_type_t;

/**
 * @brief Flags denoting the cause of a HW exception
 */
typedef enum {
  // GPU Hang
  HSA_AMD_HW_EXCEPTION_CAUSE_GPU_HANG = 1 << 0,
  // SRAM ECC
  HSA_AMD_HW_EXCEPTION_CAUSE_ECC = 1 << 1,
} hsa_amd_hw_exception_reset_cause_t;

/**
 * @brief AMD GPU HW Exception event data.
 */
typedef struct hsa_amd_gpu_hw_exception_info_s {
  /*
  The agent where the HW exception occurred.
  */
  hsa_agent_t agent;
  hsa_amd_hw_exception_reset_type_t reset_type;
  hsa_amd_hw_exception_reset_cause_t reset_cause;
} hsa_amd_gpu_hw_exception_info_t;

/**
 * @brief AMD GPU event data passed to event handler.
 */
typedef struct hsa_amd_event_s {
  /*
  The event type.
  */
  hsa_amd_event_type_t event_type;
  union {
    /*
    The memory fault info, only valid when @p event_type is HSA_AMD_GPU_MEMORY_FAULT_EVENT.
    */
    hsa_amd_gpu_memory_fault_info_t memory_fault;
    /*
    The memory fault info, only valid when @p event_type is HSA_AMD_GPU_HW_EXCEPTION_EVENT.
    */
    hsa_amd_gpu_hw_exception_info_t hw_exception;
    /*
    The memory error info, only valid when @p event_type is HSA_AMD_GPU_MEMORY_ERROR_EVENT.
    */
    hsa_amd_gpu_memory_error_info_t memory_error;
  };
} hsa_amd_event_t;

typedef hsa_status_t (*hsa_amd_system_event_callback_t)(const hsa_amd_event_t* event, void* data);

/**
 * @brief Register AMD GPU event handler.
 *
 * @param[in] callback Callback to be invoked when an event is triggered.
 * The HSA runtime passes two arguments to the callback: @p event
 * is defined per event by the HSA runtime, and @p data is the user data.
 *
 * @param[in] data User data that is passed to @p callback. May be NULL.
 *
 * @retval HSA_STATUS_SUCCESS The handler has been registered successfully.
 *
 * @retval HSA_STATUS_ERROR An event handler has already been registered.
 *
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p event is invalid.
 */
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.
 */
typedef enum hsa_amd_queue_priority_s {
  /*
  Below normal/high priority compute and all graphics
  */
  HSA_AMD_QUEUE_PRIORITY_LOW = 0,
  /*
  Above low priority compute, below high priority compute and all graphics
  */
  HSA_AMD_QUEUE_PRIORITY_NORMAL = 1,
  /*
  Above low/normal priority compute and all graphics
  */
  HSA_AMD_QUEUE_PRIORITY_HIGH = 2,
} hsa_amd_queue_priority_t;

/**
 * @brief Modifies the dispatch and wavefront scheduling prioirty for a
 * given compute queue. The default is HSA_AMD_QUEUE_PRIORITY_NORMAL.
 *
 * @param[in] queue Compute queue to apply new priority to.
 *
 * @param[in] priority Priority to associate with queue.
 *
 * @retval HSA_STATUS_SUCCESS if priority was changed successfully.
 *
 * @retval HSA_STATUS_ERROR_INVALID_QUEUE if queue is not a valid
 * compute queue handle.
 *
 * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT if priority is not a valid
 * value from hsa_amd_queue_priority_t.
 */
hsa_status_t HSA_API hsa_amd_queue_set_priority(hsa_queue_t* queue,
                                                hsa_amd_queue_priority_t priority);

/**
 * @brief Queue creation attributes.
 */
typedef enum {
  /**
   * The queue's packet buffer and queue descriptor struct should be
   * allocated in system memory (default). Mutually exclusive with
   * HSA_AMD_QUEUE_CREATE_DEVICE_MEM_RING_BUF and
   * HSA_AMD_QUEUE_CREATE_DEVICE_MEM_QUEUE_DESCRIPTOR.
   */
  HSA_AMD_QUEUE_CREATE_SYSTEM_MEM = 0,
  /**
   * The queue's packet buffer should be allocated in the agent's
   * local device memory region.
   */
  HSA_AMD_QUEUE_CREATE_DEVICE_MEM_RING_BUF = (1 << 0),
  /**
   * The queue desciptor struct should be allocated in the agent's
   * fine-grain device memory region. Not supported for devices
   * connected via PCIe because the CPU's atomic read-modify-write
   * operations cannot be promoted to PCIe atomic read-modify-write
   * operations.
   */
  HSA_AMD_QUEUE_CREATE_DEVICE_MEM_QUEUE_DESCRIPTOR = (1 << 1),
} hsa_amd_queue_create_flag_t;

/**
 * @brief Hardware engine type a queue targets.
 *
 * Selects which hardware engine the queue feeds. The default value (0)
 * is ::HSA_AMD_QUEUE_ENGINE_COMPUTE so that descriptors that leave the
 * @c engine_type field zero behave exactly like a classic compute (AQL)
 * queue. This keeps the descriptor ABI backward compatible: callers that
 * predate the @c engine_type field simply request a compute queue.
 *
 * The engine type also determines which other descriptor fields are
 * meaningful (see ::hsa_amd_queue_create_desc_t). For example, AQL queue
 * type, CU mask, and scratch (private segment) size apply only to the
 * compute engine, while @c sdma_engine_id applies only to the SDMA engine.
 *
 * @note ::HSA_AMD_QUEUE_ENGINE_COMPUTE and ::HSA_AMD_QUEUE_ENGINE_SDMA are
 * implemented today. The AIE engine type is reserved by the API so that tools
 * and applications can be written against the final interface, but the runtime
 * does not yet create AIE queues and will fail such requests with
 * ::HSA_STATUS_ERROR_INVALID_QUEUE_CREATION.
 */
typedef enum {
  /**
   * Compute (AQL) queue. This is the default engine type.
   */
  HSA_AMD_QUEUE_ENGINE_COMPUTE = 0,
  /**
   * SDMA (system DMA / copy) queue.
   */
  HSA_AMD_QUEUE_ENGINE_SDMA = 1,
  /**
   * AI Engine (AIE) queue. Reserved for future use; queue creation for
   * this engine type is not yet implemented.
   */
  HSA_AMD_QUEUE_ENGINE_AIE = 2,
} hsa_amd_queue_engine_t;

/**
 * @brief Sentinel for @c sdma_engine_id requesting runtime engine selection.
 *
 * When @c engine_type is ::HSA_AMD_QUEUE_ENGINE_SDMA and @c sdma_engine_id is
 * set to this value, the runtime selects an SDMA engine automatically,
 * rotating round-robin across the agent's SDMA engines so that concurrently
 * created queues are spread across the available hardware. Otherwise
 * @c sdma_engine_id selects a specific SDMA engine by index in
 * [0, agent's number of SDMA engines). The XGMI-optimized engines occupy the
 * upper portion of this engine-id space.
 *
 * In all cases the runtime creates the queue using the driver's
 * @c HSA_QUEUE_SDMA_BY_ENG_ID queue type, which requires sufficient KFD
 * support; requests are rejected with
 * ::HSA_STATUS_ERROR_INVALID_QUEUE_CREATION when the kernel driver cannot
 * target a specific SDMA engine.
 */
#define HSA_AMD_SDMA_ENGINE_ID_ANY UINT32_MAX

/**
 * @brief Version of the hsa_amd_queue_create_desc_t structure.
 *
 * Callers must set the @c version field to this value. The runtime rejects
 * descriptors whose version it does not recognise.
 */
#define HSA_AMD_QUEUE_CREATE_DESC_VERSION 1

/**
 * @brief Default value for @c private_segment_size in
 * ::hsa_amd_queue_create_desc_t.
 *
 * Requests the runtime's profile-dependent default scratch allocation.
 * Equivalent to passing @c UINT32_MAX to ::hsa_queue_create.
 */
#define HSA_AMD_PRIVATE_SEGMENT_SIZE_DEFAULT UINT32_MAX

/**
 * @brief Compute (AQL) queue parameters.
 *
 * Engine-specific parameters used when @c engine_type is
 * ::HSA_AMD_QUEUE_ENGINE_COMPUTE. Stored in the @c engine union of
 * ::hsa_amd_queue_create_desc_t.
 */
typedef struct hsa_amd_compute_queue_params_s {
  /** CU mask array. NULL when @c cu_mask_count is 0. Each bit corresponds to
   *  one CU; the array length is ceil(cu_mask_count / 32) uint32_t elements. */
  const uint32_t *cu_mask;
  /** Queue type: HSA_QUEUE_TYPE_MULTI, HSA_QUEUE_TYPE_SINGLE, or
   *  HSA_QUEUE_TYPE_COOPERATIVE. */
  hsa_queue_type32_t type;
  /** Initial scratch (private segment) size in bytes per work-item.
   *  0 = no scratch.  HSA_AMD_PRIVATE_SEGMENT_SIZE_DEFAULT = runtime default
   *  (profile-dependent).  Scratch may still grow dynamically beyond this
   *  initial allocation. */
  uint32_t private_segment_size;
  /** Number of bits in the CU mask. Must be a multiple of 32.
   *  0 = no CU mask (all CUs enabled). */
  uint32_t cu_mask_count;
  /** Reserved for future compute parameters. Must be 0. */
  uint32_t reserved[3];
} hsa_amd_compute_queue_params_t;

/**
 * @brief SDMA (system DMA / copy) queue parameters.
 *
 * Engine-specific parameters used when @c engine_type is
 * ::HSA_AMD_QUEUE_ENGINE_SDMA.
 *
 * SDMA queues created by this API are single-producer/external-synchronization
 * queues. The runtime exposes the ring through @c hsa_queue_t, but callers are
 * responsible for serializing packet production and for handling ring space,
 * wrap/no-op padding, packet writes, and ordered write-pointer/doorbell
 * publication before submitting work.
 */
typedef struct hsa_amd_sdma_queue_params_s {
  /** SDMA engine selector. HSA_AMD_SDMA_ENGINE_ID_ANY lets the runtime pick
   *  an engine; any other value selects a specific SDMA engine by index in
   *  [0, agent's number of SDMA engines). Maps to the kernel driver
   *  HSA_QUEUE_SDMA / HSA_QUEUE_SDMA_BY_ENG_ID queue types and the targeted
   *  engine id. */
  uint32_t sdma_engine_id;
  /** Reserved for future SDMA parameters. Must be 0. */
  uint32_t reserved[7];
} hsa_amd_sdma_queue_params_t;

/**
 * @brief AI Engine (AIE) queue parameters.
 *
 * Engine-specific parameters used when @c engine_type is
 * ::HSA_AMD_QUEUE_ENGINE_AIE. (AIE queue creation is not yet implemented.)
 */
typedef struct hsa_amd_aie_queue_params_s {
  /** Reserved for future AIE parameters. Must be 0. */
  uint32_t reserved[8];
} hsa_amd_aie_queue_params_t;

/**
 * @brief Describes a single queue to create within a batch.
 *
 * The descriptor is split into a common header (fields that apply to every
 * engine type) followed by an @c engine union that carries the parameters
 * specific to the selected @c engine_type. Callers fill in the common header
 * plus exactly one arm of the union. This makes the set of fields that apply
 * to each engine explicit rather than relying on "must be zero" rules for
 * inapplicable fields.
 *
 * A zero-initialised descriptor (with @c version set) requests a compute
 * (AQL) queue, because ::HSA_AMD_QUEUE_ENGINE_COMPUTE is 0 and the compute
 * arm is the zero state of the union. This keeps the descriptor backward
 * compatible with callers that only know about compute queues.
 *
 * On success the runtime writes the created queue into the @c queue field.
 * An array of descriptors can be passed to ::hsa_amd_queue_create to create
 * multiple queues in a single call.
 *
 * The @c version field must be set to @c HSA_AMD_QUEUE_CREATE_DESC_VERSION.
 * All @c reserved fields — including the reserved arm/bytes of the @c engine
 * union, the per-engine @c reserved members, and the trailing @c reserved
 * block — must be zero.
 *
 * Descriptor version 1 does not expose @c group_segment_size. The runtime
 * uses its default group-segment sizing, equivalent to passing @c UINT32_MAX
 * to ::hsa_queue_create.
 *
 * @note ::HSA_AMD_QUEUE_ENGINE_COMPUTE and ::HSA_AMD_QUEUE_ENGINE_SDMA are
 * implemented today. AIE requests are rejected with
 * ::HSA_STATUS_ERROR_INVALID_QUEUE_CREATION.
 */
typedef struct hsa_amd_queue_create_desc_s {
  /* ---- Common header: applies to every engine type ---- */
  /** Struct version. Must be HSA_AMD_QUEUE_CREATE_DESC_VERSION. */
  uint16_t version;
  /** Memory placement flags (hsa_amd_queue_create_flag_t). 0 = system memory. */
  uint16_t flags;
  /** Engine type the queue targets (hsa_amd_queue_engine_t).
   *  HSA_AMD_QUEUE_ENGINE_COMPUTE (0) selects a compute (AQL) queue and is
   *  the default. Selects which arm of the @c engine union is read. Only a
   *  small set of engine types exists, so this is a single byte. */
  uint8_t engine_type;
  /** Reserved header bytes for future common fields. Must be 0. */
  uint8_t reserved_header[3];
  /** Queue ring-buffer size in bytes. Must be a power of 2. For fixed-size
   *  packet queues, this must also be a multiple of the engine's packet size.
   *  For SDMA queues, the returned hsa_queue_t::size is also expressed in
   *  bytes because SDMA read/write pointers are byte offsets. */
  uint32_t queue_size_bytes;
  /** Dispatch and wavefront scheduling priority. HSA_AMD_QUEUE_PRIORITY_NORMAL = default. */
  hsa_amd_queue_priority_t priority;
  /** Callback invoked by the runtime for asynchronous queue errors. May be NULL. */
  void (*callback)(hsa_status_t status, hsa_queue_t *source, void *data);
  /** Application data passed to @c callback. May be NULL. */
  void *callback_data;
  /** [out] On success the runtime writes the created queue pointer here.
   *  On failure this is set to NULL. */
  hsa_queue_t *queue;
  union {
    /** Valid when @c engine_type == HSA_AMD_QUEUE_ENGINE_COMPUTE. */
    hsa_amd_compute_queue_params_t compute;
    /** Valid when @c engine_type == HSA_AMD_QUEUE_ENGINE_SDMA. */
    hsa_amd_sdma_queue_params_t sdma;
    /** Valid when @c engine_type == HSA_AMD_QUEUE_ENGINE_AIE. */
    hsa_amd_aie_queue_params_t aie;
    /** Fixes the union size to the v1 per-engine parameter budget. Must be 0
     *  for engine types whose arm does not cover it. */
    uint8_t reserved[32];
  } engine;
  /** Traffic class hint for the queue's memory/fabric traffic (QoS).
   *  Reserved for future use and not yet implemented: it must be 0, which
   *  selects the runtime default traffic class. */
  uint32_t traffic_class;
  /** Reserved for future use. Must be 0. */
  uint8_t reserved[20];
} hsa_amd_queue_create_desc_t;

/**
 * @brief Create one or more queues from an array of descriptors.
 *
 * @details Each element of @p descs fully describes a queue to create on
 * @p agent. The runtime creates the queue, applies the requested priority
 * and CU mask atomically, and writes the result to the descriptor's
 * @c queue output pointer.
 *
 * For single-queue creation pass @p num_descs = 1.
 *
 * On partial failure (batch mode), queues that were successfully created
 * remain valid. The caller should inspect each @c descs[i].queue pointer
 * (NULL indicates that particular queue failed). The return value reflects
 * the first error encountered.
 *
 * @param[in] agent Agent on which to create all queues.
 *
 * @param[in,out] descs Array of queue descriptors. Each descriptor's
 * @c queue field is an output parameter written by the runtime.
 *
 * @param[in] num_descs Number of elements in @p descs. Must be >= 1.
 *
 * @retval ::HSA_STATUS_SUCCESS All queues were created successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT @p agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p descs is NULL,
 * @p num_descs is 0, a descriptor's @c version is unrecognised,
 * @c queue_size_bytes is 0 or not a power of two, @c priority is invalid,
 * @c engine_type is not a valid ::hsa_amd_queue_engine_t value, the selected
 * engine's parameters are invalid (for compute: @c type is invalid,
 * @c queue_size_bytes is not a multiple of the AQL packet size, or
 * @c cu_mask_count is not a multiple of 32), @c traffic_class is non-zero
 * (it is reserved and not yet implemented), or any @c reserved field is
 * non-zero.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The runtime could not allocate
 * the required resources for one or more queues.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE_CREATION @p agent does not support
 * queues of the requested type, or a descriptor requested an @c engine_type
 * that is recognised by the API but not yet implemented by the runtime (for
 * example ::HSA_AMD_QUEUE_ENGINE_AIE).
 */
hsa_status_t HSA_API hsa_amd_queue_create(
    hsa_agent_t agent,
    hsa_amd_queue_create_desc_t *descs,
    uint32_t num_descs);

/** @} */

/** \addtogroup memory Memory
 *  @{
 */

/**
 * @brief Deallocation notifier function type.
 */
typedef void (*hsa_amd_deallocation_callback_t)(void* ptr, void* user_data);

/**
 * @brief Registers a deallocation notifier monitoring for release of agent
 * accessible address @p ptr.  If successful, @p callback will be invoked when
 * @p ptr is removed from accessibility from all agents.
 *
 * Notification callbacks are automatically deregistered when they are invoked.
 *
 * Note: The current version supports notifications of address release
 * originating from ::hsa_amd_memory_pool_free.  Support for other address
 * release APIs will follow.
 *
 * @param[in] ptr Agent accessible address to monitor for deallocation.  Passed
 * to @p callback.
 *
 * @param[in] callback Notifier to be invoked when @p ptr is released from
 * agent accessibility.
 *
 * @param[in] user_data User provided value passed to @p callback.  May be NULL.
 *
 * @retval ::HSA_STATUS_SUCCESS The notifier registered successfully
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION @p ptr does not refer to a valid agent accessible
 * address.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p callback is NULL or @p ptr is NULL.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
 * necessary resources
 */
hsa_status_t HSA_API hsa_amd_register_deallocation_callback(void* ptr,
                                                    hsa_amd_deallocation_callback_t callback,
                                                    void* user_data);

/**
 * @brief Removes a deallocation notifier previously registered with
 * ::hsa_amd_register_deallocation_callback.  Arguments must be identical to
 * those given in ::hsa_amd_register_deallocation_callback.
 *
 * @param[in] ptr Agent accessible address which was monitored for deallocation.
 *
 * @param[in] callback Notifier to be removed.
 *
 * @retval ::HSA_STATUS_SUCCESS The notifier has been removed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The given notifier was not registered.
 */
hsa_status_t HSA_API hsa_amd_deregister_deallocation_callback(void* ptr,
                                                      hsa_amd_deallocation_callback_t callback);

typedef enum hsa_amd_svm_model_s {
  /**
   * Updates to memory with this attribute conform to HSA memory consistency
   * model.
   */
  HSA_AMD_SVM_GLOBAL_FLAG_FINE_GRAINED = 0,
  /**
   * Writes to memory with this attribute can be performed by a single agent
   * at a time.
   */
  HSA_AMD_SVM_GLOBAL_FLAG_COARSE_GRAINED = 1,
  /**
   * Memory region queried contains subregions with both
   * HSA_AMD_SVM_GLOBAL_FLAG_COARSE_GRAINED and
   * HSA_AMD_SVM_GLOBAL_FLAG_FINE_GRAINED attributes.
   *
   * This attribute can not be used in hsa_amd_svm_attributes_set.  It is a
   * possible return from hsa_amd_svm_attributes_get indicating that the query
   * region contains both coarse and fine grained memory.
   */
  HSA_AMD_SVM_GLOBAL_FLAG_INDETERMINATE = 2
} hsa_amd_svm_model_t;

typedef enum hsa_amd_svm_attribute_s {
  // Memory model attribute.
  // Type of this attribute is hsa_amd_svm_model_t.
  HSA_AMD_SVM_ATTRIB_GLOBAL_FLAG = 0,
  // Marks the range read only.  This allows multiple physical copies to be
  // placed local to each accessing device.
  // Type of this attribute is bool.
  HSA_AMD_SVM_ATTRIB_READ_ONLY = 1,
  // Automatic migrations should attempt to keep the memory within the xgmi hive
  // containing accessible agents.
  // Type of this attribute is bool.
  HSA_AMD_SVM_ATTRIB_HIVE_LOCAL = 2,
  // Page granularity to migrate at once.  Page granularity is specified as
  // log2(page_count).
  // Type of this attribute is uint64_t.
  HSA_AMD_SVM_ATTRIB_MIGRATION_GRANULARITY = 3,
  // Physical location to prefer when automatic migration occurs.
  // Set to the null agent handle (handle == 0) to indicate there
  // is no preferred location.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_PREFERRED_LOCATION = 4,
  // This attribute can not be used in ::hsa_amd_svm_attributes_set (see
  // ::hsa_amd_svm_prefetch_async).
  // Queries the physical location of most recent prefetch command.
  // If the prefetch location has not been set or is not uniform across the
  // address range then returned hsa_agent_t::handle will be 0.
  // Querying this attribute will return the destination agent of the most
  // recent ::hsa_amd_svm_prefetch_async targeting the address range.  If
  // multiple async prefetches have been issued targeting the region and the
  // most recently issued prefetch has completed then the query will return
  // the location of the most recently completed prefetch.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION = 5,
  // Optimizes with the anticipation that the majority of operations to the
  // range will be read operations.
  // Type of this attribute is bool.
  HSA_AMD_SVM_ATTRIB_READ_MOSTLY = 6,
  // Allows the execution on GPU.
  // Type of this attribute is bool.
  HSA_AMD_SVM_ATTRIB_GPU_EXEC = 7,
  // This attribute can not be used in ::hsa_amd_svm_attributes_get.
  // Enables an agent for access to the range.  Access may incur a page fault
  // and associated memory migration.  Either this or
  // HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE is required prior to SVM
  // access if HSA_AMD_SYSTEM_INFO_SVM_ACCESSIBLE_BY_DEFAULT is false.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE = 0x200,
  // This attribute can not be used in ::hsa_amd_svm_attributes_get.
  // Enables an agent for access to the range without page faults.  Access
  // will not incur a page fault and will not cause access based migration.
  // and associated memory migration.  Either this or
  // HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE is required prior to SVM access if
  // HSA_AMD_SYSTEM_INFO_SVM_ACCESSIBLE_BY_DEFAULT is false.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE = 0x201,
  // This attribute can not be used in ::hsa_amd_svm_attributes_get.
  // Denies an agent access to the memory range.  Access will cause a terminal
  // segfault.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_AGENT_NO_ACCESS = 0x202,
  // This attribute can not be used in ::hsa_amd_svm_attributes_set.
  // Returns the access attribute associated with the agent.
  // The agent to query must be set in the attribute value field.
  // The attribute enum will be replaced with the agent's current access
  // attribute for the address range.
  // TODO: Clarify KFD return value for non-uniform access attribute.
  // Type of this attribute is hsa_agent_t.
  HSA_AMD_SVM_ATTRIB_ACCESS_QUERY = 0x203,
} hsa_amd_svm_attribute_t;

// List type for hsa_amd_svm_attributes_set/get.
typedef struct hsa_amd_svm_attribute_pair_s {
  // hsa_amd_svm_attribute_t value.
  uint64_t attribute;
  // Attribute value.  Bit values should be interpreted according to the type
  // given in the associated attribute description.
  uint64_t value;
} hsa_amd_svm_attribute_pair_t;

/**
 * @brief Sets SVM memory attributes.
 *
 * If HSA_AMD_SYSTEM_INFO_SVM_ACCESSIBLE_BY_DEFAULT returns false then enabling
 * access to an Agent via this API (setting HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE
 * or HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE) is required prior to SVM
 * memory access by that Agent.
 *
 * Attributes HSA_AMD_SVM_ATTRIB_ACCESS_QUERY and HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION
 * may not be used with this API.
 *
 * @param[in] ptr Will be aligned down to nearest page boundary.
 *
 * @param[in] size Will be aligned up to nearest page boundary.
 *
 * @param[in] attribute_list List of attributes to set for the address range.
 *
 * @param[in] attribute_count Length of @p attribute_list.
 */
hsa_status_t hsa_amd_svm_attributes_set(void* ptr, size_t size,
                                        hsa_amd_svm_attribute_pair_t* attribute_list,
                                        size_t attribute_count);

/**
 * @brief Gets SVM memory attributes.
 *
 * Attributes HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE,
 * HSA_AMD_SVM_ATTRIB_AGENT_ACCESSIBLE_IN_PLACE and
 * HSA_AMD_SVM_ATTRIB_PREFETCH_LOCATION may not be used with this API.
 *
 * Note that attribute HSA_AMD_SVM_ATTRIB_ACCESS_QUERY takes as input an
 * hsa_agent_t and returns the current access type through its attribute field.
 *
 * @param[in] ptr Will be aligned down to nearest page boundary.
 *
 * @param[in] size Will be aligned up to nearest page boundary.
 *
 * @param[in] attribute_list List of attributes to set for the address range.
 *
 * @param[in] attribute_count Length of @p attribute_list.
 */
hsa_status_t hsa_amd_svm_attributes_get(void* ptr, size_t size,
                                        hsa_amd_svm_attribute_pair_t* attribute_list,
                                        size_t attribute_count);

/**
 * @brief Asynchronously migrates memory to an agent.
 *
 * Schedules memory migration to @p agent when @p dep_signals have been observed equal to zero.
 * @p completion_signal will decrement when the migration is complete.
 *
 * @param[in] ptr Will be aligned down to nearest page boundary.
 *
 * @param[in] size Will be aligned up to nearest page boundary.
 *
 * @param[in] agent Agent to migrate to.
 *
 * @param[in] num_dep_signals Number of dependent signals. Can be 0.
 *
 * @param[in] dep_signals List of signals that must be waited on before the migration
 * operation starts. The migration will start after every signal has been observed with
 * the value 0. If @p num_dep_signals is 0, this argument is ignored.
 *
 * @param[in] completion_signal Signal used to indicate completion of the migration
 * operation. When the migration operation is finished, the value of the signal is
 * decremented. The runtime indicates that an error has occurred during the copy
 * operation by setting the value of the completion signal to a negative
 * number. If no completion signal is required this handle may be null.
 */
hsa_status_t hsa_amd_svm_prefetch_async(void* ptr, size_t size, hsa_agent_t agent,
                                        uint32_t num_dep_signals, const hsa_signal_t* dep_signals,
                                        hsa_signal_t completion_signal);

/**
 * @brief Discards a batch of SVM memory ranges asynchronously.
 *
 * Schedules the discard of multiple SVM ranges in a single batched operation.
 * The physical pages backing the virtual address ranges may be released and reclaimed
 * by the system under memory pressure. The discard will be scheduled when all @p dep_signals
 * have been resolved.
 *
 * Only pointers allocated using ::hsa_amd_vmem_address_reserve can be discarded.
 *
 *
 * @param[in] ptrs Array of @p count pointers to SVM memory ranges to discard.
 * Must not be NULL.
 *
 * @param[in] sizes Array of @p ptr sizes, specifying the length of each memory range
 * to discard. Must not be NULL.
 *
 * @param[in] count Number of memory ranges in the @p ptrs and @p sizes arrays. Must not be 0.
 *
 * @param[in] num_dep_signals Number of dependent signals. Can be 0.
 *
 * @param[in] dep_signals List of dependency signals to wait for before the discard operation
 * starts. Can be NULL.
 *
 * @param[in] completion_signal Signal used to indicate completion of the discard operation.
 * May be a NULL signal if no completion signal is required.
 *
 * @retval ::HSA_STATUS_SUCCESS Discard operation was successfully scheduled.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED HSA runtime has not been initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptrs is NULL, @p sizes is
 * NULL, @p count is 0, @p dep_signals and @p num_dep_signals are inconsistent.
 *
 * @retval ::HSA_STATUS_ERROR_XNACK_DISABLED Cannot run this API on a system with XNACK disabled.
 */
hsa_status_t HSA_API hsa_amd_svm_discard_batch_async(void** ptrs, size_t* sizes, uint32_t count,
                                                     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
 *
 * Acquire exclusive use of SPM on @p preferred_agent.
 * See hsa_amd_spm_set_dest_buffer to provide a destination buffer to KFD to start recording and
 * retrieve this data.
 * @param[in] preferred_agent Agent on which to acquire SPM
 */
hsa_status_t hsa_amd_spm_acquire(hsa_agent_t preferred_agent);

/**
 * @brief Release Stream Performance Monitor on an agent
 *
 * Release exclusive use of SPM on @p preferred_agent. This will stop KFD writing SPM data.
 * If a destination buffer is set, then data in the destination buffer is available to user
 * when this function returns.
 *
 * @param[in] preferred_agent Agent on which to release SPM
 */
hsa_status_t hsa_amd_spm_release(hsa_agent_t preferred_agent);

/**
 * @brief  Set up the current destination user mode buffer for stream performance
 * counter data. KFD will start writing SPM data into the destination buffer. KFD will continue
 * to copy data into the current destination buffer until any of the following functions are called
 * - hsa_amd_spm_release
 * - hsa_amd_spm_set_dest_buffer with dest set to NULL
 * - hsa_amd_spm_set_dest_buffer with dest set to a new buffer
 *
 * if @p timeout is non-0, the call will wait for up to @p timeout ms for the previous
 * buffer to be filled. If previous buffer to be filled before timeout, the @p timeout
 * will be updated value with the time remaining. If the timeout is exceeded, the function
 * copies any partial data available into the previous user buffer and returns success.
 * User should not access destination data while KFD is copying data.
 * If the previous destination buffer was full, then @p is_data_loss flag is set.
 * @p dest is CPU accessible memory. It could be malloc'ed memory or host allocated memory
 *
 * @param[in] preferred_agent Agent on which to set the dest buffer
 *
 * @param[in] size_in_bytes size of the buffer
 *
 * @param[in,out] timeout timeout in milliseconds
 *
 * @param[out] size_copied number of bytes copied
 *
 * @param[in] dest destination address. Set to NULL to stop copy on previous buffer
 *
 * @param[out] is_data_loss true is data was lost
 */
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 Older version of export dmabuf
 *
 * This is the same as calling the v2 version of export dmabuf with the
 * flags argument set to HSA_AMD_DMABUF_MAPPING_TYPE_NONE.
 *
 * @param[in] ptr Pointer to the allocation being exported.
 *
 * @param[in] size Size in bytes to export following @p ptr.  The entire range
 * being exported must be contained within a single allocation.
 *
 * @param[out] dmabuf Pointer to a dma-buf file descriptor holding a reference to the
 * allocation.  Contents will not be altered in the event of failure.
 *
 * @param[out] offset Offset in bytes into the memory referenced by the dma-buf
 * object at which @p ptr resides.  Contents will not be altered in the event
 * of failure.
 *
 * @retval ::HSA_STATUS_SUCCESS Export completed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT One or more arguments is NULL.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION The address range described by
 * @p ptr and @p size are not contained within a single allocation.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The allocation described by @p ptr
 * and @p size was allocated on a device which can not export memory.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The return file descriptor,
 * @p dmabuf, could not be created.
 */
hsa_status_t hsa_amd_portable_export_dmabuf(const void* ptr, size_t size, int* dmabuf,
                                            uint64_t* offset);

                                            /**
 * @brief Obtains an OS specific, vendor neutral, handle to a memory allocation.
 *
 * Obtains an OS specific handle to GPU agent memory.  The memory must be part
 * of a single allocation from an hsa_amd_memory_pool_t exposed by a GPU Agent.
 * The handle may be used with other APIs (e.g. Vulkan) to obtain shared access
 * to the allocation.
 *
 * Shared access to the memory is not guaranteed to be fine grain coherent even
 * if the allocation exported is from a fine grain pool.  The shared memory
 * consistency model will be no stronger than the model exported from, consult
 * the importing API to determine the final consistency model.
 *
 * The allocation's memory remains valid as long as the handle and any mapping
 * of the handle remains valid.  When the handle and all mappings are closed
 * the backing memory will be released for reuse.
 *
 * @param[in] ptr Pointer to the allocation being exported.
 *
 * @param[in] size Size in bytes to export following @p ptr.  The entire range
 * being exported must be contained within a single allocation.
 *
 * @param[out] dmabuf Pointer to a dma-buf file descriptor holding a reference to the
 * allocation.  Contents will not be altered in the event of failure.
 *
 * @param[out] offset Offset in bytes into the memory referenced by the dma-buf
 * object at which @p ptr resides.  Contents will not be altered in the event
 * of failure.
 *
 * @param[in] flags Bitmask of hsa_amd_dma_buf_mapping_type_t flags.
 *
 * @retval ::HSA_STATUS_SUCCESS Export completed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT One or more arguments is NULL.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION The address range described by
 * @p ptr and @p size are not contained within a single allocation.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The allocation described by @p ptr
 * and @p size was allocated on a device which can not export memory.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The return file descriptor,
 * @p dmabuf, could not be created.
 */
hsa_status_t hsa_amd_portable_export_dmabuf_v2(const void* ptr, size_t size,
                               int* dmabuf, uint64_t* offset, uint64_t flags);

/**
 * @brief Closes an OS specific, vendor neutral, handle to a memory allocation.
 *
 * Closes an OS specific handle to GPU agent memory.
 *
 * Applications should close a handle after imports are complete.  The handle
 * is not required to remain open for the lifetime of imported mappings.  The
 * referenced allocation will remain valid until all handles and mappings
 * are closed.
 *
 * @param[in] dmabuf Handle to be closed.
 *
 * @retval ::HSA_STATUS_SUCCESS Handle closed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_RESOURCE_FREE A generic error was encountered
 * when closing the handle.  The handle may have been closed already or an
 * async IO error may have occured.
 */
hsa_status_t hsa_amd_portable_close_dmabuf(int dmabuf);

typedef enum hsa_amd_vmem_address_reserve_flag_s {
  // Only reserve a VA range without registering it to the underlying driver
  HSA_AMD_VMEM_ADDRESS_NO_REGISTER = (1UL << 0),
} hsa_amd_vmem_address_reserve_flag_t;

/**
 * @brief Allocate a reserved address range
 *
 * Reserve a virtual address range. The size must be a multiple of the system page size.
 * If it is not possible to allocate the address specified by @p address, then @p va will be
 * a different address range.
 * Address range should be released by calling hsa_amd_vmem_address_free.
 *
 * @param[out] va virtual address allocated
 * @param[in] size of address range requested
 * @param[in] address requested
 * @param[in] flags optional hsa_amd_vmem_address_reserve_flag_t
 *
 * @retval ::HSA_STATUS_SUCCESS Address range allocated successfully
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Insufficient resources to allocate an address
 * range of this size.
 *
 * Note that this API will be deprecated in a future release and replaced by
 * hsa_amd_vmem_address_reserve_align
 */
hsa_status_t hsa_amd_vmem_address_reserve(void** va, size_t size, uint64_t address,
                                          uint64_t flags);

/**
 * @brief Allocate a reserved address range
 *
 * Reserve a virtual address range. The size must be a multiple of the system page size.
 * If it is not possible to allocate the address specified by @p address, then @p va will be
 * a different address range.
 * Address range should be released by calling hsa_amd_vmem_address_free.
 *
 * @param[out] va virtual address allocated
 * @param[in] size of address range requested
 * @param[in] address requested
 * @param[in] alignment requested. 0 for default. Must be >= page-size and a power of 2
 * @param[in] flags optional hsa_amd_vmem_address_reserve_flag_t
 *
 * @retval ::HSA_STATUS_SUCCESS Address range allocated successfully
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Insufficient resources to allocate an address
 * range of this size.
 */
hsa_status_t hsa_amd_vmem_address_reserve_align(void** va, size_t size, uint64_t address,
                                          uint64_t alignment, uint64_t flags);

/**
 * @brief Free a reserved address range
 *
 * Free a previously allocated address range. The size must match the size of a previously
 * allocated address range.
 *
 * @param[out] va virtual address to be freed
 * @param[in] size of address range
 *
 * @retval ::HSA_STATUS_SUCCESS Address range released successfully
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid va specified
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT Invalid size specified
 * @retval ::HSA_STATUS_ERROR_RESOURCE_FREE Address range is still in use
 * @retval ::HSA_STATUS_ERROR Internal unexpected error
 */
hsa_status_t hsa_amd_vmem_address_free(void* va, size_t size);

/**
 * @brief Struct containing an opaque handle to a memory allocation handle
 */
typedef struct hsa_amd_vmem_alloc_handle_s {
  /**
   * Opaque handle. Two handles reference the same object of the enclosing type
   * if and only if they are equal.
   */
  uint64_t handle;
} hsa_amd_vmem_alloc_handle_t;

typedef enum {
  MEMORY_TYPE_NONE,
  MEMORY_TYPE_PINNED,
} hsa_amd_memory_type_t;

/**
 * @brief Create a virtual memory handle
 *
 * Create a virtual memory handle within this pool
 * @p size must be a aligned to allocation granule size for this memory pool, see
 * HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE
 * To minimize internal memory fragmentation, align the size to the recommended allocation granule
 * size, see HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_REC_GRANULE
 *
 * @param[in] pool memory to use.
 * @param[in] size of the memory allocation
 * @param[in] type of memory
 * @param[in] flags - currently unsupported
 * @param[out] memory_handle - handle for the allocation
 *
 * @retval ::HSA_STATUS_SUCCESS memory allocated successfully
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT Invalid arguments
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION This memory pool does not support allocations
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Insufficient resources to allocate this memory
 */
hsa_status_t hsa_amd_vmem_handle_create(hsa_amd_memory_pool_t pool, size_t size,
                                        hsa_amd_memory_type_t type, uint64_t flags,
                                        hsa_amd_vmem_alloc_handle_t* memory_handle);

/**
 * @brief Release a virtual memory handle
 *
 * @param[in] memory handle that was previously allocated
 *
 * @retval ::HSA_STATUS_SUCCESS Address range allocated successfully
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory handle
 */
hsa_status_t hsa_amd_vmem_handle_release(hsa_amd_vmem_alloc_handle_t memory_handle);

/**
 * @brief Map a virtual memory handle
 *
 * Map a virtual memory handle to a reserved address range. The virtual address requested must be
 * within a previously reserved address range. @p va and (@p va + size) must be must be within
 * (va + size) of the previous allocated address range.
 * @p size must be equal to size of the @p memory_handle
 * hsa_amd_vmem_set_access needs to be called to make the memory accessible to specific agents
 *
 * @param[in] va virtual address range where memory will be mapped
 * @param[in] size of memory mapping
 * @param[in] in_offset offset into memory. Currently unsupported
 * @param[in] memory_handle virtual memory handle to be mapped
 * @param[in] flags. Currently unsupported
 *
 * @retval ::HSA_STATUS_SUCCESS Memory mapped successfully
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT va, size or memory_handle are invalid
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Insufficient resources
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_map(void* va, size_t size, size_t in_offset,
                              hsa_amd_vmem_alloc_handle_t memory_handle, uint64_t flags);

/**
 * @brief Unmap a virtual memory handle
 *
 * Unmap previously mapped virtual address range
 *
 * @param[in] va virtual address range where memory will be mapped
 * @param[in] size of memory mapping
 *
 * @retval ::HSA_STATUS_SUCCESS Memory backing unmapped successfully
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION memory_handle is invalid
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT size is invalid
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_unmap(void* va, size_t size);

typedef struct hsa_amd_memory_access_desc_s {
  hsa_access_permission_t permissions;
  hsa_agent_t agent_handle;
} hsa_amd_memory_access_desc_t;

/**
 * @brief Make a memory mapping accessible
 *
 * Make previously mapped virtual address accessible to specific agents. @p size must be equal to
 * size of previously mapped virtual memory handle.
 * Calling hsa_amd_vmem_set_access multiple times on the same @p va:
 *  - Will overwrite permissions for agents specified in @p desc
 *  - Will leave permissions unchanged for agents not specified in @p desc
 *
 * @param[in] va previously mapped virtual address
 * @param[in] size of memory mapping
 * @param[in] desc list of access permissions for each agent
 * @param[in] desc_cnt number of elements in desc
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT va, size or memory_handle are invalid
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION memory_handle is invalid
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Insufficient resources
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT Invalid agent in desc
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_set_access(void* va, size_t size,
                                     const hsa_amd_memory_access_desc_t* desc,
                                     size_t desc_cnt);

/**
 * @brief Get current access permissions for memory mapping
 *
 * Get access permissions for memory mapping for specific agent.
 *
 * @param[in] va previously mapped virtual address
 * @param[in] perms current permissions
 * @param[in] agent_handle agent
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT Invalid agent
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION va is not mapped or permissions never set for this
 * agent
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_get_access(void* va, hsa_access_permission_t* perms,
                                     hsa_agent_t agent_handle);

/**
 * @brief Get an exportable locally unique shareable handle
 *
 * Get an exportable shareable handle for a memory_handle. This shareabl handle can then be used to
 * re-create a virtual memory handle using hsa_amd_vmem_import_shareable_handle. The shareable
 * handle can be transferred using mechanisms that support posix file descriptors Once all shareable
 * handles are closed, the memory_handle is released.
 *
 * @param[out] dmabuf_fd shareable handle
 * @param[in] handle previously allocated virtual memory handle
 * @param[in] flags Currently unsupported
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory handle
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Out of resources
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_export_shareable_handle(int* dmabuf_fd,
                                                  hsa_amd_vmem_alloc_handle_t handle,
                                                  uint64_t flags);
/**
 * @brief Import a shareable handle
 *
 * Import a shareable handle for a memory handle. Importing a shareable handle that has been closed
 * and released results in undefined behavior.
 *
 * @param[in] dmabuf_fd shareable handle exported with hsa_amd_vmem_export_shareable_handle
 * @param[out] handle virtual memory handle
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory handle
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Out of resources
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_import_shareable_handle(int dmabuf_fd,
                                                  hsa_amd_vmem_alloc_handle_t* handle);

/**
 * @brief Returns memory handle for mapped memory
 *
 * Return a memory handle for previously mapped memory. The handle will be the same value of handle
 * used to map the memory. The returned handle must be released with corresponding number of calls
 * to hsa_amd_vmem_handle_release.
 *
 * @param[out] memory_handle memory handle for this mapped address
 * @param[in] mapped address
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid address
 */
hsa_status_t hsa_amd_vmem_retain_alloc_handle(hsa_amd_vmem_alloc_handle_t* memory_handle,
                                              void* addr);

/**
 * @brief Returns the current allocation properties of a handle
 *
 * Returns the allocation properties of an existing handle
 *
 * @param[in] memory_handle memory handle to be queried
 * @param[out] pool memory pool that owns this handle
 * @param[out] memory type

 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory_handle
 */
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);

/**
 * @brief 128-bit globally unique identifier for a ROCr shared memory
 * allocation.
 */
typedef struct hsa_fabric_handle_s {
  uint8_t handle[16];
} hsa_fabric_handle_t;


/**
 * Get a globally-unique exportable shareable handle for a memory_handle.
 * This shareable handle can then be used to re-create a virtual memory handle
 * using hsa_amd_vmem_import_shareable_handle. Once all shareable handles are
 * closed, the memory_handle is released.
 * This is only supported on handles allocated on GPU agents.
 *
 * @param[out] fabric_handle fabric handle
 * @param[in] handle previously allocated virtual memory handle
 * @param[in] flags Currently unsupported
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory handle
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Out of resources
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_export_fabric_handle(hsa_fabric_handle_t *fabric_handle,
                                               hsa_amd_vmem_alloc_handle_t handle,
                                               uint64_t flags);

/**
 * @brief Import a globally-unique shareable handle
 *
 * Import a shareable handle for a memory handle. Importing a shareable handle that has been closed
 * and released results in undefined behavior.
 *
 * @param[in] fabric_handle shareable handle exported with hsa_amd_vmem_export_shareable_handle
 * @param[out] handle virtual memory handle
 *
 * @retval ::HSA_STATUS_SUCCESS
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION Invalid memory handle
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Out of resources
 *
 * @retval ::HSA_STATUS_ERROR Unexpected internal error
 */
hsa_status_t hsa_amd_vmem_import_fabric_handle(hsa_fabric_handle_t fabric_handle,
                                               hsa_amd_vmem_alloc_handle_t* handle);
/** @} */

/** \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
 * result in a scratch use-once method.
 *
 * Increasing this threshold will only increase the internal limit and not cause immediate allocation
 * of additional scratch memory. Decreasing this threshold will result in a release in scratch memory
 * on queues where the current amount of allocated scratch exceeds the new limit.
 *
 * If this API call would result in a release in scratch memory and there are dispatches that are
 * currently using scratch memory on this agent, this will result into a blocking call until the
 * current dispatches are completed.
 *
 * This API is only supported on devices that support asynchronous scratch reclaim.
 *
 * @param[in] agent A valid agent.
 *
 * @param[in] threshold Threshold size in bytes
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT This agent does not support asynchronous scratch
 * reclaim
 */
hsa_status_t HSA_API hsa_amd_agent_set_async_scratch_limit(hsa_agent_t agent, size_t threshold);

typedef enum {
  /*
   * Returns the agent that owns the underlying HW queue.
   * The type of this attribute is hsa_agent_t.
   */
  HSA_AMD_QUEUE_INFO_AGENT,
  /*
   * Returns the doorbell ID of the completion signal of the queue
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_QUEUE_INFO_DOORBELL_ID,
  /*
   * Returns how many times the underlying hardware queue has been shared.
   * @p value will be set to -1 if this queue was not allocated using
   * hsa_amd_counted_queue_acquire. The type of this attribute is uint32_t.
   */
  HSA_QUEUE_INFO_USE_COUNT,
  /*
   * Returns a unique ID representing the HW resource used by a counted queue. Two queues
   * with the same HW_ID use the same underlying hardware queue. This query can be
   * used on counted and non-counted queues. The type of this attribute is uint32_t.
   */
  HSA_QUEUE_INFO_HW_ID,
  /*
   * Major version of metadata prefetch dispatch packet. The versioning starts at 0.
   * Returns 0xFF if metadata prefetch is not supported.
   * The type of this attribute is uint8_t.
   */
  HSA_AMD_QUEUE_INFO_PREFETCH_METADATA_DISPATCH_PKT_VERSION_MAJOR,
  /*
   * Minor version of metadata prefetch dispatch packet. The versioning starts at 0.
   * Returns 0xFF if metadata prefetch is not supported.
   * The type of this attribute is uint8_t.
   */
  HSA_AMD_QUEUE_INFO_PREFETCH_METADATA_DISPATCH_PKT_VERSION_MINOR,
  /*
   * Major version of metadata prefetch barrier packet. The versioning starts at 0.
   * Returns 0xFF if metadata prefetch is not supported.
   * The type of this attribute is uint8_t.
   */
  HSA_AMD_QUEUE_INFO_PREFETCH_METADATA_BARRIER_PKT_VERSION_MAJOR,
  /*
   * Minor version of metadata prefetch barrier packet. The versioning starts at 0.
   * Returns 0xFF if metadata prefetch is not supported.
   * The type of this attribute is uint8_t.
   */
  HSA_AMD_QUEUE_INFO_PREFETCH_METADATA_BARRIER_PKT_VERSION_MINOR,
  /*
   * If supported by the underlying HW, returns the address of the metadata ring
   * buffer. The type of this attribute is uint64_t.
   */
  HSA_AMD_QUEUE_INFO_PREFETCH_METADATA_RING_BUFFER,
  /*
   * Bit-mask indicating properties of this queue.
   * The type of this attribute is uint8_t[8].
   */
  HSA_AMD_QUEUE_INFO_PROPERTIES,

  /*
   * Per-queue VM fault state — populated after a GPU memory fault.
   */

  /*
   * Whether this queue has experienced a VM fault.
   * The type of this attribute is bool.
   */
  HSA_AMD_QUEUE_INFO_VM_FAULT_STATUS,
  /*
   * The virtual address that caused the VM fault on this queue.
   * Only valid when HSA_AMD_QUEUE_INFO_VM_FAULT_STATUS is true.
   * The type of this attribute is uint64_t.
   */
  HSA_AMD_QUEUE_INFO_VM_FAULT_ADDRESS,
  /*
   * A bitmask of HSA_AMD_MEMORY_FAULT_* flags describing the reason for the
   * VM fault on this queue.  Only valid when HSA_AMD_QUEUE_INFO_VM_FAULT_STATUS
   * is true.  The type of this attribute is uint32_t.
   */
  HSA_AMD_QUEUE_INFO_VM_FAULT_REASON,
  /*
   * Hardware engine type targeted by this queue.
   * The type of this attribute is hsa_amd_queue_engine_t.
   */
  HSA_AMD_QUEUE_INFO_ENGINE_TYPE,
  /*
   * Resolved hardware SDMA engine ID. Automatic SDMA queue creation returns
   * the selected engine ID, never HSA_AMD_SDMA_ENGINE_ID_ANY. This attribute
   * is valid only for queues whose engine type is HSA_AMD_QUEUE_ENGINE_SDMA.
   * The type of this attribute is uint32_t.
   */
  HSA_AMD_QUEUE_INFO_SDMA_ENGINE_ID,
} hsa_queue_info_attribute_t;

hsa_status_t hsa_amd_queue_get_info(hsa_queue_t* queue, hsa_queue_info_attribute_t attribute,
                                    void* value);

typedef struct hsa_amd_ais_file_handle_s {
  /*
   * file handle for AIS read & write. Linux will use fd.
   * pad is keep the size consistent accross different platforms.
   */
  union {
    void*      handle;
    int        fd;
    uint8_t    pad[8];
  };
} hsa_amd_ais_file_handle_t;

/**
 * @brief Write data from device memory to a file
 *
 * Writes data from device memory buffer to a file at the specified offset.
 * The device memory pointer must be accessible from the host and point to
 * a valid allocation.
 *
 * EXPERIMENTAL: AIS read and write calls are currently in experimental phase and
 *  APIs may be modified
 *
 * @param[in] handle Handle of the file to write to.
 *
 * @param[in] devicePtr Device memory buffer pointer containing data to write.
 *
 * @param[in] size Size in bytes of the data to write.
 *
 * @param[in] file_offset Offset in bytes into the file where data will be written.
 *
 * @param[in/out] size_copied Actual number of bytes copied
 *
 * @param[in/out] status Additional status if any
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p fd is invalid, @p devicePtr
 * is NULL, or @p size is 0.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION @p devicePtr does not refer to
 * a valid allocation.
 *
 * @retval ::HSA_STATUS_ERROR An error occurred during the write operation.
 */
hsa_status_t HSA_API hsa_amd_ais_file_write(hsa_amd_ais_file_handle_t handle, void *devicePtr,
                                            uint64_t size, int64_t file_offset,
                                            uint64_t *size_copied, int32_t *status);

/**
 * @brief Read data from a file to device memory
 *
 * Reads data from a file at the specified offset into a device memory buffer.
 * The device memory pointer must be accessible from the host and point to
 * a valid allocation.
 *
 * EXPERIMENTAL: AIS read and write calls are currently in experimental phase and
 *  APIs may be modified
 * @param[in] hanlde Handle of the file to read from.
 *
 * @param[in] devicePtr Device memory buffer pointer to store the read data.
 *
 * @param[in] size Size in bytes of the data to read.
 *
 * @param[in] file_offset Offset in bytes into the file where data will be read from.
 *
 * @param[in/out] size_copied Actual number of bytes copied
 *
 * @param[in/out] status Additional status if any
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p fd is invalid, @p devicePtr
 * is NULL, or @p size is 0.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION @p devicePtr does not refer to
 * a valid allocation.
 *
 * @retval ::HSA_STATUS_ERROR An error occurred during the read operation.
 */
hsa_status_t HSA_API hsa_amd_ais_file_read(hsa_amd_ais_file_handle_t handle, void *devicePtr,
                                           uint64_t size, int64_t file_offset,
                                           uint64_t *size_copied, int32_t *status);

/**
 * @brief Create a queue that is limited by the GPU_MAX_HW_QUEUES environment variable.
 *
 * This underlying hardware queue returned by this function may be shared by other queues. For
 * each priority this function will create a new hardware queue as long as the number of queues
 * is less than GPU_MAX_HW_QUEUES. Once the GPU_MAX_HW_QUEUES limit is reached, this function will
 * stop creating new hardware queues and return a reference to an existing queue of the requested
 * @p priority instead. Each successful call will return a different @p queue handle.
 * The hsa_amd_queue_get_info API can be used to determine whether this queue is currently shared.
 *
 * When there are multiple eligible hardware queues available, the queue with the lowest
 * HSA_QUEUE_INFO_USE_COUNT will be returned.
 *
 * For each successful call, hsa_amd_counted_queue_release should be called to release the
 * HSA_QUEUE_INFO_USE_COUNT. After release, the queue handle becomes invalid and must not be used.
 *
 * hsa_amd_queue_set_priority and hsa_amd_queue_cu_set_mask cannot be used on counted queues.
 *
 * @param[in] agent Agent where to create the queue
 *
 * @param[in] type  For future use. HSA_QUEUE_TYPE_MULTI is the only valid option.
 * HSA_QUEUE_TYPE_COOPERATIVE queues are not supported.
 *
 * @param[in] priority Associated priority. The GPU_MAX_HW_QUEUES limit is counted for each priority
 *
 * @param[in] callback callback invoked by the HSA runtime for every asynchronous event related to
 * the newly created queue. May be NULL. The HSA runtime passes three arguments to the callback: a
 * code identifying the event that triggered the invocation, a pointer to the queue where the event
 * originated, and the application data.
 *
 * @param[in] data Application data that is passed to @p callback on every iteration. May be NULL.
 *
 * @param[in] flags For future use. Ignored.
 *
 * @param[out] queue Unique handle to reference the newly created queue.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
 *
 * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is failure to allocate the resources required
 * by the implementation.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid or not a GPU agent.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE_CREATION @p type is not HSA_QUEUE_TYPE_MULTI.
 *
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT Invalid priority or NULL queue pointer.
 */
hsa_status_t HSA_API hsa_amd_counted_queue_acquire(hsa_agent_t agent, hsa_queue_type_t type,
                                           hsa_amd_queue_priority_t priority,
                                           void (*callback)(hsa_status_t status,
                                                            hsa_queue_t* source, void* data),
                                           void* data, uint64_t flags, hsa_queue_t** queue);

/**
 * @brief Release a counted queue and decrements its use count.
 *
 * Releases a queue that was previously acquired using hsa_amd_counted_queue_acquire.
 * Each call to this API decrements the internal use count HSA_QUEUE_INFO_USE_COUNT
 * of the underlying hardware. After this call, queue handle is invalid and must not be used.
 * Once created, the hardware queue is retained until hsa_shutdown is called to avoid costly
 * overhead of repeatedly creating new hardware queues, allowing them to be reused.
 *
 *
 * @param[in] queue Counted queue handle returned from hsa_amd_counted_queue_acquire.
 * Must not be NULL.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 * @retval ::HSA_STATUS_ERROR Invalid queue or queue was already released.
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been initialized.
 * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The @p queue is NULL or previously released.
 * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The queue's agent is invalid or not a GPU agent.
 */
hsa_status_t HSA_API hsa_amd_counted_queue_release(hsa_queue_t* queue);

/**
 * @brief logging types
 */
typedef enum hsa_amd_log_flag_s {
  /* Log AQL packets internally enqueued by ROCr */
  HSA_AMD_LOG_FLAG_BLIT_KERNEL_PKTS = 0,
  HSA_AMD_LOG_FLAG_AQL = 0,
  /* Log SDMA packets */
  HSA_AMD_LOG_FLAG_SDMA = 1,
  /* Log INFO */
  HSA_AMD_LOG_FLAG_INFO = 2,
} hsa_amd_log_flag_t;

/**
 * @brief Enable logging via external file
 * If this function is called multiple times, the last call to this function will overwrite the
 * previous @p flags and @p file.
 *
 * @param[in] flags is used to filter types of logging. Type is uint8_t[8].
 * Can be set using the hsa_flag_set64 macro. Setting @p flags to 0 will disable logging.
 * @param[in] file file stream to output logging. If file is NULL, prints are sent to stderr.
 *
 * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 *
 * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 * initialized.
 */
hsa_status_t hsa_amd_enable_logging(uint8_t* flags, void* file);

/** @} */

#ifdef __cplusplus
}  // end extern "C" block
#endif

#endif  // header guard