]>
Commit | Line | Data |
---|---|---|
85f0a4d9 AS |
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 |