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