include/hsa_ext_amd.h

   1 ////////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright (C) 2014-2020 Advanced Micro Devices Inc.  All rights reserved.
   4 //
   5 // Permission is hereby granted, free of charge, to any person or organization
   6 // obtaining a copy of the software and accompanying documentation covered by
   7 // this license (the "Software") to use, reproduce, display, distribute,
   8 // execute, and transmit the Software, and to prepare derivative works of the
   9 // Software, and to permit third-parties to whom the Software is furnished to
  10 // do so, all subject to the following:
  11 //
  12 // The copyright notices in the Software and this entire statement, including
  13 // the above license grant, this restriction and the following disclaimer,
  14 // must be included in all copies of the Software, in whole or in part, and
  15 // all derivative works of the Software, unless such copies or derivative
  16 // works are solely in the form of machine-executable object code generated by
  17 // a source language processor.
  18 //
  19 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
  22 // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
  23 // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
  24 // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  25 // DEALINGS IN THE SOFTWARE.
  26 //
  27 ////////////////////////////////////////////////////////////////////////////////
  28
  29 // HSA AMD extension.
  30
  31 #ifndef HSA_RUNTIME_EXT_AMD_H_
  32 #define HSA_RUNTIME_EXT_AMD_H_
  33
  34 #include "hsa.h"
  35 #include "hsa_ext_image.h"
  36
  37 #define HSA_AMD_INTERFACE_VERSION_MAJOR 1
  38 #define HSA_AMD_INTERFACE_VERSION_MINOR 0
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /**
  45  * @brief Enumeration constants added to ::hsa_status_t.
  46  *
  47  * @remark Additions to hsa_status_t
  48  */
  49 enum {
  50   /**
  51    * The memory pool is invalid.
  52    */
  53   HSA_STATUS_ERROR_INVALID_MEMORY_POOL = 40,
  54
  55   /**
  56    * Agent accessed memory beyond the maximum legal address.
  57    */
  58   HSA_STATUS_ERROR_MEMORY_APERTURE_VIOLATION = 41,
  59
  60   /**
  61    * Agent executed an invalid shader instruction.
  62    */
  63   HSA_STATUS_ERROR_ILLEGAL_INSTRUCTION = 42,
  64 };
  65
  66 /**
  67  * @brief Agent attributes.
  68  */
  69 typedef enum hsa_amd_agent_info_s {
  70   /**
  71    * Chip identifier. The type of this attribute is uint32_t.
  72    */
  73   HSA_AMD_AGENT_INFO_CHIP_ID = 0xA000,
  74   /**
  75    * Size of a cacheline in bytes. The type of this attribute is uint32_t.
  76    */
  77   HSA_AMD_AGENT_INFO_CACHELINE_SIZE = 0xA001,
  78   /**
  79    * The number of compute unit available in the agent. The type of this
  80    * attribute is uint32_t.
  81    */
  82   HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT = 0xA002,
  83   /**
  84    * The maximum clock frequency of the agent in MHz. The type of this
  85    * attribute is uint32_t.
  86    */
  87   HSA_AMD_AGENT_INFO_MAX_CLOCK_FREQUENCY = 0xA003,
  88   /**
  89    * Internal driver node identifier. The type of this attribute is uint32_t.
  90    */
  91   HSA_AMD_AGENT_INFO_DRIVER_NODE_ID = 0xA004,
  92   /**
  93    * Max number of watch points on memory address ranges to generate exception
  94    * events when the watched addresses are accessed.  The type of this
  95    * attribute is uint32_t.
  96    */
  97   HSA_AMD_AGENT_INFO_MAX_ADDRESS_WATCH_POINTS = 0xA005,
  98   /**
  99    * Agent BDF_ID, named LocationID in thunk. The type of this attribute is
 100    * uint32_t.
 101    */
 102   HSA_AMD_AGENT_INFO_BDFID = 0xA006,
 103   /**
 104    * Memory Interface width, the return value type is uint32_t.
 105    * This attribute is deprecated.
 106    */
 107   HSA_AMD_AGENT_INFO_MEMORY_WIDTH = 0xA007,
 108   /**
 109    * Max Memory Clock, the return value type is uint32_t.
 110    */
 111   HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY = 0xA008,
 112   /**
 113    * Board name of Agent - populated from MarketingName of Kfd Node
 114    * The value is an Ascii string of 64 chars.
 115    */
 116   HSA_AMD_AGENT_INFO_PRODUCT_NAME = 0xA009,
 117   /**
 118    * Maximum number of waves possible in a Compute Unit.
 119    * The type of this attribute is uint32_t.
 120    */
 121   HSA_AMD_AGENT_INFO_MAX_WAVES_PER_CU = 0xA00A,
 122   /**
 123    * Number of SIMD's per compute unit CU
 124    * The type of this attribute is uint32_t.
 125    */
 126   HSA_AMD_AGENT_INFO_NUM_SIMDS_PER_CU = 0xA00B,
 127   /**
 128    * Number of Shader Engines (SE) in Gpu
 129    * The type of this attribute is uint32_t.
 130    */
 131   HSA_AMD_AGENT_INFO_NUM_SHADER_ENGINES = 0xA00C,
 132   /**
 133    * Number of Shader Arrays Per Shader Engines in Gpu
 134    * The type of this attribute is uint32_t.
 135    */
 136   HSA_AMD_AGENT_INFO_NUM_SHADER_ARRAYS_PER_SE = 0xA00D,
 137   /**
 138    * Address of the HDP flush registers.  Use of these registers does not conform to the HSA memory
 139    * model and should be treated with caution.
 140    * The type of this attribute is hsa_amd_hdp_flush_t.
 141    */
 142   HSA_AMD_AGENT_INFO_HDP_FLUSH = 0xA00E,
 143   /**
 144    * PCIe domain for the agent.  Pairs with HSA_AMD_AGENT_INFO_BDFID
 145    * to give the full physical location of the Agent.
 146    * The type of this attribute is uint32_t.
 147    */
 148   HSA_AMD_AGENT_INFO_DOMAIN = 0xA00F,
 149   /**
 150    * Queries for support of cooperative queues.  See ::HSA_QUEUE_TYPE_COOPERATIVE.
 151    * The type of this attribute is bool.
 152    */
 153   HSA_AMD_AGENT_INFO_COOPERATIVE_QUEUES = 0xA010,
 154   /**
 155    * Queries UUID of an agent. The value is an Ascii string with a maximum
 156    * of 21 chars including NUL. The string value consists of two parts: header
 157    * and body. The header identifies device type (GPU, CPU, DSP) while body
 158    * encodes UUID as a 16 digit hex string
 159    *
 160    * Agents that do not support UUID will return the string "GPU-XX" or
 161    * "CPU-XX" or "DSP-XX" depending upon their device type ::hsa_device_type_t
 162    */
 163   HSA_AMD_AGENT_INFO_UUID = 0xA011,
 164   /**
 165    * Queries for the ASIC revision of an agent. The value is an integer that
 166    * increments for each revision. This can be used by user-level software to
 167    * change how it operates, depending on the hardware version. This allows
 168    * selective workarounds for hardware errata.
 169    * The type of this attribute is uint32_t.
 170    */
 171   HSA_AMD_AGENT_INFO_ASIC_REVISION = 0xA012
 172 } hsa_amd_agent_info_t;
 173
 174 typedef struct hsa_amd_hdp_flush_s {
 175   uint32_t* HDP_MEM_FLUSH_CNTL;
 176   uint32_t* HDP_REG_FLUSH_CNTL;
 177 } hsa_amd_hdp_flush_t;
 178
 179 /**
 180  * @brief Region attributes.
 181  */
 182 typedef enum hsa_amd_region_info_s {
 183   /**
 184    * Determine if host can access the region. The type of this attribute
 185    * is bool.
 186    */
 187   HSA_AMD_REGION_INFO_HOST_ACCESSIBLE = 0xA000,
 188   /**
 189    * Base address of the region in flat address space.
 190    */
 191   HSA_AMD_REGION_INFO_BASE = 0xA001,
 192   /**
 193    * Memory Interface width, the return value type is uint32_t.
 194    * This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_WIDTH.
 195    */
 196   HSA_AMD_REGION_INFO_BUS_WIDTH = 0xA002,
 197   /**
 198    * Max Memory Clock, the return value type is uint32_t.
 199    * This attribute is deprecated. Use HSA_AMD_AGENT_INFO_MEMORY_MAX_FREQUENCY.
 200    */
 201   HSA_AMD_REGION_INFO_MAX_CLOCK_FREQUENCY = 0xA003
 202 } hsa_amd_region_info_t;
 203
 204 /**
 205  * @brief Coherency attributes of fine grain region.
 206  */
 207 typedef enum hsa_amd_coherency_type_s {
 208   /**
 209    * Coherent region.
 210    */
 211   HSA_AMD_COHERENCY_TYPE_COHERENT = 0,
 212   /**
 213    * Non coherent region.
 214    */
 215   HSA_AMD_COHERENCY_TYPE_NONCOHERENT = 1
 216 } hsa_amd_coherency_type_t;
 217
 218 /**
 219  * @brief Get the coherency type of the fine grain region of an agent.
 220  *
 221  * @param[in] agent A valid agent.
 222  *
 223  * @param[out] type Pointer to a memory location where the HSA runtime will
 224  * store the coherency type of the fine grain region.
 225  *
 226  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 227  *
 228  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 229  * initialized.
 230  *
 231  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 232  *
 233  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p type is NULL.
 234  */
 235 hsa_status_t HSA_API hsa_amd_coherency_get_type(hsa_agent_t agent,
 236                                                 hsa_amd_coherency_type_t* type);
 237
 238 /**
 239  * @brief Set the coherency type of the fine grain region of an agent.
 240  * Deprecated.  This is supported on KV platforms.  For backward compatibility
 241  * other platforms will spuriously succeed.
 242  *
 243  * @param[in] agent A valid agent.
 244  *
 245  * @param[in] type The coherency type to be set.
 246  *
 247  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 248  *
 249  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 250  * initialized.
 251  *
 252  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 253  *
 254  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p type is invalid.
 255  */
 256 hsa_status_t HSA_API hsa_amd_coherency_set_type(hsa_agent_t agent,
 257                                                 hsa_amd_coherency_type_t type);
 258
 259 /**
 260  * @brief Structure containing profiling dispatch time information.
 261  *
 262  * Times are reported as ticks in the domain of the HSA system clock.
 263  * The HSA system clock tick and frequency is obtained via hsa_system_get_info.
 264  */
 265 typedef struct hsa_amd_profiling_dispatch_time_s {
 266   /**
 267    * Dispatch packet processing start time.
 268    */
 269   uint64_t start;
 270   /**
 271    * Dispatch packet completion time.
 272    */
 273   uint64_t end;
 274 } hsa_amd_profiling_dispatch_time_t;
 275
 276 /**
 277  * @brief Structure containing profiling async copy time information.
 278  *
 279  * Times are reported as ticks in the domain of the HSA system clock.
 280  * The HSA system clock tick and frequency is obtained via hsa_system_get_info.
 281  */
 282 typedef struct hsa_amd_profiling_async_copy_time_s {
 283   /**
 284    * Async copy processing start time.
 285    */
 286   uint64_t start;
 287   /**
 288    * Async copy completion time.
 289    */
 290   uint64_t end;
 291 } hsa_amd_profiling_async_copy_time_t;
 292
 293 /**
 294  * @brief Enable or disable profiling capability of a queue.
 295  *
 296  * @param[in] queue A valid queue.
 297  *
 298  * @param[in] enable 1 to enable profiling. 0 to disable profiling.
 299  *
 300  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 301  *
 302  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 303  * initialized.
 304  *
 305  * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE The queue is invalid.
 306  *
 307  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p queue is NULL.
 308  */
 309 hsa_status_t HSA_API
 310     hsa_amd_profiling_set_profiler_enabled(hsa_queue_t* queue, int enable);
 311
 312 /**
 313  * @brief Enable or disable asynchronous memory copy profiling.
 314  *
 315  * @details The runtime will provide the copy processing start timestamp and
 316  * completion timestamp of each call to hsa_amd_memory_async_copy if the
 317  * async copy profiling is enabled prior to the call to
 318  * hsa_amd_memory_async_copy. The completion signal object is used to
 319  * hold the last async copy start and end timestamp. The client can retrieve
 320  * these timestamps via call to hsa_amd_profiling_get_async_copy_time.
 321  *
 322  * @param[in] enable True to enable profiling. False to disable profiling.
 323  *
 324  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 325  *
 326  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 327  * initialized.
 328  *
 329  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES Failed on allocating resources
 330  * needed to profile the asynchronous copy.
 331  */
 332 hsa_status_t HSA_API
 333     hsa_amd_profiling_async_copy_enable(bool enable);
 334
 335 /**
 336  * @brief Retrieve packet processing time stamps.
 337  *
 338  * @param[in] agent The agent with which the signal was last used.  For
 339  * instance, if the profiled dispatch packet is dispatched onto queue Q,
 340  * which was created on agent A, then this parameter must be A.
 341  *
 342  * @param[in] signal A signal used as the completion signal of the dispatch
 343  * packet to retrieve time stamps from.  This dispatch packet must have been
 344  * issued to a queue with profiling enabled and have already completed.  Also
 345  * the signal must not have yet been used in any other packet following the
 346  * completion of the profiled dispatch packet.
 347  *
 348  * @param[out] time Packet processing timestamps in the HSA system clock
 349  * domain.
 350  *
 351  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 352  *
 353  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 354  * initialized.
 355  *
 356  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 357  *
 358  * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL The signal is invalid.
 359  *
 360  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p time is NULL.
 361  */
 362 hsa_status_t HSA_API hsa_amd_profiling_get_dispatch_time(
 363     hsa_agent_t agent, hsa_signal_t signal,
 364     hsa_amd_profiling_dispatch_time_t* time);
 365
 366 /**
 367  * @brief Retrieve asynchronous copy timestamps.
 368  *
 369  * @details Async copy profiling is enabled via call to
 370  * hsa_amd_profiling_async_copy_enable.
 371  *
 372  * @param[in] signal A signal used as the completion signal of the call to
 373  * hsa_amd_memory_async_copy.
 374  *
 375  * @param[out] time Async copy processing timestamps in the HSA system clock
 376  * domain.
 377  *
 378  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 379  *
 380  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 381  * initialized.
 382  *
 383  * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL The signal is invalid.
 384  *
 385  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p time is NULL.
 386  */
 387 hsa_status_t HSA_API hsa_amd_profiling_get_async_copy_time(
 388     hsa_signal_t signal, hsa_amd_profiling_async_copy_time_t* time);
 389
 390 /**
 391  * @brief Computes the frequency ratio and offset between the agent clock and
 392  * HSA system clock and converts the agent's tick to HSA system domain tick.
 393  *
 394  * @param[in] agent The agent used to retrieve the agent_tick. It is user's
 395  * responsibility to make sure the tick number is from this agent, otherwise,
 396  * the behavior is undefined.
 397  *
 398  * @param[in] agent_tick The tick count retrieved from the specified @p agent.
 399  *
 400  * @param[out] system_tick The translated HSA system domain clock counter tick.
 401  *
 402  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 403  *
 404  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 405  * initialized.
 406  *
 407  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 408  *
 409  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p system_tick is NULL;
 410  */
 411 hsa_status_t HSA_API
 412     hsa_amd_profiling_convert_tick_to_system_domain(hsa_agent_t agent,
 413                                                     uint64_t agent_tick,
 414                                                     uint64_t* system_tick);
 415
 416 /**
 417  * @brief Signal attribute flags.
 418  */
 419 typedef enum {
 420   /**
 421    * Signal will only be consumed by AMD GPUs.  Limits signal consumption to
 422    * AMD GPU agents only.  Ignored if @p num_consumers is not zero (all agents).
 423    */
 424   HSA_AMD_SIGNAL_AMD_GPU_ONLY = 1,
 425   /**
 426    * Signal may be used for interprocess communication.
 427    * IPC signals can be read, written, and waited on from any process.
 428    * Profiling using an IPC enabled signal is only supported in a single process
 429    * at a time.  Producing profiling data in one process and consuming it in
 430    * another process is undefined.
 431    */
 432   HSA_AMD_SIGNAL_IPC = 2,
 433 } hsa_amd_signal_attribute_t;
 434
 435 /**
 436  * @brief Create a signal with specific attributes.
 437  *
 438  * @param[in] initial_value Initial value of the signal.
 439  *
 440  * @param[in] num_consumers Size of @p consumers. A value of 0 indicates that
 441  * any agent might wait on the signal.
 442  *
 443  * @param[in] consumers List of agents that might consume (wait on) the
 444  * signal. If @p num_consumers is 0, this argument is ignored; otherwise, the
 445  * HSA runtime might use the list to optimize the handling of the signal
 446  * object. If an agent not listed in @p consumers waits on the returned
 447  * signal, the behavior is undefined. The memory associated with @p consumers
 448  * can be reused or freed after the function returns.
 449  *
 450  * @param[in] attributes Requested signal attributes.  Multiple signal attributes
 451  * may be requested by combining them with bitwise OR.  Requesting no attributes
 452  * (@p attributes == 0) results in the same signal as would have been obtained
 453  * via hsa_signal_create.
 454  *
 455  * @param[out] signal Pointer to a memory location where the HSA runtime will
 456  * store the newly created signal handle. Must not be NULL.
 457  *
 458  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 459  *
 460  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 461  * initialized.
 462  *
 463  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime failed to allocate
 464  * the required resources.
 465  *
 466  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p signal is NULL, @p
 467  * num_consumers is greater than 0 but @p consumers is NULL, or @p consumers
 468  * contains duplicates.
 469  */
 470 hsa_status_t HSA_API hsa_amd_signal_create(hsa_signal_value_t initial_value, uint32_t num_consumers,
 471                                            const hsa_agent_t* consumers, uint64_t attributes,
 472                                            hsa_signal_t* signal);
 473
 474 /**
 475  * @brief Asyncronous signal handler function type.
 476  *
 477  * @details Type definition of callback function to be used with
 478  * hsa_amd_signal_async_handler. This callback is invoked if the associated
 479  * signal and condition are met. The callback receives the value of the signal
 480  * which satisfied the associated wait condition and a user provided value. If
 481  * the callback returns true then the callback will be called again if the
 482  * associated signal and condition are satisfied again. If the callback returns
 483  * false then it will not be called again.
 484  *
 485  * @param[in] value Contains the value of the signal observed by
 486  * hsa_amd_signal_async_handler which caused the signal handler to be invoked.
 487  *
 488  * @param[in] arg Contains the user provided value given when the signal handler
 489  * was registered with hsa_amd_signal_async_handler
 490  *
 491  * @retval true resumes monitoring the signal with this handler (as if calling
 492  * hsa_amd_signal_async_handler again with identical parameters)
 493  *
 494  * @retval false stops monitoring the signal with this handler (handler will
 495  * not be called again for this signal)
 496  *
 497  */
 498 typedef bool (*hsa_amd_signal_handler)(hsa_signal_value_t value, void* arg);
 499
 500 /**
 501  * @brief Register asynchronous signal handler function.
 502  *
 503  * @details Allows registering a callback function and user provided value with
 504  * a signal and wait condition. The callback will be invoked if the associated
 505  * signal and wait condition are satisfied. Callbacks will be invoked serially
 506  * but in an arbitrary order so callbacks should be independent of each other.
 507  * After being invoked a callback may continue to wait for its associated signal
 508  * and condition and, possibly, be invoked again. Or the callback may stop
 509  * waiting. If the callback returns true then it will continue waiting and may
 510  * be called again. If false then the callback will not wait again and will not
 511  * be called again for the associated signal and condition. It is possible to
 512  * register the same callback multiple times with the same or different signals
 513  * and/or conditions. Each registration of the callback will be treated entirely
 514  * independently.
 515  *
 516  * @param[in] signal hsa signal to be asynchronously monitored
 517  *
 518  * @param[in] cond condition value to monitor for
 519  *
 520  * @param[in] value signal value used in condition expression
 521  *
 522  * @param[in] handler asynchronous signal handler invoked when signal's
 523  * condition is met
 524  *
 525  * @param[in] arg user provided value which is provided to handler when handler
 526  * is invoked
 527  *
 528  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 529  *
 530  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 531  * initialized.
 532  *
 533  * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL signal is not a valid hsa_signal_t
 534  *
 535  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT handler is invalid (NULL)
 536  *
 537  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime is out of
 538  * resources or blocking signals are not supported by the HSA driver component.
 539  *
 540  */
 541 hsa_status_t HSA_API
 542     hsa_amd_signal_async_handler(hsa_signal_t signal,
 543                                  hsa_signal_condition_t cond,
 544                                  hsa_signal_value_t value,
 545                                  hsa_amd_signal_handler handler, void* arg);
 546
 547 /**
 548  * @brief Call a function asynchronously
 549  *
 550  * @details Provides access to the runtime's asynchronous event handling thread
 551  * for general asynchronous functions.  Functions queued this way are executed
 552  * in the same manner as if they were a signal handler who's signal is
 553  * satisfied.
 554  *
 555  * @param[in] callback asynchronous function to be invoked
 556  *
 557  * @param[in] arg user provided value which is provided to handler when handler
 558  * is invoked
 559  *
 560  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 561  *
 562  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 563  * initialized.
 564  *
 565  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT handler is invalid (NULL)
 566  *
 567  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES The HSA runtime is out of
 568  * resources or blocking signals are not supported by the HSA driver component.
 569  *
 570  */
 571 hsa_status_t HSA_API
 572     hsa_amd_async_function(void (*callback)(void* arg), void* arg);
 573
 574 /**
 575  * @brief Wait for any signal-condition pair to be satisfied.
 576  *
 577  * @details Allows waiting for any of several signal and conditions pairs to be
 578  * satisfied. The function returns the index into the list of signals of the
 579  * first satisfying signal-condition pair. The value of the satisfying signal's
 580  * value is returned in satisfying_value unless satisfying_value is NULL. This
 581  * function provides only relaxed memory semantics.
 582  */
 583 uint32_t HSA_API
 584     hsa_amd_signal_wait_any(uint32_t signal_count, hsa_signal_t* signals,
 585                             hsa_signal_condition_t* conds,
 586                             hsa_signal_value_t* values, uint64_t timeout_hint,
 587                             hsa_wait_state_t wait_hint,
 588                             hsa_signal_value_t* satisfying_value);
 589
 590 /**
 591  * @brief Query image limits.
 592  *
 593  * @param[in] agent A valid agent.
 594  *
 595  * @param[in] attribute HSA image info attribute to query.
 596  *
 597  * @param[out] value Pointer to an application-allocated buffer where to store
 598  * the value of the attribute. If the buffer passed by the application is not
 599  * large enough to hold the value of @p attribute, the behavior is undefined.
 600  *
 601  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 602  *
 603  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 604  * initialized.
 605  *
 606  * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE @p value is NULL or @p attribute <
 607  * HSA_EXT_AGENT_INFO_IMAGE_1D_MAX_ELEMENTS or @p attribute >
 608  * HSA_EXT_AGENT_INFO_IMAGE_ARRAY_MAX_LAYERS.
 609  *
 610  */
 611 hsa_status_t HSA_API hsa_amd_image_get_info_max_dim(hsa_agent_t agent,
 612                                                     hsa_agent_info_t attribute,
 613                                                     void* value);
 614
 615 /**
 616  * @brief Set a CU affinity to specific queues within the process, this function
 617  * call is "atomic".
 618  *
 619  * @param[in] queue A pointer to HSA queue.
 620  *
 621  * @param[in] num_cu_mask_count Size of CUMask bit array passed in.
 622  *
 623  * @param[in] cu_mask Bit-vector representing the CU mask.
 624  *
 625  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 626  *
 627  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 628  * initialized.
 629  *
 630  * @retval ::HSA_STATUS_ERROR_INVALID_QUEUE @p queue is NULL or invalid.
 631  *
 632  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p num_cu_mask_count is not
 633  * multiple of 32 or @p cu_mask is NULL.
 634  *
 635  * @retval ::HSA_STATUS_ERROR failed to call thunk api
 636  *
 637  */
 638 hsa_status_t HSA_API hsa_amd_queue_cu_set_mask(const hsa_queue_t* queue,
 639                                                uint32_t num_cu_mask_count,
 640                                                const uint32_t* cu_mask);
 641
 642 /**
 643  * @brief Memory segments associated with a memory pool.
 644  */
 645 typedef enum {
 646   /**
 647    * Global segment. Used to hold data that is shared by all agents.
 648    */
 649   HSA_AMD_SEGMENT_GLOBAL = 0,
 650   /**
 651    * Read-only segment. Used to hold data that remains constant during the
 652    * execution of a kernel.
 653    */
 654   HSA_AMD_SEGMENT_READONLY = 1,
 655   /**
 656    * Private segment. Used to hold data that is local to a single work-item.
 657    */
 658   HSA_AMD_SEGMENT_PRIVATE = 2,
 659   /**
 660    * Group segment. Used to hold data that is shared by the work-items of a
 661    * work-group.
 662    */
 663   HSA_AMD_SEGMENT_GROUP = 3,
 664 } hsa_amd_segment_t;
 665
 666 /**
 667  * @brief A memory pool encapsulates physical storage on an agent
 668  * along with a memory access model.
 669  *
 670  * @details A memory pool encapsulates a physical partition of an agent's
 671  * memory system along with a memory access model.  Division of a single
 672  * memory system into separate pools allows querying each partition's access
 673  * path properties (see ::hsa_amd_agent_memory_pool_get_info). Allocations
 674  * from a pool are preferentially bound to that pool's physical partition.
 675  * Binding to the pool's preferential physical partition may not be
 676  * possible or persistent depending on the system's memory policy
 677  * and/or state which is beyond the scope of HSA APIs.
 678  *
 679  * For example, a multi-node NUMA memory system may be represented by multiple
 680  * pool's with each pool providing size and access path information for the
 681  * partition it represents.  Allocations from a pool are preferentially bound
 682  * to the pool's partition (which in this example is a NUMA node) while
 683  * following its memory access model. The actual placement may vary or migrate
 684  * due to the system's NUMA policy and state, which is beyond the scope of
 685  * HSA APIs.
 686  */
 687 typedef struct hsa_amd_memory_pool_s {
 688   /**
 689    * Opaque handle.
 690    */
 691   uint64_t handle;
 692 } hsa_amd_memory_pool_t;
 693
 694 typedef enum hsa_amd_memory_pool_global_flag_s {
 695   /**
 696    * The application can use allocations in the memory pool to store kernel
 697    * arguments, and provide the values for the kernarg segment of
 698    * a kernel dispatch.
 699    */
 700   HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_KERNARG_INIT = 1,
 701   /**
 702    * Updates to memory in this pool conform to HSA memory consistency model.
 703    * If this flag is set, then ::HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED
 704    * must not be set.
 705    */
 706   HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_FINE_GRAINED = 2,
 707   /**
 708    * Writes to memory in this pool can be performed by a single agent at a time.
 709    */
 710   HSA_AMD_MEMORY_POOL_GLOBAL_FLAG_COARSE_GRAINED = 4
 711 } hsa_amd_memory_pool_global_flag_t;
 712
 713 /**
 714  * @brief Memory pool features.
 715  */
 716 typedef enum {
 717   /**
 718   * Segment where the memory pool resides. The type of this attribute is
 719   * ::hsa_amd_segment_t.
 720   */
 721   HSA_AMD_MEMORY_POOL_INFO_SEGMENT = 0,
 722   /**
 723   * Flag mask. The value of this attribute is undefined if the value of
 724   * ::HSA_AMD_MEMORY_POOL_INFO_SEGMENT is not ::HSA_AMD_SEGMENT_GLOBAL. The type
 725   * of
 726   * this attribute is uint32_t, a bit-field of
 727   * ::hsa_amd_memory_pool_global_flag_t
 728   * values.
 729   */
 730   HSA_AMD_MEMORY_POOL_INFO_GLOBAL_FLAGS = 1,
 731   /**
 732   * Size of this pool, in bytes. The type of this attribute is size_t.
 733   */
 734   HSA_AMD_MEMORY_POOL_INFO_SIZE = 2,
 735   /**
 736   * Indicates whether memory in this pool can be allocated using
 737   * ::hsa_amd_memory_pool_allocate. The type of this attribute is bool.
 738   *
 739   * The value of this flag is always false for memory pools in the group and
 740   * private segments.
 741   */
 742   HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED = 5,
 743   /**
 744   * Allocation granularity of buffers allocated by
 745   * ::hsa_amd_memory_pool_allocate
 746   * in this memory pool. The size of a buffer allocated in this pool is a
 747   * multiple of the value of this attribute. The value of this attribute is
 748   * only defined if ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for
 749   * this pool. The type of this attribute is size_t.
 750   */
 751   HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE = 6,
 752   /**
 753   * Alignment of buffers allocated by ::hsa_amd_memory_pool_allocate in this
 754   * pool. The value of this attribute is only defined if
 755   * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED is true for this pool, and
 756   * must be a power of 2. The type of this attribute is size_t.
 757   */
 758   HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT = 7,
 759   /**
 760   * This memory_pool can be made directly accessible by all the agents in the
 761   * system (::hsa_amd_agent_memory_pool_get_info does not return
 762   * ::HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED for any agent). The type of this
 763   * attribute is bool.
 764   */
 765   HSA_AMD_MEMORY_POOL_INFO_ACCESSIBLE_BY_ALL = 15,
 766   /**
 767   * Maximum aggregate allocation size in bytes. The type of this attribute
 768   * is size_t.
 769   */
 770   HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE = 16,
 771 } hsa_amd_memory_pool_info_t;
 772
 773 /**
 774  * @brief Get the current value of an attribute of a memory pool.
 775  *
 776  * @param[in] memory_pool A valid memory pool.
 777  *
 778  * @param[in] attribute Attribute to query.
 779  *
 780  * @param[out] value Pointer to a application-allocated buffer where to store
 781  * the value of the attribute. If the buffer passed by the application is not
 782  * large enough to hold the value of @p attribute, the behavior is undefined.
 783  *
 784  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 785  *
 786  */
 787 hsa_status_t HSA_API
 788     hsa_amd_memory_pool_get_info(hsa_amd_memory_pool_t memory_pool,
 789                                  hsa_amd_memory_pool_info_t attribute,
 790                                  void* value);
 791
 792 /**
 793  * @brief Iterate over the memory pools associated with a given agent, and
 794  * invoke an application-defined callback on every iteration.
 795  *
 796  * @details An agent can directly access buffers located in some memory pool, or
 797  * be enabled to access them by the application (see ::hsa_amd_agents_allow_access),
 798  * yet that memory pool may not be returned by this function for that given
 799  * agent.
 800  *
 801  * A memory pool of fine-grained type must be associated only with the host.
 802  *
 803  * @param[in] agent A valid agent.
 804  *
 805  * @param[in] callback Callback to be invoked on the same thread that called
 806  * ::hsa_amd_agent_iterate_memory_pools, serially, once per memory pool that is
 807  * associated with the agent.  The HSA runtime passes two arguments to the
 808  * callback: the memory pool, and the application data.  If @p callback
 809  * returns a status other than ::HSA_STATUS_SUCCESS for a particular iteration,
 810  * the traversal stops and ::hsa_amd_agent_iterate_memory_pools returns that status
 811  * value.
 812  *
 813  * @param[in] data Application data that is passed to @p callback on every
 814  * iteration. May be NULL.
 815  *
 816  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 817  *
 818  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 819  * initialized.
 820  *
 821  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 822  *
 823  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p callback is NULL.
 824  */
 825 hsa_status_t HSA_API hsa_amd_agent_iterate_memory_pools(
 826     hsa_agent_t agent,
 827     hsa_status_t (*callback)(hsa_amd_memory_pool_t memory_pool, void* data),
 828     void* data);
 829
 830 /**
 831  * @brief Allocate a block of memory (or buffer) in the specified pool.
 832  *
 833  * @param[in] memory_pool Memory pool where to allocate memory from. The memory
 834  * pool must have the ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALLOWED flag set.
 835  *
 836  * @param[in] size Allocation size, in bytes. Must not be zero. This value is
 837  * rounded up to the nearest multiple of
 838  * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_GRANULE in @p memory_pool.
 839  *
 840  * @param[in] flags A bit-field that is used to specify allocation
 841  * directives. Reserved parameter, must be 0.
 842  *
 843  * @param[out] ptr Pointer to the location where to store the base virtual
 844  * address of
 845  * the allocated block. The returned base address is aligned to the value of
 846  * ::HSA_AMD_MEMORY_POOL_INFO_RUNTIME_ALLOC_ALIGNMENT in @p memory_pool. If the
 847  * allocation fails, the returned value is undefined.
 848  *
 849  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 850  *
 851  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 852  * initialized.
 853  *
 854  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES No memory is available.
 855  *
 856  * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL The memory pool is invalid.
 857  *
 858  * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION The host is not allowed to
 859  * allocate memory in @p memory_pool, or @p size is greater than
 860  * the value of HSA_AMD_MEMORY_POOL_INFO_ALLOC_MAX_SIZE in @p memory_pool.
 861  *
 862  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr is NULL, or @p size is 0,
 863  * or flags is not 0.
 864  *
 865  */
 866 hsa_status_t HSA_API
 867     hsa_amd_memory_pool_allocate(hsa_amd_memory_pool_t memory_pool, size_t size,
 868                                  uint32_t flags, void** ptr);
 869
 870 /**
 871  * @brief Deallocate a block of memory previously allocated using
 872  * ::hsa_amd_memory_pool_allocate.
 873  *
 874  * @param[in] ptr Pointer to a memory block. If @p ptr does not match a value
 875  * previously returned by ::hsa_amd_memory_pool_allocate, the behavior is undefined.
 876  *
 877  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
 878  *
 879  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 880  * initialized.
 881  *
 882  */
 883 hsa_status_t HSA_API hsa_amd_memory_pool_free(void* ptr);
 884
 885 /**
 886  * @brief Asynchronously copy a block of memory from the location pointed to by
 887  * @p src on the @p src_agent to the memory block pointed to by @p dst on the @p
 888  * dst_agent.
 889  * Because the DMA engines used may not be in the same coherency domain, the caller must ensure
 890  * that buffers are system-level coherent. In general this requires the sending device to have
 891  * released the buffer to system scope prior to executing the copy API and the receiving device
 892  * must execute a system scope acquire fence prior to use of the destination buffer.
 893  *
 894  * @param[out] dst Buffer where the content is to be copied.
 895  *
 896  * @param[in] dst_agent Agent associated with the @p dst. The agent must be able to directly
 897  * access both the source and destination buffers in their current locations.
 898  *
 899  * @param[in] src A valid pointer to the source of data to be copied. The source
 900  * buffer must not overlap with the destination buffer, otherwise the copy will succeed
 901  * but contents of @p dst is undefined.
 902  *
 903  * @param[in] src_agent Agent associated with the @p src. The agent must be able to directly
 904  * access both the source and destination buffers in their current locations.
 905  *
 906  * @param[in] size Number of bytes to copy. If @p size is 0, no copy is
 907  * performed and the function returns success. Copying a number of bytes larger
 908  * than the size of the buffers pointed by @p dst or @p src results in undefined
 909  * behavior.
 910  *
 911  * @param[in] num_dep_signals Number of dependent signals. Can be 0.
 912  *
 913  * @param[in] dep_signals List of signals that must be waited on before the copy
 914  * operation starts. The copy will start after every signal has been observed with
 915  * the value 0. The dependent signal should not include completion signal from hsa_amd_memory_async_copy
 916  * operation to be issued in future as that can result in a deadlock. If @p num_dep_signals is 0, this
 917  * argument is ignored.
 918  *
 919  * @param[in] completion_signal Signal used to indicate completion of the copy
 920  * operation. When the copy operation is finished, the value of the signal is
 921  * decremented. The runtime indicates that an error has occurred during the copy
 922  * operation by setting the value of the completion signal to a negative
 923  * number. The signal handle must not be 0.
 924  *
 925  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully. The
 926  * application is responsible for checking for asynchronous error conditions
 927  * (see the description of @p completion_signal).
 928  *
 929  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
 930  * initialized.
 931  *
 932  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT The agent is invalid.
 933  *
 934  * @retval ::HSA_STATUS_ERROR_INVALID_SIGNAL @p completion_signal is invalid.
 935  *
 936  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The source or destination
 937  * pointers are NULL, or the completion signal is 0.
 938  */
 939 hsa_status_t HSA_API
 940     hsa_amd_memory_async_copy(void* dst, hsa_agent_t dst_agent, const void* src,
 941                               hsa_agent_t src_agent, size_t size,
 942                               uint32_t num_dep_signals,
 943                               const hsa_signal_t* dep_signals,
 944                               hsa_signal_t completion_signal);
 945
 946 /*
 947 [Provisional API]
 948 Pitched memory descriptor.
 949 All elements must be 4 byte aligned.  Pitch and slice are in bytes.
 950 */
 951 typedef struct hsa_pitched_ptr_s {
 952   void* base;
 953   size_t pitch;
 954   size_t slice;
 955 } hsa_pitched_ptr_t;
 956
 957 /*
 958 [Provisional API]
 959 Copy direction flag.
 960 */
 961 typedef enum {
 962   hsaHostToHost = 0,
 963   hsaHostToDevice = 1,
 964   hsaDeviceToHost = 2,
 965   hsaDeviceToDevice = 3
 966 } hsa_amd_copy_direction_t;
 967
 968 /*
 969 [Provisional API]
 970 SDMA 3D memory copy API.  The same requirements must be met by src and dst as in
 971 hsa_amd_memory_async_copy.
 972 Both src and dst must be directly accessible to the copy_agent during the copy, src and dst rects
 973 must not overlap.
 974 CPU agents are not supported.  API requires SDMA and will return an error if SDMA is not available.
 975 Offsets and range carry x in bytes, y and z in rows and layers.
 976 */
 977 hsa_status_t HSA_API hsa_amd_memory_async_copy_rect(
 978     const hsa_pitched_ptr_t* dst, const hsa_dim3_t* dst_offset, const hsa_pitched_ptr_t* src,
 979     const hsa_dim3_t* src_offset, const hsa_dim3_t* range, hsa_agent_t copy_agent,
 980     hsa_amd_copy_direction_t dir, uint32_t num_dep_signals, const hsa_signal_t* dep_signals,
 981     hsa_signal_t completion_signal);
 982
 983 /**
 984  * @brief Type of accesses to a memory pool from a given agent.
 985  */
 986 typedef enum {
 987   /**
 988   * The agent cannot directly access any buffer in the memory pool.
 989   */
 990   HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED = 0,
 991   /**
 992   * The agent can directly access a buffer located in the pool; the application
 993   * does not need to invoke ::hsa_amd_agents_allow_access.
 994   */
 995   HSA_AMD_MEMORY_POOL_ACCESS_ALLOWED_BY_DEFAULT = 1,
 996   /**
 997   * The agent can directly access a buffer located in the pool, but only if the
 998   * application has previously requested access to that buffer using
 999   * ::hsa_amd_agents_allow_access.
1000   */
1001   HSA_AMD_MEMORY_POOL_ACCESS_DISALLOWED_BY_DEFAULT = 2
1002 } hsa_amd_memory_pool_access_t;
1003
1004 /**
1005  * @brief Properties of the relationship between an agent a memory pool.
1006  */
1007 typedef enum {
1008   /**
1009   * Hyper-transport bus type.
1010   */
1011   HSA_AMD_LINK_INFO_TYPE_HYPERTRANSPORT = 0,
1012
1013   /**
1014   * QPI bus type.
1015   */
1016   HSA_AMD_LINK_INFO_TYPE_QPI = 1,
1017
1018   /**
1019   * PCIe bus type.
1020   */
1021   HSA_AMD_LINK_INFO_TYPE_PCIE = 2,
1022
1023   /**
1024   * Infiniband bus type.
1025   */
1026   HSA_AMD_LINK_INFO_TYPE_INFINBAND = 3,
1027
1028   /**
1029   * xGMI link type.
1030   */
1031   HSA_AMD_LINK_INFO_TYPE_XGMI = 4
1032
1033 } hsa_amd_link_info_type_t;
1034
1035 /**
1036  * @brief Link properties when accessing the memory pool from the specified
1037  * agent.
1038  */
1039 typedef struct hsa_amd_memory_pool_link_info_s {
1040   /**
1041   * Minimum transfer latency (rounded to ns).
1042   */
1043   uint32_t min_latency;
1044
1045   /**
1046   * Maximum transfer latency (rounded to ns).
1047   */
1048   uint32_t max_latency;
1049
1050   /**
1051   * Minimum link interface bandwidth in MB/s.
1052   */
1053   uint32_t min_bandwidth;
1054
1055   /**
1056   * Maximum link interface bandwidth in MB/s.
1057   */
1058   uint32_t max_bandwidth;
1059
1060   /**
1061   * Support for 32-bit atomic transactions.
1062   */
1063   bool atomic_support_32bit;
1064
1065   /**
1066   * Support for 64-bit atomic transactions.
1067   */
1068   bool atomic_support_64bit;
1069
1070   /**
1071   * Support for cache coherent transactions.
1072   */
1073   bool coherent_support;
1074
1075   /**
1076   * The type of bus/link.
1077   */
1078   hsa_amd_link_info_type_t link_type;
1079
1080   /**
1081    * NUMA distance of memory pool relative to querying agent
1082    */
1083   uint32_t numa_distance;
1084 } hsa_amd_memory_pool_link_info_t;
1085
1086 /**
1087  * @brief Properties of the relationship between an agent a memory pool.
1088  */
1089 typedef enum {
1090   /**
1091   * Access to buffers located in the memory pool. The type of this attribute
1092   * is ::hsa_amd_memory_pool_access_t.
1093   *
1094   * An agent can always directly access buffers currently located in a memory
1095   * pool that is associated (the memory_pool is one of the values returned by
1096   * ::hsa_amd_agent_iterate_memory_pools on the agent) with that agent. If the
1097   * buffer is currently located in a memory pool that is not associated with
1098   * the agent, and the value returned by this function for the given
1099   * combination of agent and memory pool is not
1100   * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED, the application still needs to invoke
1101   * ::hsa_amd_agents_allow_access in order to gain direct access to the buffer.
1102   *
1103   * If the given agent can directly access buffers the pool, the result is not
1104   * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is associated with
1105   * the agent, or it is of fined-grained type, the result must not be
1106   * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. If the memory pool is not associated
1107   * with the agent, and does not reside in the global segment, the result must
1108   * be HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED.
1109   */
1110   HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS = 0,
1111
1112   /**
1113   * Number of links to hop when accessing the memory pool from the specified
1114   * agent. The value of this attribute is zero if the memory pool is associated
1115   * with the agent, or if the access type is
1116   * HSA_AMD_MEMORY_POOL_ACCESS_NEVER_ALLOWED. The type of this attribute is
1117   * uint32_t.
1118   */
1119   HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS = 1,
1120
1121   /**
1122   * Details of each link hop when accessing the memory pool starting from the
1123   * specified agent. The type of this attribute is an array size of
1124   * HSA_AMD_AGENT_MEMORY_POOL_INFO_NUM_LINK_HOPS with each element containing
1125   * ::hsa_amd_memory_pool_link_info_t.
1126   */
1127   HSA_AMD_AGENT_MEMORY_POOL_INFO_LINK_INFO = 2
1128
1129 } hsa_amd_agent_memory_pool_info_t;
1130
1131 /**
1132  * @brief Get the current value of an attribute of the relationship between an
1133  * agent and a memory pool.
1134  *
1135  * @param[in] agent Agent.
1136  *
1137  * @param[in] memory_pool Memory pool.
1138  *
1139  * @param[in] attribute Attribute to query.
1140  *
1141  * @param[out] value Pointer to a application-allocated buffer where to store
1142  * the value of the attribute. If the buffer passed by the application is not
1143  * large enough to hold the value of @p attribute, the behavior is undefined.
1144  *
1145  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1146  *
1147  */
1148 hsa_status_t HSA_API hsa_amd_agent_memory_pool_get_info(
1149     hsa_agent_t agent, hsa_amd_memory_pool_t memory_pool,
1150     hsa_amd_agent_memory_pool_info_t attribute, void* value);
1151
1152 /**
1153  * @brief Enable direct access to a buffer from a given set of agents.
1154  *
1155  * @details
1156  *
1157  * Upon return, only the listed agents and the agent associated with the
1158  * buffer's memory pool have direct access to the @p ptr.
1159  *
1160  * Any agent that has access to the buffer before and after the call to
1161  * ::hsa_amd_agents_allow_access will also have access while
1162  * ::hsa_amd_agents_allow_access is in progress.
1163  *
1164  * The caller is responsible for ensuring that each agent in the list
1165  * must be able to access the memory pool containing @p ptr
1166  * (using ::hsa_amd_agent_memory_pool_get_info with ::HSA_AMD_AGENT_MEMORY_POOL_INFO_ACCESS attribute),
1167  * otherwise error code is returned.
1168  *
1169  * @param[in] num_agents Size of @p agents.
1170  *
1171  * @param[in] agents List of agents. If @p num_agents is 0, this argument is
1172  * ignored.
1173  *
1174  * @param[in] flags A list of bit-field that is used to specify access
1175  * information in a per-agent basis. This is currently reserved and must be NULL.
1176  *
1177  * @param[in] ptr A buffer previously allocated using ::hsa_amd_memory_pool_allocate.
1178  *
1179  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1180  *
1181  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1182  * initialized.
1183  *
1184  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p num_agents is 0, or @p agents
1185  * is NULL, @p flags is not NULL, or attempting to enable access to agent(s)
1186  * because @p ptr is allocated from an inaccessible pool.
1187  *
1188  */
1189 hsa_status_t HSA_API
1190     hsa_amd_agents_allow_access(uint32_t num_agents, const hsa_agent_t* agents,
1191                                 const uint32_t* flags, const void* ptr);
1192
1193 /**
1194  * @brief Query if buffers currently located in some memory pool can be
1195  * relocated to a destination memory pool.
1196  *
1197  * @details If the returned value is non-zero, a migration of a buffer to @p
1198  * dst_memory_pool using ::hsa_amd_memory_migrate may nevertheless fail due to
1199  * resource limitations.
1200  *
1201  * @param[in] src_memory_pool Source memory pool.
1202  *
1203  * @param[in] dst_memory_pool Destination memory pool.
1204  *
1205  * @param[out] result Pointer to a memory location where the result of the query
1206  * is stored. Must not be NULL. If buffers currently located in @p
1207  * src_memory_pool can be relocated to @p dst_memory_pool, the result is
1208  * true.
1209  *
1210  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1211  *
1212  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1213  * initialized.
1214  *
1215  * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL One of the memory pools is
1216  * invalid.
1217  *
1218  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p result is NULL.
1219  */
1220 hsa_status_t HSA_API
1221     hsa_amd_memory_pool_can_migrate(hsa_amd_memory_pool_t src_memory_pool,
1222                                     hsa_amd_memory_pool_t dst_memory_pool,
1223                                     bool* result);
1224
1225 /**
1226  * @brief Relocate a buffer to a new memory pool.
1227  *
1228  * @details When a buffer is migrated, its virtual address remains the same but
1229  * its physical contents are moved to the indicated memory pool.
1230  *
1231  * After migration, only the agent associated with the destination pool will have access.
1232  *
1233  * The caller is also responsible for ensuring that the allocation in the
1234  * source memory pool where the buffer is currently located can be migrated to the
1235  * specified destination memory pool (using ::hsa_amd_memory_pool_can_migrate returns a value of true
1236  * for the source and destination memory pools), otherwise behavior is undefined.
1237  *
1238  * The caller must ensure that the buffer is not accessed while it is migrated.
1239  *
1240  * @param[in] ptr Buffer to be relocated. The buffer must have been released to system
1241  * prior to call this API.  The buffer will be released to system upon completion.
1242  *
1243  * @param[in] memory_pool Memory pool where to place the buffer.
1244  *
1245  * @param[in] flags A bit-field that is used to specify migration
1246  * information. Must be zero.
1247  *
1248  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1249  *
1250  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1251  * initialized.
1252  *
1253  * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL The destination memory pool is
1254  * invalid.
1255  *
1256  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
1257  * allocating the necessary resources.
1258  *
1259  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p flags is not 0.
1260  */
1261 hsa_status_t HSA_API hsa_amd_memory_migrate(const void* ptr,
1262                                             hsa_amd_memory_pool_t memory_pool,
1263                                             uint32_t flags);
1264
1265 /**
1266  *
1267  * @brief Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and
1268  * return a new pointer accessible by the @p agents. If the @p host_ptr overlaps with previously
1269  * locked memory, then the overlap area is kept locked (i.e multiple mappings are permitted). In
1270  * this case, the same input @p host_ptr may give different locked @p agent_ptr and when it does,
1271  * they are not necessarily coherent (i.e. accessing either @p agent_ptr is not equivalent).
1272  * Accesses to @p agent_ptr are coarse grained.
1273  *
1274  * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator.
1275  *
1276  * @param[in] size The size to be locked.
1277  *
1278  * @param[in] agents Array of agent handle to gain access to the @p host_ptr.
1279  * If this parameter is NULL and the @p num_agent is 0, all agents
1280  * in the platform will gain access to the @p host_ptr.
1281  *
1282  * @param[out] agent_ptr Pointer to the location where to store the new address.
1283  *
1284  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1285  *
1286  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1287  * initialized.
1288  *
1289  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
1290  * allocating the necessary resources.
1291  *
1292  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT One or more agent in @p agents is
1293  * invalid.
1294  *
1295  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p size is 0 or @p host_ptr or
1296  * @p agent_ptr is NULL or @p agents not NULL but @p num_agent is 0 or @p agents
1297  * is NULL but @p num_agent is not 0.
1298  */
1299 hsa_status_t HSA_API hsa_amd_memory_lock(void* host_ptr, size_t size,
1300                                          hsa_agent_t* agents, int num_agent,
1301                                          void** agent_ptr);
1302
1303 /**
1304  *
1305  * @brief Pin a host pointer allocated by C/C++ or OS allocator (i.e. ordinary system DRAM) and
1306  * return a new pointer accessible by the @p agents. If the @p host_ptr overlaps with previously
1307  * locked memory, then the overlap area is kept locked (i.e. multiple mappings are permitted).
1308  * In this case, the same input @p host_ptr may give different locked @p agent_ptr and when it
1309  * does, they are not necessarily coherent (i.e. accessing either @p agent_ptr is not equivalent).
1310  * Acesses to the memory via @p agent_ptr have the same access properties as memory allocated from
1311  * @p pool as determined by ::hsa_amd_memory_pool_get_info and ::hsa_amd_agent_memory_pool_get_info
1312  * (ex. coarse/fine grain, platform atomic support, link info).  Physical composition and placement
1313  * of the memory (ex. page size, NUMA binding) is not changed.
1314  *
1315  * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator.
1316  *
1317  * @param[in] size The size to be locked.
1318  *
1319  * @param[in] agents Array of agent handle to gain access to the @p host_ptr.
1320  * If this parameter is NULL and the @p num_agent is 0, all agents
1321  * in the platform will gain access to the @p host_ptr.
1322  *
1323  * @param[in] pool Global memory pool owned by a CPU agent.
1324  *
1325  * @param[in] flags A bit-field that is used to specify allocation
1326  * directives. Reserved parameter, must be 0.
1327  *
1328  * @param[out] agent_ptr Pointer to the location where to store the new address.
1329  *
1330  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1331  *
1332  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1333  * initialized.
1334  *
1335  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES There is a failure in
1336  * allocating the necessary resources.
1337  *
1338  * @retval ::HSA_STATUS_ERROR_INVALID_AGENT One or more agent in @p agents is
1339  * invalid or can not access @p pool.
1340  *
1341  * @retval ::HSA_STATUS_ERROR_INVALID_MEMORY_POOL @p pool is invalid or not owned
1342  * by a CPU agent.
1343  *
1344  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p size is 0 or @p host_ptr or
1345  * @p agent_ptr is NULL or @p agents not NULL but @p num_agent is 0 or @p agents
1346  * is NULL but @p num_agent is not 0 or flags is not 0.
1347  */
1348 hsa_status_t HSA_API hsa_amd_memory_lock_to_pool(void* host_ptr, size_t size, hsa_agent_t* agents,
1349                                                  int num_agent, hsa_amd_memory_pool_t pool,
1350                                                  uint32_t flags, void** agent_ptr);
1351
1352 /**
1353  *
1354  * @brief Unpin the host pointer previously pinned via ::hsa_amd_memory_lock or
1355  * ::hsa_amd_memory_lock_to_pool.
1356  *
1357  * @details The behavior is undefined if the host pointer being unpinned does not
1358  * match previous pinned address or if the host pointer was already deallocated.
1359  *
1360  * @param[in] host_ptr A buffer allocated by C/C++ or OS allocator that was
1361  * pinned previously via ::hsa_amd_memory_lock or ::hsa_amd_memory_lock_to_pool.
1362  *
1363  * @retval ::HSA_STATUS_SUCCESS The function has been executed successfully.
1364  *
1365  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1366  * initialized.
1367  */
1368 hsa_status_t HSA_API hsa_amd_memory_unlock(void* host_ptr);
1369
1370 /**
1371  * @brief Sets the first @p count of uint32_t of the block of memory pointed by
1372  * @p ptr to the specified @p value.
1373  *
1374  * @param[in] ptr Pointer to the block of memory to fill.
1375  *
1376  * @param[in] value Value to be set.
1377  *
1378  * @param[in] count Number of uint32_t element to be set to the value.
1379  *
1380  * @retval HSA_STATUS_SUCCESS The function has been executed successfully.
1381  *
1382  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1383  * initialized.
1384  *
1385  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr is NULL or
1386  * not 4 bytes aligned
1387  *
1388  * @retval HSA_STATUS_ERROR_INVALID_ALLOCATION if the given memory
1389  * region was not allocated with HSA runtime APIs.
1390  *
1391  */
1392 hsa_status_t HSA_API
1393     hsa_amd_memory_fill(void* ptr, uint32_t value, size_t count);
1394
1395 /**
1396  * @brief Maps an interop object into the HSA flat address space and establishes
1397  * memory residency.  The metadata pointer is valid during the lifetime of the
1398  * map (until hsa_amd_interop_unmap_buffer is called).
1399  * Multiple calls to hsa_amd_interop_map_buffer with the same interop_handle
1400  * result in multiple mappings with potentially different addresses and
1401  * different metadata pointers.  Concurrent operations on these addresses are
1402  * not coherent.  Memory must be fenced to system scope to ensure consistency,
1403  * between mappings and with any views of this buffer in the originating
1404  * software stack.
1405  *
1406  * @param[in] num_agents Number of agents which require access to the memory
1407  *
1408  * @param[in] agents List of accessing agents.
1409  *
1410  * @param[in] interop_handle Handle of interop buffer (dmabuf handle in Linux)
1411  *
1412  * @param [in] flags Reserved, must be 0
1413  *
1414  * @param[out] size Size in bytes of the mapped object
1415  *
1416  * @param[out] ptr Base address of the mapped object
1417  *
1418  * @param[out] metadata_size Size of metadata in bytes, may be NULL
1419  *
1420  * @param[out] metadata Pointer to metadata, may be NULL
1421  *
1422  * @retval HSA_STATUS_SUCCESS if successfully mapped
1423  *
1424  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1425  *
1426  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1427  * necessary resources
1428  *
1429  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT all other errors
1430  */
1431 hsa_status_t HSA_API hsa_amd_interop_map_buffer(uint32_t num_agents,
1432                                         hsa_agent_t* agents,
1433                                         int interop_handle,
1434                                         uint32_t flags,
1435                                         size_t* size,
1436                                         void** ptr,
1437                                         size_t* metadata_size,
1438                                         const void** metadata);
1439
1440 /**
1441  * @brief Removes a previously mapped interop object from HSA's flat address space.
1442  * Ends lifetime for the mapping's associated metadata pointer.
1443  */
1444 hsa_status_t HSA_API hsa_amd_interop_unmap_buffer(void* ptr);
1445
1446 /**
1447  * @brief Encodes an opaque vendor specific image format.  The length of data
1448  * depends on the underlying format.  This structure must not be copied as its
1449  * true length can not be determined.
1450  */
1451 typedef struct hsa_amd_image_descriptor_s {
1452   /*
1453   Version number of the descriptor
1454   */
1455   uint32_t version;
1456
1457   /*
1458   Vendor and device PCI IDs for the format as VENDOR_ID<<16|DEVICE_ID.
1459   */
1460   uint32_t deviceID;
1461
1462   /*
1463   Start of vendor specific data.
1464   */
1465   uint32_t data[1];
1466 } hsa_amd_image_descriptor_t;
1467
1468 /**
1469  * @brief Creates an image from an opaque vendor specific image format.
1470  * Does not modify data at image_data.  Intended initially for
1471  * accessing interop images.
1472  *
1473  * @param agent[in] Agent on which to create the image
1474  *
1475  * @param[in] image_descriptor[in] Vendor specific image format
1476  *
1477  * @param[in] image_data Pointer to image backing store
1478  *
1479  * @param[in] access_permission Access permissions for the image object
1480  *
1481  * @param[out] image Created image object.
1482  *
1483  * @retval HSA_STATUS_SUCCESS Image created successfully
1484  *
1485  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1486  *
1487  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1488  * necessary resources
1489  *
1490  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT Bad or mismatched descriptor,
1491  * null image_data, or mismatched access_permission.
1492  */
1493 hsa_status_t HSA_API hsa_amd_image_create(
1494     hsa_agent_t agent,
1495     const hsa_ext_image_descriptor_t *image_descriptor,
1496     const hsa_amd_image_descriptor_t *image_layout,
1497     const void *image_data,
1498     hsa_access_permission_t access_permission,
1499     hsa_ext_image_t *image
1500 );
1501
1502 /**
1503  * @brief Denotes the type of memory in a pointer info query.
1504  */
1505 typedef enum {
1506   /*
1507   Memory is not known to the HSA driver.  Unallocated or unlocked system memory.
1508   */
1509   HSA_EXT_POINTER_TYPE_UNKNOWN = 0,
1510   /*
1511   Memory was allocated with an HSA memory allocator.
1512   */
1513   HSA_EXT_POINTER_TYPE_HSA = 1,
1514   /*
1515   System memory which has been locked for use with an HSA agent.
1516
1517   Memory of this type is normal malloc'd memory and is always accessible to
1518   the CPU.  Pointer info queries may not include CPU agents in the accessible
1519   agents list as the CPU has implicit access.
1520   */
1521   HSA_EXT_POINTER_TYPE_LOCKED = 2,
1522   /*
1523   Memory originated in a graphics component and is shared with ROCr.
1524   */
1525   HSA_EXT_POINTER_TYPE_GRAPHICS = 3,
1526   /*
1527   Memory has been shared with the local process via ROCr IPC APIs.
1528   */
1529   HSA_EXT_POINTER_TYPE_IPC = 4
1530 } hsa_amd_pointer_type_t;
1531
1532 /**
1533  * @brief Describes a memory allocation known to ROCr.
1534  * Within a ROCr major version this structure can only grow.
1535  */
1536 typedef struct hsa_amd_pointer_info_s {
1537   /*
1538   Size in bytes of this structure.  Used for version control within a major ROCr
1539   revision.  Set to sizeof(hsa_amd_pointer_t) prior to calling
1540   hsa_amd_pointer_info.  If the runtime supports an older version of pointer
1541   info then size will be smaller on return.  Members starting after the return
1542   value of size will not be updated by hsa_amd_pointer_info.
1543   */
1544   uint32_t size;
1545   /*
1546   The type of allocation referenced.
1547   */
1548   hsa_amd_pointer_type_t type;
1549   /*
1550   Base address at which non-host agents may access the allocation.
1551   */
1552   void* agentBaseAddress;
1553   /*
1554   Base address at which the host agent may access the allocation.
1555   */
1556   void* hostBaseAddress;
1557   /*
1558   Size of the allocation
1559   */
1560   size_t sizeInBytes;
1561   /*
1562   Application provided value.
1563   */
1564   void* userData;
1565   /*
1566   Reports an agent which "owns" (ie has preferred access to) the pool in which the allocation was
1567   made.  When multiple agents share equal access to a pool (ex: multiple CPU agents, or multi-die
1568   GPU boards) any such agent may be returned.
1569   */
1570   hsa_agent_t agentOwner;
1571 } hsa_amd_pointer_info_t;
1572
1573 /**
1574  * @brief Retrieves information about the allocation referenced by the given
1575  * pointer.  Optionally returns the number and list of agents which can
1576  * directly access the allocation.
1577  *
1578  * @param[in] ptr Pointer which references the allocation to retrieve info for.
1579  *
1580  * @param[in, out] info Pointer to structure to be filled with allocation info.
1581  * Data member size must be set to the size of the structure prior to calling
1582  * hsa_amd_pointer_info.  On return size will be set to the size of the
1583  * pointer info structure supported by the runtime, if smaller.  Members
1584  * beyond the returned value of size will not be updated by the API.
1585  * Must not be NULL.
1586  *
1587  * @param[in] alloc Function pointer to an allocator used to allocate the
1588  * @p accessible array.  If NULL @p accessible will not be returned.
1589  *
1590  * @param[out] num_agents_accessible Recieves the count of agents in
1591  * @p accessible.  If NULL @p accessible will not be returned.
1592  *
1593  * @param[out] accessible Recieves a pointer to the array, allocated by @p alloc,
1594  * holding the list of agents which may directly access the allocation.
1595  * May be NULL.
1596  *
1597  * @retval HSA_STATUS_SUCCESS Info retrieved successfully
1598  *
1599  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1600  *
1601  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1602  * necessary resources
1603  *
1604  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT NULL in @p ptr or @p info.
1605  */
1606 hsa_status_t HSA_API hsa_amd_pointer_info(void* ptr,
1607                                           hsa_amd_pointer_info_t* info,
1608                                           void* (*alloc)(size_t),
1609                                           uint32_t* num_agents_accessible,
1610                                           hsa_agent_t** accessible);
1611
1612 /**
1613  * @brief Associates an arbitrary pointer with an allocation known to ROCr.
1614  * The pointer can be fetched by hsa_amd_pointer_info in the userData field.
1615  *
1616  * @param[in] ptr Pointer to the first byte of an allocation known to ROCr
1617  * with which to associate @p userdata.
1618  *
1619  * @param[in] userdata Abitrary pointer to associate with the allocation.
1620  *
1621  * @retval HSA_STATUS_SUCCESS @p userdata successfully stored.
1622  *
1623  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1624  *
1625  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1626  * necessary resources
1627  *
1628  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr is not known to ROCr.
1629  */
1630 hsa_status_t HSA_API hsa_amd_pointer_info_set_userdata(void* ptr,
1631                                                        void* userdata);
1632
1633 /**
1634  * @brief 256-bit process independent identifier for a ROCr shared memory
1635  * allocation.
1636  */
1637 typedef struct hsa_amd_ipc_memory_s {
1638   uint32_t handle[8];
1639 } hsa_amd_ipc_memory_t;
1640
1641 /**
1642  * @brief Prepares an allocation for interprocess sharing and creates a
1643  * handle of type hsa_amd_ipc_memory_t uniquely identifying the allocation.  A
1644  * handle is valid while the allocation it references remains accessible in
1645  * any process.  In general applications should confirm that a shared memory
1646  * region has been attached (via hsa_amd_ipc_memory_attach) in the remote
1647  * process prior to releasing that memory in the local process.
1648  * Repeated calls for the same allocation may, but are not required to, return
1649  * unique handles.
1650  *
1651  * @param[in] ptr Pointer to memory allocated via ROCr APIs to prepare for
1652  * sharing.
1653  *
1654  * @param[in] len Length in bytes of the allocation to share.
1655  *
1656  * @param[out] handle Process independent identifier referencing the shared
1657  * allocation.
1658  *
1659  * @retval HSA_STATUS_SUCCESS allocation is prepared for interprocess sharing.
1660  *
1661  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1662  *
1663  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1664  * necessary resources
1665  *
1666  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p ptr does not point to the
1667  * first byte of an allocation made through ROCr, or len is not the full length
1668  * of the allocation or handle is NULL.
1669  */
1670 hsa_status_t HSA_API hsa_amd_ipc_memory_create(void* ptr, size_t len,
1671                                                hsa_amd_ipc_memory_t* handle);
1672
1673 /**
1674  * @brief Imports shared memory into the local process and makes it accessible
1675  * by the given agents.  If a shared memory handle is attached multiple times
1676  * in a process each attach may return a different address.  Each returned
1677  * address is refcounted and requires a matching number of calls to
1678  * hsa_amd_ipc_memory_detach to release the shared memory mapping.
1679  *
1680  * @param[in] handle Pointer to the identifier for the shared memory.
1681  *
1682  * @param[in] len Length of the shared memory to import.
1683  * Reserved.  Must be the full length of the shared allocation in this version.
1684  *
1685  * @param[in] num_agents Count of agents in @p mapping_agents.
1686  * May be zero if all agents are to be allowed access.
1687  *
1688  * @param[in] mapping_agents List of agents to access the shared memory.
1689  * Ignored if @p num_agents is zero.
1690  *
1691  * @param[out] mapped_ptr Recieves a process local pointer to the shared memory.
1692  *
1693  * @retval HSA_STATUS_SUCCESS if memory is successfully imported.
1694  *
1695  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1696  *
1697  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1698  * necessary resources
1699  *
1700  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p handle is not valid, @p len is
1701  * incorrect, @p mapped_ptr is NULL, or some agent for which access was
1702  * requested can not access the shared memory.
1703  */
1704 hsa_status_t HSA_API hsa_amd_ipc_memory_attach(
1705     const hsa_amd_ipc_memory_t* handle, size_t len,
1706     uint32_t num_agents,
1707     const hsa_agent_t* mapping_agents,
1708     void** mapped_ptr);
1709
1710 /**
1711  * @brief Decrements the reference count for the shared memory mapping and
1712  * releases access to shared memory imported with hsa_amd_ipc_memory_attach.
1713  *
1714  * @param[in] mapped_ptr Pointer to the first byte of a shared allocation
1715  * imported with hsa_amd_ipc_memory_attach.
1716  *
1717  * @retval HSA_STATUS_SUCCESS if @p mapped_ptr was imported with
1718  * hsa_amd_ipc_memory_attach.
1719  *
1720  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1721  *
1722  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p mapped_ptr was not imported
1723  * with hsa_amd_ipc_memory_attach.
1724  */
1725 hsa_status_t HSA_API hsa_amd_ipc_memory_detach(void* mapped_ptr);
1726
1727 /**
1728  * @brief 256-bit process independent identifier for a ROCr IPC signal.
1729  */
1730 typedef hsa_amd_ipc_memory_t hsa_amd_ipc_signal_t;
1731
1732 /**
1733  * @brief Obtains an interprocess sharing handle for a signal.  The handle is
1734  * valid while the signal it references remains valid in any process.  In
1735  * general applications should confirm that the signal has been attached (via
1736  * hsa_amd_ipc_signal_attach) in the remote process prior to destroying that
1737  * signal in the local process.
1738  * Repeated calls for the same signal may, but are not required to, return
1739  * unique handles.
1740  *
1741  * @param[in] signal Signal created with attribute HSA_AMD_SIGNAL_IPC.
1742  *
1743  * @param[out] handle Process independent identifier referencing the shared
1744  * signal.
1745  *
1746  * @retval HSA_STATUS_SUCCESS @p handle is ready to use for interprocess sharing.
1747  *
1748  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1749  *
1750  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1751  * necessary resources
1752  *
1753  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p signal is not a valid signal
1754  * created with attribute HSA_AMD_SIGNAL_IPC or handle is NULL.
1755  */
1756 hsa_status_t HSA_API hsa_amd_ipc_signal_create(hsa_signal_t signal, hsa_amd_ipc_signal_t* handle);
1757
1758 /**
1759  * @brief Imports an IPC capable signal into the local process.  If an IPC
1760  * signal handle is attached multiple times in a process each attach may return
1761  * a different signal handle.  Each returned signal handle is refcounted and
1762  * requires a matching number of calls to hsa_signal_destroy to release the
1763  * shared signal.
1764  *
1765  * @param[in] handle Pointer to the identifier for the shared signal.
1766  *
1767  * @param[out] signal Recieves a process local signal handle to the shared signal.
1768  *
1769  * @retval HSA_STATUS_SUCCESS if the signal is successfully imported.
1770  *
1771  * @retval HSA_STATUS_ERROR_NOT_INITIALIZED if HSA is not initialized
1772  *
1773  * @retval HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1774  * necessary resources
1775  *
1776  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p handle is not valid.
1777  */
1778 hsa_status_t HSA_API hsa_amd_ipc_signal_attach(const hsa_amd_ipc_signal_t* handle,
1779                                                hsa_signal_t* signal);
1780
1781 /**
1782  * @brief GPU system event type.
1783  */
1784 typedef enum hsa_amd_event_type_s {
1785   /*
1786    AMD GPU memory fault.
1787    */
1788   HSA_AMD_GPU_MEMORY_FAULT_EVENT = 0,
1789 } hsa_amd_event_type_t;
1790
1791 /**
1792  * @brief Flags denoting the cause of a memory fault.
1793  */
1794 typedef enum {
1795   // Page not present or supervisor privilege.
1796   HSA_AMD_MEMORY_FAULT_PAGE_NOT_PRESENT = 1 << 0,
1797   // Write access to a read-only page.
1798   HSA_AMD_MEMORY_FAULT_READ_ONLY = 1 << 1,
1799   // Execute access to a page marked NX.
1800   HSA_AMD_MEMORY_FAULT_NX = 1 << 2,
1801   // GPU attempted access to a host only page.
1802   HSA_AMD_MEMORY_FAULT_HOST_ONLY = 1 << 3,
1803   // DRAM ECC failure.
1804   HSA_AMD_MEMORY_FAULT_DRAM_ECC = 1 << 4,
1805   // Can't determine the exact fault address.
1806   HSA_AMD_MEMORY_FAULT_IMPRECISE = 1 << 5,
1807   // SRAM ECC failure (ie registers, no fault address).
1808   HSA_AMD_MEMORY_FAULT_SRAM_ECC = 1 << 6,
1809   // GPU reset following unspecified hang.
1810   HSA_AMD_MEMORY_FAULT_HANG = 1 << 31
1811 } hsa_amd_memory_fault_reason_t;
1812
1813 /**
1814  * @brief AMD GPU memory fault event data.
1815  */
1816 typedef struct hsa_amd_gpu_memory_fault_info_s {
1817   /*
1818   The agent where the memory fault occurred.
1819   */
1820   hsa_agent_t agent;
1821   /*
1822   Virtual address accessed.
1823   */
1824   uint64_t virtual_address;
1825   /*
1826   Bit field encoding the memory access failure reasons. There could be multiple bits set
1827   for one fault.  Bits are defined in hsa_amd_memory_fault_reason_t.
1828   */
1829   uint32_t fault_reason_mask;
1830 } hsa_amd_gpu_memory_fault_info_t;
1831
1832 /**
1833  * @brief AMD GPU event data passed to event handler.
1834  */
1835 typedef struct hsa_amd_event_s {
1836   /*
1837   The event type.
1838   */
1839   hsa_amd_event_type_t event_type;
1840   union {
1841     /*
1842     The memory fault info, only valid when @p event_type is HSA_AMD_GPU_MEMORY_FAULT_EVENT.
1843     */
1844     hsa_amd_gpu_memory_fault_info_t memory_fault;
1845   };
1846 } hsa_amd_event_t;
1847
1848 typedef hsa_status_t (*hsa_amd_system_event_callback_t)(const hsa_amd_event_t* event, void* data);
1849
1850 /**
1851  * @brief Register AMD GPU event handler.
1852  *
1853  * @param[in] callback Callback to be invoked when an event is triggered.
1854  * The HSA runtime passes two arguments to the callback: @p event
1855  * is defined per event by the HSA runtime, and @p data is the user data.
1856  *
1857  * @param[in] data User data that is passed to @p callback. May be NULL.
1858  *
1859  * @retval HSA_STATUS_SUCCESS The handler has been registered successfully.
1860  *
1861  * @retval HSA_STATUS_ERROR An event handler has already been registered.
1862  *
1863  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT @p event is invalid.
1864  */
1865 hsa_status_t HSA_API hsa_amd_register_system_event_handler(hsa_amd_system_event_callback_t callback,
1866                                                    void* data);
1867
1868 /**
1869  * @brief Per-queue dispatch and wavefront scheduling priority.
1870  */
1871 typedef enum hsa_amd_queue_priority_s {
1872   /*
1873   Below normal/high priority compute and all graphics
1874   */
1875   HSA_AMD_QUEUE_PRIORITY_LOW = 0,
1876   /*
1877   Above low priority compute, below high priority compute and all graphics
1878   */
1879   HSA_AMD_QUEUE_PRIORITY_NORMAL = 1,
1880   /*
1881   Above low/normal priority compute and all graphics
1882   */
1883   HSA_AMD_QUEUE_PRIORITY_HIGH = 2,
1884 } hsa_amd_queue_priority_t;
1885
1886 /**
1887  * @brief Modifies the dispatch and wavefront scheduling prioirty for a
1888  * given compute queue. The default is HSA_AMD_QUEUE_PRIORITY_NORMAL.
1889  *
1890  * @param[in] queue Compute queue to apply new priority to.
1891  *
1892  * @param[in] priority Priority to associate with queue.
1893  *
1894  * @retval HSA_STATUS_SUCCESS if priority was changed successfully.
1895  *
1896  * @retval HSA_STATUS_ERROR_INVALID_QUEUE if queue is not a valid
1897  * compute queue handle.
1898  *
1899  * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT if priority is not a valid
1900  * value from hsa_amd_queue_priority_t.
1901  */
1902 hsa_status_t HSA_API hsa_amd_queue_set_priority(hsa_queue_t* queue,
1903                                                 hsa_amd_queue_priority_t priority);
1904
1905 /**
1906  * @brief Deallocation notifier function type.
1907  */
1908 typedef void (*hsa_amd_deallocation_callback_t)(void* ptr, void* user_data);
1909
1910 /**
1911  * @brief Registers a deallocation notifier monitoring for release of agent
1912  * accessible address @p ptr.  If successful, @p callback will be invoked when
1913  * @p ptr is removed from accessibility from all agents.
1914  *
1915  * Notification callbacks are automatically deregistered when they are invoked.
1916  *
1917  * Note: The current version supports notifications of address release
1918  * originating from ::hsa_amd_memory_pool_free.  Support for other address
1919  * release APIs will follow.
1920  *
1921  * @param[in] ptr Agent accessible address to monitor for deallocation.  Passed
1922  * to @p callback.
1923  *
1924  * @param[in] callback Notifier to be invoked when @p ptr is released from
1925  * agent accessibility.
1926  *
1927  * @param[in] user_data User provided value passed to @p callback.  May be NULL.
1928  *
1929  * @retval ::HSA_STATUS_SUCCESS The notifier registered successfully
1930  *
1931  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1932  * initialized.
1933  *
1934  * @retval ::HSA_STATUS_ERROR_INVALID_ALLOCATION @p ptr does not refer to a valid agent accessible
1935  * address.
1936  *
1937  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT @p callback is NULL or @p ptr is NULL.
1938  *
1939  * @retval ::HSA_STATUS_ERROR_OUT_OF_RESOURCES if there is a failure in allocating
1940  * necessary resources
1941  */
1942 hsa_status_t HSA_API hsa_amd_register_deallocation_callback(void* ptr,
1943                                                     hsa_amd_deallocation_callback_t callback,
1944                                                     void* user_data);
1945
1946 /**
1947  * @brief Removes a deallocation notifier previously registered with
1948  * ::hsa_amd_register_deallocation_callback.  Arguments must be identical to
1949  * those given in ::hsa_amd_register_deallocation_callback.
1950  *
1951  * @param[in] ptr Agent accessible address which was monitored for deallocation.
1952  *
1953  * @param[in] callback Notifier to be removed.
1954  *
1955  * @retval ::HSA_STATUS_SUCCESS The notifier has been removed successfully.
1956  *
1957  * @retval ::HSA_STATUS_ERROR_NOT_INITIALIZED The HSA runtime has not been
1958  * initialized.
1959  *
1960  * @retval ::HSA_STATUS_ERROR_INVALID_ARGUMENT The given notifier was not registered.
1961  */
1962 hsa_status_t HSA_API hsa_amd_deregister_deallocation_callback(void* ptr,
1963                                                       hsa_amd_deallocation_callback_t callback);
1964
1965 #ifdef __cplusplus
1966 }  // end extern "C" block
1967 #endif
1968
1969 #endif  // header guard