mirror of OpenBSD xenocara tree
github.com/openbsd/xenocara
openbsd
1/*
2 * Copyright 2014 Advanced Micro Devices, Inc.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 *
22 */
23
24/**
25 * \file amdgpu.h
26 *
27 * Declare public libdrm_amdgpu API
28 *
29 * This file define API exposed by libdrm_amdgpu library.
30 * User wanted to use libdrm_amdgpu functionality must include
31 * this file.
32 *
33 */
34#ifndef _AMDGPU_H_
35#define _AMDGPU_H_
36
37#include <stdint.h>
38#include <stdbool.h>
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44struct drm_amdgpu_info_hw_ip;
45struct drm_amdgpu_bo_list_entry;
46
47/*--------------------------------------------------------------------------*/
48/* --------------------------- Defines ------------------------------------ */
49/*--------------------------------------------------------------------------*/
50
51/**
52 * Define max. number of Command Buffers (IB) which could be sent to the single
53 * hardware IP to accommodate CE/DE requirements
54 *
55 * \sa amdgpu_cs_ib_info
56*/
57#define AMDGPU_CS_MAX_IBS_PER_SUBMIT 4
58
59/**
60 * Special timeout value meaning that the timeout is infinite.
61 */
62#define AMDGPU_TIMEOUT_INFINITE 0xffffffffffffffffull
63
64/**
65 * Used in amdgpu_cs_query_fence_status(), meaning that the given timeout
66 * is absolute.
67 */
68#define AMDGPU_QUERY_FENCE_TIMEOUT_IS_ABSOLUTE (1 << 0)
69
70/*--------------------------------------------------------------------------*/
71/* ----------------------------- Enums ------------------------------------ */
72/*--------------------------------------------------------------------------*/
73
74/**
75 * Enum describing possible handle types
76 *
77 * \sa amdgpu_bo_import, amdgpu_bo_export
78 *
79*/
80enum amdgpu_bo_handle_type {
81 /** GEM flink name (needs DRM authentication, used by DRI2) */
82 amdgpu_bo_handle_type_gem_flink_name = 0,
83
84 /** KMS handle which is used by all driver ioctls */
85 amdgpu_bo_handle_type_kms = 1,
86
87 /** DMA-buf fd handle */
88 amdgpu_bo_handle_type_dma_buf_fd = 2,
89
90 /** Deprecated in favour of and same behaviour as
91 * amdgpu_bo_handle_type_kms, use that instead of this
92 */
93 amdgpu_bo_handle_type_kms_noimport = 3,
94};
95
96/** Define known types of GPU VM VA ranges */
97enum amdgpu_gpu_va_range
98{
99 /** Allocate from "normal"/general range */
100 amdgpu_gpu_va_range_general = 0
101};
102
103enum amdgpu_sw_info {
104 amdgpu_sw_info_address32_hi = 0,
105};
106
107/*--------------------------------------------------------------------------*/
108/* -------------------------- Datatypes ----------------------------------- */
109/*--------------------------------------------------------------------------*/
110
111/**
112 * Define opaque pointer to context associated with fd.
113 * This context will be returned as the result of
114 * "initialize" function and should be pass as the first
115 * parameter to any API call
116 */
117typedef struct amdgpu_device *amdgpu_device_handle;
118
119/**
120 * Define GPU Context type as pointer to opaque structure
121 * Example of GPU Context is the "rendering" context associated
122 * with OpenGL context (glCreateContext)
123 */
124typedef struct amdgpu_context *amdgpu_context_handle;
125
126/**
127 * Define handle for amdgpu resources: buffer, GDS, etc.
128 */
129typedef struct amdgpu_bo *amdgpu_bo_handle;
130
131/**
132 * Define handle for list of BOs
133 */
134typedef struct amdgpu_bo_list *amdgpu_bo_list_handle;
135
136/**
137 * Define handle to be used to work with VA allocated ranges
138 */
139typedef struct amdgpu_va *amdgpu_va_handle;
140
141/**
142 * Define handle dealing with VA allocation. An amdgpu_device
143 * owns one of these, but they can also be used without a device.
144 */
145typedef struct amdgpu_va_manager *amdgpu_va_manager_handle;
146
147/**
148 * Define handle for semaphore
149 */
150typedef struct amdgpu_semaphore *amdgpu_semaphore_handle;
151
152/*--------------------------------------------------------------------------*/
153/* -------------------------- Structures ---------------------------------- */
154/*--------------------------------------------------------------------------*/
155
156/**
157 * Structure describing memory allocation request
158 *
159 * \sa amdgpu_bo_alloc()
160 *
161*/
162struct amdgpu_bo_alloc_request {
163 /** Allocation request. It must be aligned correctly. */
164 uint64_t alloc_size;
165
166 /**
167 * It may be required to have some specific alignment requirements
168 * for physical back-up storage (e.g. for displayable surface).
169 * If 0 there is no special alignment requirement
170 */
171 uint64_t phys_alignment;
172
173 /**
174 * UMD should specify where to allocate memory and how it
175 * will be accessed by the CPU.
176 */
177 uint32_t preferred_heap;
178
179 /** Additional flags passed on allocation */
180 uint64_t flags;
181};
182
183/**
184 * Special UMD specific information associated with buffer.
185 *
186 * It may be need to pass some buffer charactersitic as part
187 * of buffer sharing. Such information are defined UMD and
188 * opaque for libdrm_amdgpu as well for kernel driver.
189 *
190 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_query_info,
191 * amdgpu_bo_import(), amdgpu_bo_export
192 *
193*/
194struct amdgpu_bo_metadata {
195 /** Special flag associated with surface */
196 uint64_t flags;
197
198 /**
199 * ASIC-specific tiling information (also used by DCE).
200 * The encoding is defined by the AMDGPU_TILING_* definitions.
201 */
202 uint64_t tiling_info;
203
204 /** Size of metadata associated with the buffer, in bytes. */
205 uint32_t size_metadata;
206
207 /** UMD specific metadata. Opaque for kernel */
208 uint32_t umd_metadata[64];
209};
210
211/**
212 * Structure describing allocated buffer. Client may need
213 * to query such information as part of 'sharing' buffers mechanism
214 *
215 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_query_info(),
216 * amdgpu_bo_import(), amdgpu_bo_export()
217*/
218struct amdgpu_bo_info {
219 /** Allocated memory size */
220 uint64_t alloc_size;
221
222 /**
223 * It may be required to have some specific alignment requirements
224 * for physical back-up storage.
225 */
226 uint64_t phys_alignment;
227
228 /** Heap where to allocate memory. */
229 uint32_t preferred_heap;
230
231 /** Additional allocation flags. */
232 uint64_t alloc_flags;
233
234 /** Metadata associated with buffer if any. */
235 struct amdgpu_bo_metadata metadata;
236};
237
238/**
239 * Structure with information about "imported" buffer
240 *
241 * \sa amdgpu_bo_import()
242 *
243 */
244struct amdgpu_bo_import_result {
245 /** Handle of memory/buffer to use */
246 amdgpu_bo_handle buf_handle;
247
248 /** Buffer size */
249 uint64_t alloc_size;
250};
251
252/**
253 *
254 * Structure to describe GDS partitioning information.
255 * \note OA and GWS resources are asscoiated with GDS partition
256 *
257 * \sa amdgpu_gpu_resource_query_gds_info
258 *
259*/
260struct amdgpu_gds_resource_info {
261 uint32_t gds_gfx_partition_size;
262 uint32_t compute_partition_size;
263 uint32_t gds_total_size;
264 uint32_t gws_per_gfx_partition;
265 uint32_t gws_per_compute_partition;
266 uint32_t oa_per_gfx_partition;
267 uint32_t oa_per_compute_partition;
268};
269
270/**
271 * Structure describing CS fence
272 *
273 * \sa amdgpu_cs_query_fence_status(), amdgpu_cs_request, amdgpu_cs_submit()
274 *
275*/
276struct amdgpu_cs_fence {
277
278 /** In which context IB was sent to execution */
279 amdgpu_context_handle context;
280
281 /** To which HW IP type the fence belongs */
282 uint32_t ip_type;
283
284 /** IP instance index if there are several IPs of the same type. */
285 uint32_t ip_instance;
286
287 /** Ring index of the HW IP */
288 uint32_t ring;
289
290 /** Specify fence for which we need to check submission status.*/
291 uint64_t fence;
292};
293
294/**
295 * Structure describing IB
296 *
297 * \sa amdgpu_cs_request, amdgpu_cs_submit()
298 *
299*/
300struct amdgpu_cs_ib_info {
301 /** Special flags */
302 uint64_t flags;
303
304 /** Virtual MC address of the command buffer */
305 uint64_t ib_mc_address;
306
307 /**
308 * Size of Command Buffer to be submitted.
309 * - The size is in units of dwords (4 bytes).
310 * - Could be 0
311 */
312 uint32_t size;
313};
314
315/**
316 * Structure describing fence information
317 *
318 * \sa amdgpu_cs_request, amdgpu_cs_query_fence,
319 * amdgpu_cs_submit(), amdgpu_cs_query_fence_status()
320*/
321struct amdgpu_cs_fence_info {
322 /** buffer object for the fence */
323 amdgpu_bo_handle handle;
324
325 /** fence offset in the unit of sizeof(uint64_t) */
326 uint64_t offset;
327};
328
329/**
330 * Structure describing submission request
331 *
332 * \note We could have several IBs as packet. e.g. CE, CE, DE case for gfx
333 *
334 * \sa amdgpu_cs_submit()
335*/
336struct amdgpu_cs_request {
337 /** Specify flags with additional information */
338 uint64_t flags;
339
340 /** Specify HW IP block type to which to send the IB. */
341 unsigned ip_type;
342
343 /** IP instance index if there are several IPs of the same type. */
344 unsigned ip_instance;
345
346 /**
347 * Specify ring index of the IP. We could have several rings
348 * in the same IP. E.g. 0 for SDMA0 and 1 for SDMA1.
349 */
350 uint32_t ring;
351
352 /**
353 * List handle with resources used by this request.
354 */
355 amdgpu_bo_list_handle resources;
356
357 /**
358 * Number of dependencies this Command submission needs to
359 * wait for before starting execution.
360 */
361 uint32_t number_of_dependencies;
362
363 /**
364 * Array of dependencies which need to be met before
365 * execution can start.
366 */
367 struct amdgpu_cs_fence *dependencies;
368
369 /** Number of IBs to submit in the field ibs. */
370 uint32_t number_of_ibs;
371
372 /**
373 * IBs to submit. Those IBs will be submit together as single entity
374 */
375 struct amdgpu_cs_ib_info *ibs;
376
377 /**
378 * The returned sequence number for the command submission
379 */
380 uint64_t seq_no;
381
382 /**
383 * The fence information
384 */
385 struct amdgpu_cs_fence_info fence_info;
386};
387
388/**
389 * Structure which provide information about GPU VM MC Address space
390 * alignments requirements
391 *
392 * \sa amdgpu_query_buffer_size_alignment
393 */
394struct amdgpu_buffer_size_alignments {
395 /** Size alignment requirement for allocation in
396 * local memory */
397 uint64_t size_local;
398
399 /**
400 * Size alignment requirement for allocation in remote memory
401 */
402 uint64_t size_remote;
403};
404
405/**
406 * Structure which provide information about heap
407 *
408 * \sa amdgpu_query_heap_info()
409 *
410 */
411struct amdgpu_heap_info {
412 /** Theoretical max. available memory in the given heap */
413 uint64_t heap_size;
414
415 /**
416 * Number of bytes allocated in the heap. This includes all processes
417 * and private allocations in the kernel. It changes when new buffers
418 * are allocated, freed, and moved. It cannot be larger than
419 * heap_size.
420 */
421 uint64_t heap_usage;
422
423 /**
424 * Theoretical possible max. size of buffer which
425 * could be allocated in the given heap
426 */
427 uint64_t max_allocation;
428};
429
430/**
431 * Describe GPU h/w info needed for UMD correct initialization
432 *
433 * \sa amdgpu_query_gpu_info()
434*/
435struct amdgpu_gpu_info {
436 /** Asic id */
437 uint32_t asic_id;
438 /** Chip revision */
439 uint32_t chip_rev;
440 /** Chip external revision */
441 uint32_t chip_external_rev;
442 /** Family ID */
443 uint32_t family_id;
444 /** Special flags */
445 uint64_t ids_flags;
446 /** max engine clock*/
447 uint64_t max_engine_clk;
448 /** max memory clock */
449 uint64_t max_memory_clk;
450 /** number of shader engines */
451 uint32_t num_shader_engines;
452 /** number of shader arrays per engine */
453 uint32_t num_shader_arrays_per_engine;
454 /** Number of available good shader pipes */
455 uint32_t avail_quad_shader_pipes;
456 /** Max. number of shader pipes.(including good and bad pipes */
457 uint32_t max_quad_shader_pipes;
458 /** Number of parameter cache entries per shader quad pipe */
459 uint32_t cache_entries_per_quad_pipe;
460 /** Number of available graphics context */
461 uint32_t num_hw_gfx_contexts;
462 /** Number of render backend pipes */
463 uint32_t rb_pipes;
464 /** Enabled render backend pipe mask */
465 uint32_t enabled_rb_pipes_mask;
466 /** Frequency of GPU Counter */
467 uint32_t gpu_counter_freq;
468 /** CC_RB_BACKEND_DISABLE.BACKEND_DISABLE per SE */
469 uint32_t backend_disable[4];
470 /** Value of MC_ARB_RAMCFG register*/
471 uint32_t mc_arb_ramcfg;
472 /** Value of GB_ADDR_CONFIG */
473 uint32_t gb_addr_cfg;
474 /** Values of the GB_TILE_MODE0..31 registers */
475 uint32_t gb_tile_mode[32];
476 /** Values of GB_MACROTILE_MODE0..15 registers */
477 uint32_t gb_macro_tile_mode[16];
478 /** Value of PA_SC_RASTER_CONFIG register per SE */
479 uint32_t pa_sc_raster_cfg[4];
480 /** Value of PA_SC_RASTER_CONFIG_1 register per SE */
481 uint32_t pa_sc_raster_cfg1[4];
482 /* CU info */
483 uint32_t cu_active_number;
484 uint32_t cu_ao_mask;
485 uint32_t cu_bitmap[4][4];
486 /* video memory type info*/
487 uint32_t vram_type;
488 /* video memory bit width*/
489 uint32_t vram_bit_width;
490 /** constant engine ram size*/
491 uint32_t ce_ram_size;
492 /* vce harvesting instance */
493 uint32_t vce_harvest_config;
494 /* PCI revision ID */
495 uint32_t pci_rev_id;
496};
497
498
499/*--------------------------------------------------------------------------*/
500/*------------------------- Functions --------------------------------------*/
501/*--------------------------------------------------------------------------*/
502
503/*
504 * Initialization / Cleanup
505 *
506*/
507
508/**
509 *
510 * \param fd - \c [in] File descriptor for AMD GPU device
511 * received previously as the result of
512 * e.g. drmOpen() call.
513 * For legacy fd type, the DRI2/DRI3
514 * authentication should be done before
515 * calling this function.
516 * \param major_version - \c [out] Major version of library. It is assumed
517 * that adding new functionality will cause
518 * increase in major version
519 * \param minor_version - \c [out] Minor version of library
520 * \param device_handle - \c [out] Pointer to opaque context which should
521 * be passed as the first parameter on each
522 * API call
523 *
524 *
525 * \return 0 on success\n
526 * <0 - Negative POSIX Error code
527 *
528 *
529 * \sa amdgpu_device_deinitialize()
530*/
531int amdgpu_device_initialize(int fd,
532 uint32_t *major_version,
533 uint32_t *minor_version,
534 amdgpu_device_handle *device_handle);
535
536/**
537 * Same as amdgpu_device_initialize() except when deduplicate_device
538 * is false *and* fd points to a device that was already initialized.
539 * In this case, amdgpu_device_initialize would return the same
540 * amdgpu_device_handle while here amdgpu_device_initialize2 would
541 * return a new handle.
542 * amdgpu_device_initialize() should be preferred in most situations;
543 * the only use-case where not-deduplicating devices make sense is
544 * when one wants to have isolated device handles in the same process.
545 */
546int amdgpu_device_initialize2(int fd, bool deduplicate_device,
547 uint32_t *major_version,
548 uint32_t *minor_version,
549 amdgpu_device_handle *device_handle);
550/**
551 *
552 * When access to such library does not needed any more the special
553 * function must be call giving opportunity to clean up any
554 * resources if needed.
555 *
556 * \param device_handle - \c [in] Context associated with file
557 * descriptor for AMD GPU device
558 * received previously as the
559 * result e.g. of drmOpen() call.
560 *
561 * \return 0 on success\n
562 * <0 - Negative POSIX Error code
563 *
564 * \sa amdgpu_device_initialize()
565 *
566*/
567int amdgpu_device_deinitialize(amdgpu_device_handle device_handle);
568
569/**
570 *
571 * /param device_handle - \c [in] Device handle.
572 * See #amdgpu_device_initialize()
573 *
574 * \return Returns the drm fd used for operations on this
575 * device. This is still owned by the library and hence
576 * should not be closed. Guaranteed to be valid until
577 * #amdgpu_device_deinitialize gets called.
578 *
579*/
580int amdgpu_device_get_fd(amdgpu_device_handle device_handle);
581
582/*
583 * Memory Management
584 *
585*/
586
587/**
588 * Allocate memory to be used by UMD for GPU related operations
589 *
590 * \param dev - \c [in] Device handle.
591 * See #amdgpu_device_initialize()
592 * \param alloc_buffer - \c [in] Pointer to the structure describing an
593 * allocation request
594 * \param buf_handle - \c [out] Allocated buffer handle
595 *
596 * \return 0 on success\n
597 * <0 - Negative POSIX Error code
598 *
599 * \sa amdgpu_bo_free()
600*/
601int amdgpu_bo_alloc(amdgpu_device_handle dev,
602 struct amdgpu_bo_alloc_request *alloc_buffer,
603 amdgpu_bo_handle *buf_handle);
604
605/**
606 * Associate opaque data with buffer to be queried by another UMD
607 *
608 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
609 * \param buf_handle - \c [in] Buffer handle
610 * \param info - \c [in] Metadata to associated with buffer
611 *
612 * \return 0 on success\n
613 * <0 - Negative POSIX Error code
614*/
615int amdgpu_bo_set_metadata(amdgpu_bo_handle buf_handle,
616 struct amdgpu_bo_metadata *info);
617
618/**
619 * Query buffer information including metadata previusly associated with
620 * buffer.
621 *
622 * \param dev - \c [in] Device handle.
623 * See #amdgpu_device_initialize()
624 * \param buf_handle - \c [in] Buffer handle
625 * \param info - \c [out] Structure describing buffer
626 *
627 * \return 0 on success\n
628 * <0 - Negative POSIX Error code
629 *
630 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_alloc()
631*/
632int amdgpu_bo_query_info(amdgpu_bo_handle buf_handle,
633 struct amdgpu_bo_info *info);
634
635/**
636 * Allow others to get access to buffer
637 *
638 * \param dev - \c [in] Device handle.
639 * See #amdgpu_device_initialize()
640 * \param buf_handle - \c [in] Buffer handle
641 * \param type - \c [in] Type of handle requested
642 * \param shared_handle - \c [out] Special "shared" handle
643 *
644 * \return 0 on success\n
645 * <0 - Negative POSIX Error code
646 *
647 * \sa amdgpu_bo_import()
648 *
649*/
650int amdgpu_bo_export(amdgpu_bo_handle buf_handle,
651 enum amdgpu_bo_handle_type type,
652 uint32_t *shared_handle);
653
654/**
655 * Request access to "shared" buffer
656 *
657 * \param dev - \c [in] Device handle.
658 * See #amdgpu_device_initialize()
659 * \param type - \c [in] Type of handle requested
660 * \param shared_handle - \c [in] Shared handle received as result "import"
661 * operation
662 * \param output - \c [out] Pointer to structure with information
663 * about imported buffer
664 *
665 * \return 0 on success\n
666 * <0 - Negative POSIX Error code
667 *
668 * \note Buffer must be "imported" only using new "fd" (different from
669 * one used by "exporter").
670 *
671 * \sa amdgpu_bo_export()
672 *
673*/
674int amdgpu_bo_import(amdgpu_device_handle dev,
675 enum amdgpu_bo_handle_type type,
676 uint32_t shared_handle,
677 struct amdgpu_bo_import_result *output);
678
679/**
680 * Request GPU access to user allocated memory e.g. via "malloc"
681 *
682 * \param dev - [in] Device handle. See #amdgpu_device_initialize()
683 * \param cpu - [in] CPU address of user allocated memory which we
684 * want to map to GPU address space (make GPU accessible)
685 * (This address must be correctly aligned).
686 * \param size - [in] Size of allocation (must be correctly aligned)
687 * \param buf_handle - [out] Buffer handle for the userptr memory
688 * resource on submission and be used in other operations.
689 *
690 *
691 * \return 0 on success\n
692 * <0 - Negative POSIX Error code
693 *
694 * \note
695 * This call doesn't guarantee that such memory will be persistently
696 * "locked" / make non-pageable. The purpose of this call is to provide
697 * opportunity for GPU get access to this resource during submission.
698 *
699 * The maximum amount of memory which could be mapped in this call depends
700 * if overcommit is disabled or not. If overcommit is disabled than the max.
701 * amount of memory to be pinned will be limited by left "free" size in total
702 * amount of memory which could be locked simultaneously ("GART" size).
703 *
704 * Supported (theoretical) max. size of mapping is restricted only by
705 * "GART" size.
706 *
707 * It is responsibility of caller to correctly specify access rights
708 * on VA assignment.
709*/
710int amdgpu_create_bo_from_user_mem(amdgpu_device_handle dev,
711 void *cpu, uint64_t size,
712 amdgpu_bo_handle *buf_handle);
713
714/**
715 * Validate if the user memory comes from BO
716 *
717 * \param dev - [in] Device handle. See #amdgpu_device_initialize()
718 * \param cpu - [in] CPU address of user allocated memory which we
719 * want to map to GPU address space (make GPU accessible)
720 * (This address must be correctly aligned).
721 * \param size - [in] Size of allocation (must be correctly aligned)
722 * \param buf_handle - [out] Buffer handle for the userptr memory
723 * if the user memory is not from BO, the buf_handle will be NULL.
724 * \param offset_in_bo - [out] offset in this BO for this user memory
725 *
726 *
727 * \return 0 on success\n
728 * <0 - Negative POSIX Error code
729 *
730*/
731int amdgpu_find_bo_by_cpu_mapping(amdgpu_device_handle dev,
732 void *cpu,
733 uint64_t size,
734 amdgpu_bo_handle *buf_handle,
735 uint64_t *offset_in_bo);
736
737/**
738 * Free previously allocated memory
739 *
740 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
741 * \param buf_handle - \c [in] Buffer handle to free
742 *
743 * \return 0 on success\n
744 * <0 - Negative POSIX Error code
745 *
746 * \note In the case of memory shared between different applications all
747 * resources will be “physically” freed only all such applications
748 * will be terminated
749 * \note If is UMD responsibility to ‘free’ buffer only when there is no
750 * more GPU access
751 *
752 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_alloc()
753 *
754*/
755int amdgpu_bo_free(amdgpu_bo_handle buf_handle);
756
757/**
758 * Increase the reference count of a buffer object
759 *
760 * \param bo - \c [in] Buffer object handle to increase the reference count
761 *
762 * \sa amdgpu_bo_alloc(), amdgpu_bo_free()
763 *
764*/
765void amdgpu_bo_inc_ref(amdgpu_bo_handle bo);
766
767/**
768 * Request CPU access to GPU accessible memory
769 *
770 * \param buf_handle - \c [in] Buffer handle
771 * \param cpu - \c [out] CPU address to be used for access
772 *
773 * \return 0 on success\n
774 * <0 - Negative POSIX Error code
775 *
776 * \sa amdgpu_bo_cpu_unmap()
777 *
778*/
779int amdgpu_bo_cpu_map(amdgpu_bo_handle buf_handle, void **cpu);
780
781/**
782 * Release CPU access to GPU memory
783 *
784 * \param buf_handle - \c [in] Buffer handle
785 *
786 * \return 0 on success\n
787 * <0 - Negative POSIX Error code
788 *
789 * \sa amdgpu_bo_cpu_map()
790 *
791*/
792int amdgpu_bo_cpu_unmap(amdgpu_bo_handle buf_handle);
793
794/**
795 * Wait until a buffer is not used by the device.
796 *
797 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
798 * \param buf_handle - \c [in] Buffer handle.
799 * \param timeout_ns - Timeout in nanoseconds.
800 * \param buffer_busy - 0 if buffer is idle, all GPU access was completed
801 * and no GPU access is scheduled.
802 * 1 GPU access is in fly or scheduled
803 *
804 * \return 0 - on success
805 * <0 - Negative POSIX Error code
806 */
807int amdgpu_bo_wait_for_idle(amdgpu_bo_handle buf_handle,
808 uint64_t timeout_ns,
809 bool *buffer_busy);
810
811/**
812 * Creates a BO list handle for command submission.
813 *
814 * \param dev - \c [in] Device handle.
815 * See #amdgpu_device_initialize()
816 * \param number_of_buffers - \c [in] Number of BOs in the list
817 * \param buffers - \c [in] List of BO handles
818 * \param result - \c [out] Created BO list handle
819 *
820 * \return 0 on success\n
821 * <0 - Negative POSIX Error code
822 *
823 * \sa amdgpu_bo_list_destroy_raw(), amdgpu_cs_submit_raw2()
824*/
825int amdgpu_bo_list_create_raw(amdgpu_device_handle dev,
826 uint32_t number_of_buffers,
827 struct drm_amdgpu_bo_list_entry *buffers,
828 uint32_t *result);
829
830/**
831 * Destroys a BO list handle.
832 *
833 * \param bo_list - \c [in] BO list handle.
834 *
835 * \return 0 on success\n
836 * <0 - Negative POSIX Error code
837 *
838 * \sa amdgpu_bo_list_create_raw(), amdgpu_cs_submit_raw2()
839*/
840int amdgpu_bo_list_destroy_raw(amdgpu_device_handle dev, uint32_t bo_list);
841
842/**
843 * Creates a BO list handle for command submission.
844 *
845 * \param dev - \c [in] Device handle.
846 * See #amdgpu_device_initialize()
847 * \param number_of_resources - \c [in] Number of BOs in the list
848 * \param resources - \c [in] List of BO handles
849 * \param resource_prios - \c [in] Optional priority for each handle
850 * \param result - \c [out] Created BO list handle
851 *
852 * \return 0 on success\n
853 * <0 - Negative POSIX Error code
854 *
855 * \sa amdgpu_bo_list_destroy()
856*/
857int amdgpu_bo_list_create(amdgpu_device_handle dev,
858 uint32_t number_of_resources,
859 amdgpu_bo_handle *resources,
860 uint8_t *resource_prios,
861 amdgpu_bo_list_handle *result);
862
863/**
864 * Destroys a BO list handle.
865 *
866 * \param handle - \c [in] BO list handle.
867 *
868 * \return 0 on success\n
869 * <0 - Negative POSIX Error code
870 *
871 * \sa amdgpu_bo_list_create()
872*/
873int amdgpu_bo_list_destroy(amdgpu_bo_list_handle handle);
874
875/**
876 * Update resources for existing BO list
877 *
878 * \param handle - \c [in] BO list handle
879 * \param number_of_resources - \c [in] Number of BOs in the list
880 * \param resources - \c [in] List of BO handles
881 * \param resource_prios - \c [in] Optional priority for each handle
882 *
883 * \return 0 on success\n
884 * <0 - Negative POSIX Error code
885 *
886 * \sa amdgpu_bo_list_update()
887*/
888int amdgpu_bo_list_update(amdgpu_bo_list_handle handle,
889 uint32_t number_of_resources,
890 amdgpu_bo_handle *resources,
891 uint8_t *resource_prios);
892
893/*
894 * GPU Execution context
895 *
896*/
897
898/**
899 * Create GPU execution Context
900 *
901 * For the purpose of GPU Scheduler and GPU Robustness extensions it is
902 * necessary to have information/identify rendering/compute contexts.
903 * It also may be needed to associate some specific requirements with such
904 * contexts. Kernel driver will guarantee that submission from the same
905 * context will always be executed in order (first come, first serve).
906 *
907 *
908 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
909 * \param priority - \c [in] Context creation flags. See AMDGPU_CTX_PRIORITY_*
910 * \param context - \c [out] GPU Context handle
911 *
912 * \return 0 on success\n
913 * <0 - Negative POSIX Error code
914 *
915 * \sa amdgpu_cs_ctx_free()
916 *
917*/
918int amdgpu_cs_ctx_create2(amdgpu_device_handle dev,
919 uint32_t priority,
920 amdgpu_context_handle *context);
921/**
922 * Create GPU execution Context
923 *
924 * Refer to amdgpu_cs_ctx_create2 for full documentation. This call
925 * is missing the priority parameter.
926 *
927 * \sa amdgpu_cs_ctx_create2()
928 *
929*/
930int amdgpu_cs_ctx_create(amdgpu_device_handle dev,
931 amdgpu_context_handle *context);
932
933/**
934 *
935 * Destroy GPU execution context when not needed any more
936 *
937 * \param context - \c [in] GPU Context handle
938 *
939 * \return 0 on success\n
940 * <0 - Negative POSIX Error code
941 *
942 * \sa amdgpu_cs_ctx_create()
943 *
944*/
945int amdgpu_cs_ctx_free(amdgpu_context_handle context);
946
947/**
948 * Override the submission priority for the given context using a master fd.
949 *
950 * \param dev - \c [in] device handle
951 * \param context - \c [in] context handle for context id
952 * \param master_fd - \c [in] The master fd to authorize the override.
953 * \param priority - \c [in] The priority to assign to the context.
954 *
955 * \return 0 on success or a a negative Posix error code on failure.
956 */
957int amdgpu_cs_ctx_override_priority(amdgpu_device_handle dev,
958 amdgpu_context_handle context,
959 int master_fd,
960 unsigned priority);
961
962/**
963 * Set or query the stable power state for GPU profiling.
964 *
965 * \param dev - \c [in] device handle
966 * \param op - \c [in] AMDGPU_CTX_OP_{GET,SET}_STABLE_PSTATE
967 * \param flags - \c [in] AMDGPU_CTX_STABLE_PSTATE_*
968 * \param out_flags - \c [out] output current stable pstate
969 *
970 * \return 0 on success otherwise POSIX Error code.
971 */
972int amdgpu_cs_ctx_stable_pstate(amdgpu_context_handle context,
973 uint32_t op,
974 uint32_t flags,
975 uint32_t *out_flags);
976
977/**
978 * Query reset state for the specific GPU Context
979 *
980 * \param context - \c [in] GPU Context handle
981 * \param state - \c [out] One of AMDGPU_CTX_*_RESET
982 * \param hangs - \c [out] Number of hangs caused by the context.
983 *
984 * \return 0 on success\n
985 * <0 - Negative POSIX Error code
986 *
987 * \sa amdgpu_cs_ctx_create()
988 *
989*/
990int amdgpu_cs_query_reset_state(amdgpu_context_handle context,
991 uint32_t *state, uint32_t *hangs);
992
993/**
994 * Query reset state for the specific GPU Context.
995 *
996 * \param context - \c [in] GPU Context handle
997 * \param flags - \c [out] A combination of AMDGPU_CTX_QUERY2_FLAGS_*
998 *
999 * \return 0 on success\n
1000 * <0 - Negative POSIX Error code
1001 *
1002 * \sa amdgpu_cs_ctx_create()
1003 *
1004*/
1005int amdgpu_cs_query_reset_state2(amdgpu_context_handle context,
1006 uint64_t *flags);
1007
1008/*
1009 * Command Buffers Management
1010 *
1011*/
1012
1013/**
1014 * Send request to submit command buffers to hardware.
1015 *
1016 * Kernel driver could use GPU Scheduler to make decision when physically
1017 * sent this request to the hardware. Accordingly this request could be put
1018 * in queue and sent for execution later. The only guarantee is that request
1019 * from the same GPU context to the same ip:ip_instance:ring will be executed in
1020 * order.
1021 *
1022 * The caller can specify the user fence buffer/location with the fence_info in the
1023 * cs_request.The sequence number is returned via the 'seq_no' parameter
1024 * in ibs_request structure.
1025 *
1026 *
1027 * \param dev - \c [in] Device handle.
1028 * See #amdgpu_device_initialize()
1029 * \param context - \c [in] GPU Context
1030 * \param flags - \c [in] Global submission flags
1031 * \param ibs_request - \c [in/out] Pointer to submission requests.
1032 * We could submit to the several
1033 * engines/rings simulteniously as
1034 * 'atomic' operation
1035 * \param number_of_requests - \c [in] Number of submission requests
1036 *
1037 * \return 0 on success\n
1038 * <0 - Negative POSIX Error code
1039 *
1040 * \note It is required to pass correct resource list with buffer handles
1041 * which will be accessible by command buffers from submission
1042 * This will allow kernel driver to correctly implement "paging".
1043 * Failure to do so will have unpredictable results.
1044 *
1045 * \sa amdgpu_command_buffer_alloc(), amdgpu_command_buffer_free(),
1046 * amdgpu_cs_query_fence_status()
1047 *
1048*/
1049int amdgpu_cs_submit(amdgpu_context_handle context,
1050 uint64_t flags,
1051 struct amdgpu_cs_request *ibs_request,
1052 uint32_t number_of_requests);
1053
1054/**
1055 * Query status of Command Buffer Submission
1056 *
1057 * \param fence - \c [in] Structure describing fence to query
1058 * \param timeout_ns - \c [in] Timeout value to wait
1059 * \param flags - \c [in] Flags for the query
1060 * \param expired - \c [out] If fence expired or not.\n
1061 * 0 – if fence is not expired\n
1062 * !0 - otherwise
1063 *
1064 * \return 0 on success\n
1065 * <0 - Negative POSIX Error code
1066 *
1067 * \note If UMD wants only to check operation status and returned immediately
1068 * then timeout value as 0 must be passed. In this case success will be
1069 * returned in the case if submission was completed or timeout error
1070 * code.
1071 *
1072 * \sa amdgpu_cs_submit()
1073*/
1074int amdgpu_cs_query_fence_status(struct amdgpu_cs_fence *fence,
1075 uint64_t timeout_ns,
1076 uint64_t flags,
1077 uint32_t *expired);
1078
1079/**
1080 * Wait for multiple fences
1081 *
1082 * \param fences - \c [in] The fence array to wait
1083 * \param fence_count - \c [in] The fence count
1084 * \param wait_all - \c [in] If true, wait all fences to be signaled,
1085 * otherwise, wait at least one fence
1086 * \param timeout_ns - \c [in] The timeout to wait, in nanoseconds
1087 * \param status - \c [out] '1' for signaled, '0' for timeout
1088 * \param first - \c [out] the index of the first signaled fence from @fences
1089 *
1090 * \return 0 on success
1091 * <0 - Negative POSIX Error code
1092 *
1093 * \note Currently it supports only one amdgpu_device. All fences come from
1094 * the same amdgpu_device with the same fd.
1095*/
1096int amdgpu_cs_wait_fences(struct amdgpu_cs_fence *fences,
1097 uint32_t fence_count,
1098 bool wait_all,
1099 uint64_t timeout_ns,
1100 uint32_t *status, uint32_t *first);
1101
1102/*
1103 * Query / Info API
1104 *
1105*/
1106
1107/**
1108 * Query allocation size alignments
1109 *
1110 * UMD should query information about GPU VM MC size alignments requirements
1111 * to be able correctly choose required allocation size and implement
1112 * internal optimization if needed.
1113 *
1114 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1115 * \param info - \c [out] Pointer to structure to get size alignment
1116 * requirements
1117 *
1118 * \return 0 on success\n
1119 * <0 - Negative POSIX Error code
1120 *
1121*/
1122int amdgpu_query_buffer_size_alignment(amdgpu_device_handle dev,
1123 struct amdgpu_buffer_size_alignments
1124 *info);
1125
1126/**
1127 * Query firmware versions
1128 *
1129 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1130 * \param fw_type - \c [in] AMDGPU_INFO_FW_*
1131 * \param ip_instance - \c [in] Index of the IP block of the same type.
1132 * \param index - \c [in] Index of the engine. (for SDMA and MEC)
1133 * \param version - \c [out] Pointer to to the "version" return value
1134 * \param feature - \c [out] Pointer to to the "feature" return value
1135 *
1136 * \return 0 on success\n
1137 * <0 - Negative POSIX Error code
1138 *
1139*/
1140int amdgpu_query_firmware_version(amdgpu_device_handle dev, unsigned fw_type,
1141 unsigned ip_instance, unsigned index,
1142 uint32_t *version, uint32_t *feature);
1143
1144/**
1145 * Query the number of HW IP instances of a certain type.
1146 *
1147 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1148 * \param type - \c [in] Hardware IP block type = AMDGPU_HW_IP_*
1149 * \param count - \c [out] Pointer to structure to get information
1150 *
1151 * \return 0 on success\n
1152 * <0 - Negative POSIX Error code
1153*/
1154int amdgpu_query_hw_ip_count(amdgpu_device_handle dev, unsigned type,
1155 uint32_t *count);
1156
1157/**
1158 * Query engine information
1159 *
1160 * This query allows UMD to query information different engines and their
1161 * capabilities.
1162 *
1163 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1164 * \param type - \c [in] Hardware IP block type = AMDGPU_HW_IP_*
1165 * \param ip_instance - \c [in] Index of the IP block of the same type.
1166 * \param info - \c [out] Pointer to structure to get information
1167 *
1168 * \return 0 on success\n
1169 * <0 - Negative POSIX Error code
1170*/
1171int amdgpu_query_hw_ip_info(amdgpu_device_handle dev, unsigned type,
1172 unsigned ip_instance,
1173 struct drm_amdgpu_info_hw_ip *info);
1174
1175/**
1176 * Query heap information
1177 *
1178 * This query allows UMD to query potentially available memory resources and
1179 * adjust their logic if necessary.
1180 *
1181 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1182 * \param heap - \c [in] Heap type
1183 * \param info - \c [in] Pointer to structure to get needed information
1184 *
1185 * \return 0 on success\n
1186 * <0 - Negative POSIX Error code
1187 *
1188*/
1189int amdgpu_query_heap_info(amdgpu_device_handle dev, uint32_t heap,
1190 uint32_t flags, struct amdgpu_heap_info *info);
1191
1192/**
1193 * Get the CRTC ID from the mode object ID
1194 *
1195 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1196 * \param id - \c [in] Mode object ID
1197 * \param result - \c [in] Pointer to the CRTC ID
1198 *
1199 * \return 0 on success\n
1200 * <0 - Negative POSIX Error code
1201 *
1202*/
1203int amdgpu_query_crtc_from_id(amdgpu_device_handle dev, unsigned id,
1204 int32_t *result);
1205
1206/**
1207 * Query GPU H/w Info
1208 *
1209 * Query hardware specific information
1210 *
1211 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1212 * \param heap - \c [in] Heap type
1213 * \param info - \c [in] Pointer to structure to get needed information
1214 *
1215 * \return 0 on success\n
1216 * <0 - Negative POSIX Error code
1217 *
1218*/
1219int amdgpu_query_gpu_info(amdgpu_device_handle dev,
1220 struct amdgpu_gpu_info *info);
1221
1222/**
1223 * Query hardware or driver information.
1224 *
1225 * The return size is query-specific and depends on the "info_id" parameter.
1226 * No more than "size" bytes is returned.
1227 *
1228 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1229 * \param info_id - \c [in] AMDGPU_INFO_*
1230 * \param size - \c [in] Size of the returned value.
1231 * \param value - \c [out] Pointer to the return value.
1232 *
1233 * \return 0 on success\n
1234 * <0 - Negative POSIX error code
1235 *
1236*/
1237int amdgpu_query_info(amdgpu_device_handle dev, unsigned info_id,
1238 unsigned size, void *value);
1239
1240/**
1241 * Query hardware or driver information.
1242 *
1243 * The return size is query-specific and depends on the "info_id" parameter.
1244 * No more than "size" bytes is returned.
1245 *
1246 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1247 * \param info - \c [in] amdgpu_sw_info_*
1248 * \param value - \c [out] Pointer to the return value.
1249 *
1250 * \return 0 on success\n
1251 * <0 - Negative POSIX error code
1252 *
1253*/
1254int amdgpu_query_sw_info(amdgpu_device_handle dev, enum amdgpu_sw_info info,
1255 void *value);
1256
1257/**
1258 * Query information about GDS
1259 *
1260 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1261 * \param gds_info - \c [out] Pointer to structure to get GDS information
1262 *
1263 * \return 0 on success\n
1264 * <0 - Negative POSIX Error code
1265 *
1266*/
1267int amdgpu_query_gds_info(amdgpu_device_handle dev,
1268 struct amdgpu_gds_resource_info *gds_info);
1269
1270/**
1271 * Query information about sensor.
1272 *
1273 * The return size is query-specific and depends on the "sensor_type"
1274 * parameter. No more than "size" bytes is returned.
1275 *
1276 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1277 * \param sensor_type - \c [in] AMDGPU_INFO_SENSOR_*
1278 * \param size - \c [in] Size of the returned value.
1279 * \param value - \c [out] Pointer to the return value.
1280 *
1281 * \return 0 on success\n
1282 * <0 - Negative POSIX Error code
1283 *
1284*/
1285int amdgpu_query_sensor_info(amdgpu_device_handle dev, unsigned sensor_type,
1286 unsigned size, void *value);
1287
1288/**
1289 * Query information about video capabilities
1290 *
1291 * The return sizeof(struct drm_amdgpu_info_video_caps)
1292 *
1293 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1294 * \param caps_type - \c [in] AMDGPU_INFO_VIDEO_CAPS_DECODE(ENCODE)
1295 * \param size - \c [in] Size of the returned value.
1296 * \param value - \c [out] Pointer to the return value.
1297 *
1298 * \return 0 on success\n
1299 * <0 - Negative POSIX Error code
1300 *
1301*/
1302int amdgpu_query_video_caps_info(amdgpu_device_handle dev, unsigned cap_type,
1303 unsigned size, void *value);
1304
1305/**
1306 * Query information about VM faults
1307 *
1308 * The return sizeof(struct drm_amdgpu_info_gpuvm_fault)
1309 *
1310 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1311 * \param size - \c [in] Size of the returned value.
1312 * \param value - \c [out] Pointer to the return value.
1313 *
1314 * \return 0 on success\n
1315 * <0 - Negative POSIX Error code
1316 *
1317*/
1318int amdgpu_query_gpuvm_fault_info(amdgpu_device_handle dev, unsigned size,
1319 void *value);
1320
1321/**
1322 * Read a set of consecutive memory-mapped registers.
1323 * Not all registers are allowed to be read by userspace.
1324 *
1325 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize(
1326 * \param dword_offset - \c [in] Register offset in dwords
1327 * \param count - \c [in] The number of registers to read starting
1328 * from the offset
1329 * \param instance - \c [in] GRBM_GFX_INDEX selector. It may have other
1330 * uses. Set it to 0xffffffff if unsure.
1331 * \param flags - \c [in] Flags with additional information.
1332 * \param values - \c [out] The pointer to return values.
1333 *
1334 * \return 0 on success\n
1335 * <0 - Negative POSIX error code
1336 *
1337*/
1338int amdgpu_read_mm_registers(amdgpu_device_handle dev, unsigned dword_offset,
1339 unsigned count, uint32_t instance, uint32_t flags,
1340 uint32_t *values);
1341
1342/**
1343 * Flag to request VA address range in the 32bit address space
1344*/
1345#define AMDGPU_VA_RANGE_32_BIT 0x1
1346#define AMDGPU_VA_RANGE_HIGH 0x2
1347#define AMDGPU_VA_RANGE_REPLAYABLE 0x4
1348
1349/**
1350 * Allocate virtual address range
1351 *
1352 * \param dev - [in] Device handle. See #amdgpu_device_initialize()
1353 * \param va_range_type - \c [in] Type of MC va range from which to allocate
1354 * \param size - \c [in] Size of range. Size must be correctly* aligned.
1355 * It is client responsibility to correctly aligned size based on the future
1356 * usage of allocated range.
1357 * \param va_base_alignment - \c [in] Overwrite base address alignment
1358 * requirement for GPU VM MC virtual
1359 * address assignment. Must be multiple of size alignments received as
1360 * 'amdgpu_buffer_size_alignments'.
1361 * If 0 use the default one.
1362 * \param va_base_required - \c [in] Specified required va base address.
1363 * If 0 then library choose available one.
1364 * If !0 value will be passed and those value already "in use" then
1365 * corresponding error status will be returned.
1366 * \param va_base_allocated - \c [out] On return: Allocated VA base to be used
1367 * by client.
1368 * \param va_range_handle - \c [out] On return: Handle assigned to allocation
1369 * \param flags - \c [in] flags for special VA range
1370 *
1371 * \return 0 on success\n
1372 * >0 - AMD specific error code\n
1373 * <0 - Negative POSIX Error code
1374 *
1375 * \notes \n
1376 * It is client responsibility to correctly handle VA assignments and usage.
1377 * Neither kernel driver nor libdrm_amdpgu are able to prevent and
1378 * detect wrong va assignment.
1379 *
1380 * It is client responsibility to correctly handle multi-GPU cases and to pass
1381 * the corresponding arrays of all devices handles where corresponding VA will
1382 * be used.
1383 *
1384*/
1385int amdgpu_va_range_alloc(amdgpu_device_handle dev,
1386 enum amdgpu_gpu_va_range va_range_type,
1387 uint64_t size,
1388 uint64_t va_base_alignment,
1389 uint64_t va_base_required,
1390 uint64_t *va_base_allocated,
1391 amdgpu_va_handle *va_range_handle,
1392 uint64_t flags);
1393
1394/**
1395 * Free previously allocated virtual address range
1396 *
1397 *
1398 * \param va_range_handle - \c [in] Handle assigned to VA allocation
1399 *
1400 * \return 0 on success\n
1401 * >0 - AMD specific error code\n
1402 * <0 - Negative POSIX Error code
1403 *
1404*/
1405int amdgpu_va_range_free(amdgpu_va_handle va_range_handle);
1406
1407/**
1408 * Return the starting address of the allocated virtual address range.
1409 */
1410uint64_t amdgpu_va_get_start_addr(amdgpu_va_handle va_handle);
1411
1412/**
1413* Query virtual address range
1414*
1415* UMD can query GPU VM range supported by each device
1416* to initialize its own VAM accordingly.
1417*
1418* \param dev - [in] Device handle. See #amdgpu_device_initialize()
1419* \param type - \c [in] Type of virtual address range
1420* \param offset - \c [out] Start offset of virtual address range
1421* \param size - \c [out] Size of virtual address range
1422*
1423* \return 0 on success\n
1424* <0 - Negative POSIX Error code
1425*
1426*/
1427
1428int amdgpu_va_range_query(amdgpu_device_handle dev,
1429 enum amdgpu_gpu_va_range type,
1430 uint64_t *start,
1431 uint64_t *end);
1432
1433/**
1434 * Allocate a amdgpu_va_manager object.
1435 * The returned object has be initialized with the amdgpu_va_manager_init
1436 * before use.
1437 * On release, amdgpu_va_manager_deinit needs to be called, then the memory
1438 * can be released using free().
1439 */
1440amdgpu_va_manager_handle amdgpu_va_manager_alloc(void);
1441
1442void amdgpu_va_manager_init(amdgpu_va_manager_handle va_mgr,
1443 uint64_t low_va_offset, uint64_t low_va_max,
1444 uint64_t high_va_offset, uint64_t high_va_max,
1445 uint32_t virtual_address_alignment);
1446
1447void amdgpu_va_manager_deinit(amdgpu_va_manager_handle va_mgr);
1448
1449/**
1450 * Similar to #amdgpu_va_range_alloc() but allocates VA
1451 * directly from an amdgpu_va_manager_handle instead of using
1452 * the manager from an amdgpu_device.
1453 */
1454
1455int amdgpu_va_range_alloc2(amdgpu_va_manager_handle va_mgr,
1456 enum amdgpu_gpu_va_range va_range_type,
1457 uint64_t size,
1458 uint64_t va_base_alignment,
1459 uint64_t va_base_required,
1460 uint64_t *va_base_allocated,
1461 amdgpu_va_handle *va_range_handle,
1462 uint64_t flags);
1463
1464/**
1465 * VA mapping/unmapping for the buffer object
1466 *
1467 * \param bo - \c [in] BO handle
1468 * \param offset - \c [in] Start offset to map
1469 * \param size - \c [in] Size to map
1470 * \param addr - \c [in] Start virtual address.
1471 * \param flags - \c [in] Supported flags for mapping/unmapping
1472 * \param ops - \c [in] AMDGPU_VA_OP_MAP or AMDGPU_VA_OP_UNMAP
1473 *
1474 * \return 0 on success\n
1475 * <0 - Negative POSIX Error code
1476 *
1477*/
1478
1479int amdgpu_bo_va_op(amdgpu_bo_handle bo,
1480 uint64_t offset,
1481 uint64_t size,
1482 uint64_t addr,
1483 uint64_t flags,
1484 uint32_t ops);
1485
1486/**
1487 * VA mapping/unmapping for a buffer object or PRT region.
1488 *
1489 * This is not a simple drop-in extension for amdgpu_bo_va_op; instead, all
1490 * parameters are treated "raw", i.e. size is not automatically aligned, and
1491 * all flags must be specified explicitly.
1492 *
1493 * \param dev - \c [in] device handle
1494 * \param bo - \c [in] BO handle (may be NULL)
1495 * \param offset - \c [in] Start offset to map
1496 * \param size - \c [in] Size to map
1497 * \param addr - \c [in] Start virtual address.
1498 * \param flags - \c [in] Supported flags for mapping/unmapping
1499 * \param ops - \c [in] AMDGPU_VA_OP_MAP or AMDGPU_VA_OP_UNMAP
1500 *
1501 * \return 0 on success\n
1502 * <0 - Negative POSIX Error code
1503 *
1504*/
1505
1506int amdgpu_bo_va_op_raw(amdgpu_device_handle dev,
1507 amdgpu_bo_handle bo,
1508 uint64_t offset,
1509 uint64_t size,
1510 uint64_t addr,
1511 uint64_t flags,
1512 uint32_t ops);
1513
1514/**
1515 * create semaphore
1516 *
1517 * \param sem - \c [out] semaphore handle
1518 *
1519 * \return 0 on success\n
1520 * <0 - Negative POSIX Error code
1521 *
1522*/
1523int amdgpu_cs_create_semaphore(amdgpu_semaphore_handle *sem);
1524
1525/**
1526 * signal semaphore
1527 *
1528 * \param context - \c [in] GPU Context
1529 * \param ip_type - \c [in] Hardware IP block type = AMDGPU_HW_IP_*
1530 * \param ip_instance - \c [in] Index of the IP block of the same type
1531 * \param ring - \c [in] Specify ring index of the IP
1532 * \param sem - \c [in] semaphore handle
1533 *
1534 * \return 0 on success\n
1535 * <0 - Negative POSIX Error code
1536 *
1537*/
1538int amdgpu_cs_signal_semaphore(amdgpu_context_handle ctx,
1539 uint32_t ip_type,
1540 uint32_t ip_instance,
1541 uint32_t ring,
1542 amdgpu_semaphore_handle sem);
1543
1544/**
1545 * wait semaphore
1546 *
1547 * \param context - \c [in] GPU Context
1548 * \param ip_type - \c [in] Hardware IP block type = AMDGPU_HW_IP_*
1549 * \param ip_instance - \c [in] Index of the IP block of the same type
1550 * \param ring - \c [in] Specify ring index of the IP
1551 * \param sem - \c [in] semaphore handle
1552 *
1553 * \return 0 on success\n
1554 * <0 - Negative POSIX Error code
1555 *
1556*/
1557int amdgpu_cs_wait_semaphore(amdgpu_context_handle ctx,
1558 uint32_t ip_type,
1559 uint32_t ip_instance,
1560 uint32_t ring,
1561 amdgpu_semaphore_handle sem);
1562
1563/**
1564 * destroy semaphore
1565 *
1566 * \param sem - \c [in] semaphore handle
1567 *
1568 * \return 0 on success\n
1569 * <0 - Negative POSIX Error code
1570 *
1571*/
1572int amdgpu_cs_destroy_semaphore(amdgpu_semaphore_handle sem);
1573
1574/**
1575 * Get the ASIC marketing name
1576 *
1577 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize()
1578 *
1579 * \return the constant string of the marketing name
1580 * "NULL" means the ASIC is not found
1581*/
1582const char *amdgpu_get_marketing_name(amdgpu_device_handle dev);
1583
1584/**
1585 * Create kernel sync object
1586 *
1587 * \param dev - \c [in] device handle
1588 * \param flags - \c [in] flags that affect creation
1589 * \param syncobj - \c [out] sync object handle
1590 *
1591 * \return 0 on success\n
1592 * <0 - Negative POSIX Error code
1593 *
1594*/
1595int amdgpu_cs_create_syncobj2(amdgpu_device_handle dev,
1596 uint32_t flags,
1597 uint32_t *syncobj);
1598
1599/**
1600 * Create kernel sync object
1601 *
1602 * \param dev - \c [in] device handle
1603 * \param syncobj - \c [out] sync object handle
1604 *
1605 * \return 0 on success\n
1606 * <0 - Negative POSIX Error code
1607 *
1608*/
1609int amdgpu_cs_create_syncobj(amdgpu_device_handle dev,
1610 uint32_t *syncobj);
1611/**
1612 * Destroy kernel sync object
1613 *
1614 * \param dev - \c [in] device handle
1615 * \param syncobj - \c [in] sync object handle
1616 *
1617 * \return 0 on success\n
1618 * <0 - Negative POSIX Error code
1619 *
1620*/
1621int amdgpu_cs_destroy_syncobj(amdgpu_device_handle dev,
1622 uint32_t syncobj);
1623
1624/**
1625 * Reset kernel sync objects to unsignalled state.
1626 *
1627 * \param dev - \c [in] device handle
1628 * \param syncobjs - \c [in] array of sync object handles
1629 * \param syncobj_count - \c [in] number of handles in syncobjs
1630 *
1631 * \return 0 on success\n
1632 * <0 - Negative POSIX Error code
1633 *
1634*/
1635int amdgpu_cs_syncobj_reset(amdgpu_device_handle dev,
1636 const uint32_t *syncobjs, uint32_t syncobj_count);
1637
1638/**
1639 * Signal kernel sync objects.
1640 *
1641 * \param dev - \c [in] device handle
1642 * \param syncobjs - \c [in] array of sync object handles
1643 * \param syncobj_count - \c [in] number of handles in syncobjs
1644 *
1645 * \return 0 on success\n
1646 * <0 - Negative POSIX Error code
1647 *
1648*/
1649int amdgpu_cs_syncobj_signal(amdgpu_device_handle dev,
1650 const uint32_t *syncobjs, uint32_t syncobj_count);
1651
1652/**
1653 * Signal kernel timeline sync objects.
1654 *
1655 * \param dev - \c [in] device handle
1656 * \param syncobjs - \c [in] array of sync object handles
1657 * \param points - \c [in] array of timeline points
1658 * \param syncobj_count - \c [in] number of handles in syncobjs
1659 *
1660 * \return 0 on success\n
1661 * <0 - Negative POSIX Error code
1662 *
1663*/
1664int amdgpu_cs_syncobj_timeline_signal(amdgpu_device_handle dev,
1665 const uint32_t *syncobjs,
1666 uint64_t *points,
1667 uint32_t syncobj_count);
1668
1669/**
1670 * Wait for one or all sync objects to signal.
1671 *
1672 * \param dev - \c [in] self-explanatory
1673 * \param handles - \c [in] array of sync object handles
1674 * \param num_handles - \c [in] self-explanatory
1675 * \param timeout_nsec - \c [in] self-explanatory
1676 * \param flags - \c [in] a bitmask of DRM_SYNCOBJ_WAIT_FLAGS_*
1677 * \param first_signaled - \c [in] self-explanatory
1678 *
1679 * \return 0 on success\n
1680 * -ETIME - Timeout
1681 * <0 - Negative POSIX Error code
1682 *
1683 */
1684int amdgpu_cs_syncobj_wait(amdgpu_device_handle dev,
1685 uint32_t *handles, unsigned num_handles,
1686 int64_t timeout_nsec, unsigned flags,
1687 uint32_t *first_signaled);
1688
1689/**
1690 * Wait for one or all sync objects on their points to signal.
1691 *
1692 * \param dev - \c [in] self-explanatory
1693 * \param handles - \c [in] array of sync object handles
1694 * \param points - \c [in] array of sync points to wait
1695 * \param num_handles - \c [in] self-explanatory
1696 * \param timeout_nsec - \c [in] self-explanatory
1697 * \param flags - \c [in] a bitmask of DRM_SYNCOBJ_WAIT_FLAGS_*
1698 * \param first_signaled - \c [in] self-explanatory
1699 *
1700 * \return 0 on success\n
1701 * -ETIME - Timeout
1702 * <0 - Negative POSIX Error code
1703 *
1704 */
1705int amdgpu_cs_syncobj_timeline_wait(amdgpu_device_handle dev,
1706 uint32_t *handles, uint64_t *points,
1707 unsigned num_handles,
1708 int64_t timeout_nsec, unsigned flags,
1709 uint32_t *first_signaled);
1710/**
1711 * Query sync objects payloads.
1712 *
1713 * \param dev - \c [in] self-explanatory
1714 * \param handles - \c [in] array of sync object handles
1715 * \param points - \c [out] array of sync points returned, which presents
1716 * syncobj payload.
1717 * \param num_handles - \c [in] self-explanatory
1718 *
1719 * \return 0 on success\n
1720 * -ETIME - Timeout
1721 * <0 - Negative POSIX Error code
1722 *
1723 */
1724int amdgpu_cs_syncobj_query(amdgpu_device_handle dev,
1725 uint32_t *handles, uint64_t *points,
1726 unsigned num_handles);
1727/**
1728 * Query sync objects last signaled or submitted point.
1729 *
1730 * \param dev - \c [in] self-explanatory
1731 * \param handles - \c [in] array of sync object handles
1732 * \param points - \c [out] array of sync points returned, which presents
1733 * syncobj payload.
1734 * \param num_handles - \c [in] self-explanatory
1735 * \param flags - \c [in] a bitmask of DRM_SYNCOBJ_QUERY_FLAGS_*
1736 *
1737 * \return 0 on success\n
1738 * -ETIME - Timeout
1739 * <0 - Negative POSIX Error code
1740 *
1741 */
1742int amdgpu_cs_syncobj_query2(amdgpu_device_handle dev,
1743 uint32_t *handles, uint64_t *points,
1744 unsigned num_handles, uint32_t flags);
1745
1746/**
1747 * Export kernel sync object to shareable fd.
1748 *
1749 * \param dev - \c [in] device handle
1750 * \param syncobj - \c [in] sync object handle
1751 * \param shared_fd - \c [out] shared file descriptor.
1752 *
1753 * \return 0 on success\n
1754 * <0 - Negative POSIX Error code
1755 *
1756*/
1757int amdgpu_cs_export_syncobj(amdgpu_device_handle dev,
1758 uint32_t syncobj,
1759 int *shared_fd);
1760/**
1761 * Import kernel sync object from shareable fd.
1762 *
1763 * \param dev - \c [in] device handle
1764 * \param shared_fd - \c [in] shared file descriptor.
1765 * \param syncobj - \c [out] sync object handle
1766 *
1767 * \return 0 on success\n
1768 * <0 - Negative POSIX Error code
1769 *
1770*/
1771int amdgpu_cs_import_syncobj(amdgpu_device_handle dev,
1772 int shared_fd,
1773 uint32_t *syncobj);
1774
1775/**
1776 * Export kernel sync object to a sync_file.
1777 *
1778 * \param dev - \c [in] device handle
1779 * \param syncobj - \c [in] sync object handle
1780 * \param sync_file_fd - \c [out] sync_file file descriptor.
1781 *
1782 * \return 0 on success\n
1783 * <0 - Negative POSIX Error code
1784 *
1785 */
1786int amdgpu_cs_syncobj_export_sync_file(amdgpu_device_handle dev,
1787 uint32_t syncobj,
1788 int *sync_file_fd);
1789
1790/**
1791 * Import kernel sync object from a sync_file.
1792 *
1793 * \param dev - \c [in] device handle
1794 * \param syncobj - \c [in] sync object handle
1795 * \param sync_file_fd - \c [in] sync_file file descriptor.
1796 *
1797 * \return 0 on success\n
1798 * <0 - Negative POSIX Error code
1799 *
1800 */
1801int amdgpu_cs_syncobj_import_sync_file(amdgpu_device_handle dev,
1802 uint32_t syncobj,
1803 int sync_file_fd);
1804/**
1805 * Export kernel timeline sync object to a sync_file.
1806 *
1807 * \param dev - \c [in] device handle
1808 * \param syncobj - \c [in] sync object handle
1809 * \param point - \c [in] timeline point
1810 * \param flags - \c [in] flags
1811 * \param sync_file_fd - \c [out] sync_file file descriptor.
1812 *
1813 * \return 0 on success\n
1814 * <0 - Negative POSIX Error code
1815 *
1816 */
1817int amdgpu_cs_syncobj_export_sync_file2(amdgpu_device_handle dev,
1818 uint32_t syncobj,
1819 uint64_t point,
1820 uint32_t flags,
1821 int *sync_file_fd);
1822
1823/**
1824 * Import kernel timeline sync object from a sync_file.
1825 *
1826 * \param dev - \c [in] device handle
1827 * \param syncobj - \c [in] sync object handle
1828 * \param point - \c [in] timeline point
1829 * \param sync_file_fd - \c [in] sync_file file descriptor.
1830 *
1831 * \return 0 on success\n
1832 * <0 - Negative POSIX Error code
1833 *
1834 */
1835int amdgpu_cs_syncobj_import_sync_file2(amdgpu_device_handle dev,
1836 uint32_t syncobj,
1837 uint64_t point,
1838 int sync_file_fd);
1839
1840/**
1841 * transfer between syncbojs.
1842 *
1843 * \param dev - \c [in] device handle
1844 * \param dst_handle - \c [in] sync object handle
1845 * \param dst_point - \c [in] timeline point, 0 presents dst is binary
1846 * \param src_handle - \c [in] sync object handle
1847 * \param src_point - \c [in] timeline point, 0 presents src is binary
1848 * \param flags - \c [in] flags
1849 *
1850 * \return 0 on success\n
1851 * <0 - Negative POSIX Error code
1852 *
1853 */
1854int amdgpu_cs_syncobj_transfer(amdgpu_device_handle dev,
1855 uint32_t dst_handle,
1856 uint64_t dst_point,
1857 uint32_t src_handle,
1858 uint64_t src_point,
1859 uint32_t flags);
1860
1861/**
1862 * Export an amdgpu fence as a handle (syncobj or fd).
1863 *
1864 * \param what AMDGPU_FENCE_TO_HANDLE_GET_{SYNCOBJ, FD}
1865 * \param out_handle returned handle
1866 *
1867 * \return 0 on success\n
1868 * <0 - Negative POSIX Error code
1869 */
1870int amdgpu_cs_fence_to_handle(amdgpu_device_handle dev,
1871 struct amdgpu_cs_fence *fence,
1872 uint32_t what,
1873 uint32_t *out_handle);
1874
1875/**
1876 * Submit raw command submission to kernel
1877 *
1878 * \param dev - \c [in] device handle
1879 * \param context - \c [in] context handle for context id
1880 * \param bo_list_handle - \c [in] request bo list handle (0 for none)
1881 * \param num_chunks - \c [in] number of CS chunks to submit
1882 * \param chunks - \c [in] array of CS chunks
1883 * \param seq_no - \c [out] output sequence number for submission.
1884 *
1885 * \return 0 on success\n
1886 * <0 - Negative POSIX Error code
1887 *
1888 */
1889struct drm_amdgpu_cs_chunk;
1890struct drm_amdgpu_cs_chunk_dep;
1891struct drm_amdgpu_cs_chunk_data;
1892
1893int amdgpu_cs_submit_raw(amdgpu_device_handle dev,
1894 amdgpu_context_handle context,
1895 amdgpu_bo_list_handle bo_list_handle,
1896 int num_chunks,
1897 struct drm_amdgpu_cs_chunk *chunks,
1898 uint64_t *seq_no);
1899
1900/**
1901 * Submit raw command submission to the kernel with a raw BO list handle.
1902 *
1903 * \param dev - \c [in] device handle
1904 * \param context - \c [in] context handle for context id
1905 * \param bo_list_handle - \c [in] raw bo list handle (0 for none)
1906 * \param num_chunks - \c [in] number of CS chunks to submit
1907 * \param chunks - \c [in] array of CS chunks
1908 * \param seq_no - \c [out] output sequence number for submission.
1909 *
1910 * \return 0 on success\n
1911 * <0 - Negative POSIX Error code
1912 *
1913 * \sa amdgpu_bo_list_create_raw(), amdgpu_bo_list_destroy_raw()
1914 */
1915int amdgpu_cs_submit_raw2(amdgpu_device_handle dev,
1916 amdgpu_context_handle context,
1917 uint32_t bo_list_handle,
1918 int num_chunks,
1919 struct drm_amdgpu_cs_chunk *chunks,
1920 uint64_t *seq_no);
1921
1922void amdgpu_cs_chunk_fence_to_dep(struct amdgpu_cs_fence *fence,
1923 struct drm_amdgpu_cs_chunk_dep *dep);
1924void amdgpu_cs_chunk_fence_info_to_data(struct amdgpu_cs_fence_info *fence_info,
1925 struct drm_amdgpu_cs_chunk_data *data);
1926
1927/**
1928 * Reserve VMID
1929 * \param context - \c [in] GPU Context
1930 * \param flags - \c [in] TBD
1931 *
1932 * \return 0 on success otherwise POSIX Error code
1933*/
1934int amdgpu_vm_reserve_vmid(amdgpu_device_handle dev, uint32_t flags);
1935
1936/**
1937 * Free reserved VMID
1938 * \param context - \c [in] GPU Context
1939 * \param flags - \c [in] TBD
1940 *
1941 * \return 0 on success otherwise POSIX Error code
1942*/
1943int amdgpu_vm_unreserve_vmid(amdgpu_device_handle dev, uint32_t flags);
1944
1945#ifdef __cplusplus
1946}
1947#endif
1948#endif /* #ifdef _AMDGPU_H_ */