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 struct drm_amdgpu_info_hw_ip; 41 42 /*--------------------------------------------------------------------------*/ 43 /* --------------------------- Defines ------------------------------------ */ 44 /*--------------------------------------------------------------------------*/ 45 46 /** 47 * Define max. number of Command Buffers (IB) which could be sent to the single 48 * hardware IP to accommodate CE/DE requirements 49 * 50 * \sa amdgpu_cs_ib_info 51 */ 52 #define AMDGPU_CS_MAX_IBS_PER_SUBMIT 4 53 54 /** 55 * Special timeout value meaning that the timeout is infinite. 56 */ 57 #define AMDGPU_TIMEOUT_INFINITE 0xffffffffffffffffull 58 59 /** 60 * Used in amdgpu_cs_query_fence_status(), meaning that the given timeout 61 * is absolute. 62 */ 63 #define AMDGPU_QUERY_FENCE_TIMEOUT_IS_ABSOLUTE (1 << 0) 64 65 /*--------------------------------------------------------------------------*/ 66 /* ----------------------------- Enums ------------------------------------ */ 67 /*--------------------------------------------------------------------------*/ 68 69 /** 70 * Enum describing possible handle types 71 * 72 * \sa amdgpu_bo_import, amdgpu_bo_export 73 * 74 */ 75 enum amdgpu_bo_handle_type { 76 /** GEM flink name (needs DRM authentication, used by DRI2) */ 77 amdgpu_bo_handle_type_gem_flink_name = 0, 78 79 /** KMS handle which is used by all driver ioctls */ 80 amdgpu_bo_handle_type_kms = 1, 81 82 /** DMA-buf fd handle */ 83 amdgpu_bo_handle_type_dma_buf_fd = 2 84 }; 85 86 /** Define known types of GPU VM VA ranges */ 87 enum amdgpu_gpu_va_range 88 { 89 /** Allocate from "normal"/general range */ 90 amdgpu_gpu_va_range_general = 0 91 }; 92 93 /*--------------------------------------------------------------------------*/ 94 /* -------------------------- Datatypes ----------------------------------- */ 95 /*--------------------------------------------------------------------------*/ 96 97 /** 98 * Define opaque pointer to context associated with fd. 99 * This context will be returned as the result of 100 * "initialize" function and should be pass as the first 101 * parameter to any API call 102 */ 103 typedef struct amdgpu_device *amdgpu_device_handle; 104 105 /** 106 * Define GPU Context type as pointer to opaque structure 107 * Example of GPU Context is the "rendering" context associated 108 * with OpenGL context (glCreateContext) 109 */ 110 typedef struct amdgpu_context *amdgpu_context_handle; 111 112 /** 113 * Define handle for amdgpu resources: buffer, GDS, etc. 114 */ 115 typedef struct amdgpu_bo *amdgpu_bo_handle; 116 117 /** 118 * Define handle for list of BOs 119 */ 120 typedef struct amdgpu_bo_list *amdgpu_bo_list_handle; 121 122 /** 123 * Define handle to be used to work with VA allocated ranges 124 */ 125 typedef struct amdgpu_va *amdgpu_va_handle; 126 127 /** 128 * Define handle for semaphore 129 */ 130 typedef struct amdgpu_semaphore *amdgpu_semaphore_handle; 131 132 /*--------------------------------------------------------------------------*/ 133 /* -------------------------- Structures ---------------------------------- */ 134 /*--------------------------------------------------------------------------*/ 135 136 /** 137 * Structure describing memory allocation request 138 * 139 * \sa amdgpu_bo_alloc() 140 * 141 */ 142 struct amdgpu_bo_alloc_request { 143 /** Allocation request. It must be aligned correctly. */ 144 uint64_t alloc_size; 145 146 /** 147 * It may be required to have some specific alignment requirements 148 * for physical back-up storage (e.g. for displayable surface). 149 * If 0 there is no special alignment requirement 150 */ 151 uint64_t phys_alignment; 152 153 /** 154 * UMD should specify where to allocate memory and how it 155 * will be accessed by the CPU. 156 */ 157 uint32_t preferred_heap; 158 159 /** Additional flags passed on allocation */ 160 uint64_t flags; 161 }; 162 163 /** 164 * Special UMD specific information associated with buffer. 165 * 166 * It may be need to pass some buffer charactersitic as part 167 * of buffer sharing. Such information are defined UMD and 168 * opaque for libdrm_amdgpu as well for kernel driver. 169 * 170 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_query_info, 171 * amdgpu_bo_import(), amdgpu_bo_export 172 * 173 */ 174 struct amdgpu_bo_metadata { 175 /** Special flag associated with surface */ 176 uint64_t flags; 177 178 /** 179 * ASIC-specific tiling information (also used by DCE). 180 * The encoding is defined by the AMDGPU_TILING_* definitions. 181 */ 182 uint64_t tiling_info; 183 184 /** Size of metadata associated with the buffer, in bytes. */ 185 uint32_t size_metadata; 186 187 /** UMD specific metadata. Opaque for kernel */ 188 uint32_t umd_metadata[64]; 189 }; 190 191 /** 192 * Structure describing allocated buffer. Client may need 193 * to query such information as part of 'sharing' buffers mechanism 194 * 195 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_query_info(), 196 * amdgpu_bo_import(), amdgpu_bo_export() 197 */ 198 struct amdgpu_bo_info { 199 /** Allocated memory size */ 200 uint64_t alloc_size; 201 202 /** 203 * It may be required to have some specific alignment requirements 204 * for physical back-up storage. 205 */ 206 uint64_t phys_alignment; 207 208 /** Heap where to allocate memory. */ 209 uint32_t preferred_heap; 210 211 /** Additional allocation flags. */ 212 uint64_t alloc_flags; 213 214 /** Metadata associated with buffer if any. */ 215 struct amdgpu_bo_metadata metadata; 216 }; 217 218 /** 219 * Structure with information about "imported" buffer 220 * 221 * \sa amdgpu_bo_import() 222 * 223 */ 224 struct amdgpu_bo_import_result { 225 /** Handle of memory/buffer to use */ 226 amdgpu_bo_handle buf_handle; 227 228 /** Buffer size */ 229 uint64_t alloc_size; 230 }; 231 232 /** 233 * 234 * Structure to describe GDS partitioning information. 235 * \note OA and GWS resources are asscoiated with GDS partition 236 * 237 * \sa amdgpu_gpu_resource_query_gds_info 238 * 239 */ 240 struct amdgpu_gds_resource_info { 241 uint32_t gds_gfx_partition_size; 242 uint32_t compute_partition_size; 243 uint32_t gds_total_size; 244 uint32_t gws_per_gfx_partition; 245 uint32_t gws_per_compute_partition; 246 uint32_t oa_per_gfx_partition; 247 uint32_t oa_per_compute_partition; 248 }; 249 250 /** 251 * Structure describing CS fence 252 * 253 * \sa amdgpu_cs_query_fence_status(), amdgpu_cs_request, amdgpu_cs_submit() 254 * 255 */ 256 struct amdgpu_cs_fence { 257 258 /** In which context IB was sent to execution */ 259 amdgpu_context_handle context; 260 261 /** To which HW IP type the fence belongs */ 262 uint32_t ip_type; 263 264 /** IP instance index if there are several IPs of the same type. */ 265 uint32_t ip_instance; 266 267 /** Ring index of the HW IP */ 268 uint32_t ring; 269 270 /** Specify fence for which we need to check submission status.*/ 271 uint64_t fence; 272 }; 273 274 /** 275 * Structure describing IB 276 * 277 * \sa amdgpu_cs_request, amdgpu_cs_submit() 278 * 279 */ 280 struct amdgpu_cs_ib_info { 281 /** Special flags */ 282 uint64_t flags; 283 284 /** Virtual MC address of the command buffer */ 285 uint64_t ib_mc_address; 286 287 /** 288 * Size of Command Buffer to be submitted. 289 * - The size is in units of dwords (4 bytes). 290 * - Could be 0 291 */ 292 uint32_t size; 293 }; 294 295 /** 296 * Structure describing fence information 297 * 298 * \sa amdgpu_cs_request, amdgpu_cs_query_fence, 299 * amdgpu_cs_submit(), amdgpu_cs_query_fence_status() 300 */ 301 struct amdgpu_cs_fence_info { 302 /** buffer object for the fence */ 303 amdgpu_bo_handle handle; 304 305 /** fence offset in the unit of sizeof(uint64_t) */ 306 uint64_t offset; 307 }; 308 309 /** 310 * Structure describing submission request 311 * 312 * \note We could have several IBs as packet. e.g. CE, CE, DE case for gfx 313 * 314 * \sa amdgpu_cs_submit() 315 */ 316 struct amdgpu_cs_request { 317 /** Specify flags with additional information */ 318 uint64_t flags; 319 320 /** Specify HW IP block type to which to send the IB. */ 321 unsigned ip_type; 322 323 /** IP instance index if there are several IPs of the same type. */ 324 unsigned ip_instance; 325 326 /** 327 * Specify ring index of the IP. We could have several rings 328 * in the same IP. E.g. 0 for SDMA0 and 1 for SDMA1. 329 */ 330 uint32_t ring; 331 332 /** 333 * List handle with resources used by this request. 334 */ 335 amdgpu_bo_list_handle resources; 336 337 /** 338 * Number of dependencies this Command submission needs to 339 * wait for before starting execution. 340 */ 341 uint32_t number_of_dependencies; 342 343 /** 344 * Array of dependencies which need to be met before 345 * execution can start. 346 */ 347 struct amdgpu_cs_fence *dependencies; 348 349 /** Number of IBs to submit in the field ibs. */ 350 uint32_t number_of_ibs; 351 352 /** 353 * IBs to submit. Those IBs will be submit together as single entity 354 */ 355 struct amdgpu_cs_ib_info *ibs; 356 357 /** 358 * The returned sequence number for the command submission 359 */ 360 uint64_t seq_no; 361 362 /** 363 * The fence information 364 */ 365 struct amdgpu_cs_fence_info fence_info; 366 }; 367 368 /** 369 * Structure which provide information about GPU VM MC Address space 370 * alignments requirements 371 * 372 * \sa amdgpu_query_buffer_size_alignment 373 */ 374 struct amdgpu_buffer_size_alignments { 375 /** Size alignment requirement for allocation in 376 * local memory */ 377 uint64_t size_local; 378 379 /** 380 * Size alignment requirement for allocation in remote memory 381 */ 382 uint64_t size_remote; 383 }; 384 385 /** 386 * Structure which provide information about heap 387 * 388 * \sa amdgpu_query_heap_info() 389 * 390 */ 391 struct amdgpu_heap_info { 392 /** Theoretical max. available memory in the given heap */ 393 uint64_t heap_size; 394 395 /** 396 * Number of bytes allocated in the heap. This includes all processes 397 * and private allocations in the kernel. It changes when new buffers 398 * are allocated, freed, and moved. It cannot be larger than 399 * heap_size. 400 */ 401 uint64_t heap_usage; 402 403 /** 404 * Theoretical possible max. size of buffer which 405 * could be allocated in the given heap 406 */ 407 uint64_t max_allocation; 408 }; 409 410 /** 411 * Describe GPU h/w info needed for UMD correct initialization 412 * 413 * \sa amdgpu_query_gpu_info() 414 */ 415 struct amdgpu_gpu_info { 416 /** Asic id */ 417 uint32_t asic_id; 418 /** Chip revision */ 419 uint32_t chip_rev; 420 /** Chip external revision */ 421 uint32_t chip_external_rev; 422 /** Family ID */ 423 uint32_t family_id; 424 /** Special flags */ 425 uint64_t ids_flags; 426 /** max engine clock*/ 427 uint64_t max_engine_clk; 428 /** max memory clock */ 429 uint64_t max_memory_clk; 430 /** number of shader engines */ 431 uint32_t num_shader_engines; 432 /** number of shader arrays per engine */ 433 uint32_t num_shader_arrays_per_engine; 434 /** Number of available good shader pipes */ 435 uint32_t avail_quad_shader_pipes; 436 /** Max. number of shader pipes.(including good and bad pipes */ 437 uint32_t max_quad_shader_pipes; 438 /** Number of parameter cache entries per shader quad pipe */ 439 uint32_t cache_entries_per_quad_pipe; 440 /** Number of available graphics context */ 441 uint32_t num_hw_gfx_contexts; 442 /** Number of render backend pipes */ 443 uint32_t rb_pipes; 444 /** Enabled render backend pipe mask */ 445 uint32_t enabled_rb_pipes_mask; 446 /** Frequency of GPU Counter */ 447 uint32_t gpu_counter_freq; 448 /** CC_RB_BACKEND_DISABLE.BACKEND_DISABLE per SE */ 449 uint32_t backend_disable[4]; 450 /** Value of MC_ARB_RAMCFG register*/ 451 uint32_t mc_arb_ramcfg; 452 /** Value of GB_ADDR_CONFIG */ 453 uint32_t gb_addr_cfg; 454 /** Values of the GB_TILE_MODE0..31 registers */ 455 uint32_t gb_tile_mode[32]; 456 /** Values of GB_MACROTILE_MODE0..15 registers */ 457 uint32_t gb_macro_tile_mode[16]; 458 /** Value of PA_SC_RASTER_CONFIG register per SE */ 459 uint32_t pa_sc_raster_cfg[4]; 460 /** Value of PA_SC_RASTER_CONFIG_1 register per SE */ 461 uint32_t pa_sc_raster_cfg1[4]; 462 /* CU info */ 463 uint32_t cu_active_number; 464 uint32_t cu_ao_mask; 465 uint32_t cu_bitmap[4][4]; 466 /* video memory type info*/ 467 uint32_t vram_type; 468 /* video memory bit width*/ 469 uint32_t vram_bit_width; 470 /** constant engine ram size*/ 471 uint32_t ce_ram_size; 472 /* vce harvesting instance */ 473 uint32_t vce_harvest_config; 474 /* PCI revision ID */ 475 uint32_t pci_rev_id; 476 }; 477 478 479 /*--------------------------------------------------------------------------*/ 480 /*------------------------- Functions --------------------------------------*/ 481 /*--------------------------------------------------------------------------*/ 482 483 /* 484 * Initialization / Cleanup 485 * 486 */ 487 488 /** 489 * 490 * \param fd - \c [in] File descriptor for AMD GPU device 491 * received previously as the result of 492 * e.g. drmOpen() call. 493 * For legacy fd type, the DRI2/DRI3 494 * authentication should be done before 495 * calling this function. 496 * \param major_version - \c [out] Major version of library. It is assumed 497 * that adding new functionality will cause 498 * increase in major version 499 * \param minor_version - \c [out] Minor version of library 500 * \param device_handle - \c [out] Pointer to opaque context which should 501 * be passed as the first parameter on each 502 * API call 503 * 504 * 505 * \return 0 on success\n 506 * <0 - Negative POSIX Error code 507 * 508 * 509 * \sa amdgpu_device_deinitialize() 510 */ 511 int amdgpu_device_initialize(int fd, 512 uint32_t *major_version, 513 uint32_t *minor_version, 514 amdgpu_device_handle *device_handle); 515 516 /** 517 * 518 * When access to such library does not needed any more the special 519 * function must be call giving opportunity to clean up any 520 * resources if needed. 521 * 522 * \param device_handle - \c [in] Context associated with file 523 * descriptor for AMD GPU device 524 * received previously as the 525 * result e.g. of drmOpen() call. 526 * 527 * \return 0 on success\n 528 * <0 - Negative POSIX Error code 529 * 530 * \sa amdgpu_device_initialize() 531 * 532 */ 533 int amdgpu_device_deinitialize(amdgpu_device_handle device_handle); 534 535 /* 536 * Memory Management 537 * 538 */ 539 540 /** 541 * Allocate memory to be used by UMD for GPU related operations 542 * 543 * \param dev - \c [in] Device handle. 544 * See #amdgpu_device_initialize() 545 * \param alloc_buffer - \c [in] Pointer to the structure describing an 546 * allocation request 547 * \param buf_handle - \c [out] Allocated buffer handle 548 * 549 * \return 0 on success\n 550 * <0 - Negative POSIX Error code 551 * 552 * \sa amdgpu_bo_free() 553 */ 554 int amdgpu_bo_alloc(amdgpu_device_handle dev, 555 struct amdgpu_bo_alloc_request *alloc_buffer, 556 amdgpu_bo_handle *buf_handle); 557 558 /** 559 * Associate opaque data with buffer to be queried by another UMD 560 * 561 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 562 * \param buf_handle - \c [in] Buffer handle 563 * \param info - \c [in] Metadata to associated with buffer 564 * 565 * \return 0 on success\n 566 * <0 - Negative POSIX Error code 567 */ 568 int amdgpu_bo_set_metadata(amdgpu_bo_handle buf_handle, 569 struct amdgpu_bo_metadata *info); 570 571 /** 572 * Query buffer information including metadata previusly associated with 573 * buffer. 574 * 575 * \param dev - \c [in] Device handle. 576 * See #amdgpu_device_initialize() 577 * \param buf_handle - \c [in] Buffer handle 578 * \param info - \c [out] Structure describing buffer 579 * 580 * \return 0 on success\n 581 * <0 - Negative POSIX Error code 582 * 583 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_alloc() 584 */ 585 int amdgpu_bo_query_info(amdgpu_bo_handle buf_handle, 586 struct amdgpu_bo_info *info); 587 588 /** 589 * Allow others to get access to buffer 590 * 591 * \param dev - \c [in] Device handle. 592 * See #amdgpu_device_initialize() 593 * \param buf_handle - \c [in] Buffer handle 594 * \param type - \c [in] Type of handle requested 595 * \param shared_handle - \c [out] Special "shared" handle 596 * 597 * \return 0 on success\n 598 * <0 - Negative POSIX Error code 599 * 600 * \sa amdgpu_bo_import() 601 * 602 */ 603 int amdgpu_bo_export(amdgpu_bo_handle buf_handle, 604 enum amdgpu_bo_handle_type type, 605 uint32_t *shared_handle); 606 607 /** 608 * Request access to "shared" buffer 609 * 610 * \param dev - \c [in] Device handle. 611 * See #amdgpu_device_initialize() 612 * \param type - \c [in] Type of handle requested 613 * \param shared_handle - \c [in] Shared handle received as result "import" 614 * operation 615 * \param output - \c [out] Pointer to structure with information 616 * about imported buffer 617 * 618 * \return 0 on success\n 619 * <0 - Negative POSIX Error code 620 * 621 * \note Buffer must be "imported" only using new "fd" (different from 622 * one used by "exporter"). 623 * 624 * \sa amdgpu_bo_export() 625 * 626 */ 627 int amdgpu_bo_import(amdgpu_device_handle dev, 628 enum amdgpu_bo_handle_type type, 629 uint32_t shared_handle, 630 struct amdgpu_bo_import_result *output); 631 632 /** 633 * Request GPU access to user allocated memory e.g. via "malloc" 634 * 635 * \param dev - [in] Device handle. See #amdgpu_device_initialize() 636 * \param cpu - [in] CPU address of user allocated memory which we 637 * want to map to GPU address space (make GPU accessible) 638 * (This address must be correctly aligned). 639 * \param size - [in] Size of allocation (must be correctly aligned) 640 * \param buf_handle - [out] Buffer handle for the userptr memory 641 * resource on submission and be used in other operations. 642 * 643 * 644 * \return 0 on success\n 645 * <0 - Negative POSIX Error code 646 * 647 * \note 648 * This call doesn't guarantee that such memory will be persistently 649 * "locked" / make non-pageable. The purpose of this call is to provide 650 * opportunity for GPU get access to this resource during submission. 651 * 652 * The maximum amount of memory which could be mapped in this call depends 653 * if overcommit is disabled or not. If overcommit is disabled than the max. 654 * amount of memory to be pinned will be limited by left "free" size in total 655 * amount of memory which could be locked simultaneously ("GART" size). 656 * 657 * Supported (theoretical) max. size of mapping is restricted only by 658 * "GART" size. 659 * 660 * It is responsibility of caller to correctly specify access rights 661 * on VA assignment. 662 */ 663 int amdgpu_create_bo_from_user_mem(amdgpu_device_handle dev, 664 void *cpu, uint64_t size, 665 amdgpu_bo_handle *buf_handle); 666 667 /** 668 * Free previosuly allocated memory 669 * 670 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 671 * \param buf_handle - \c [in] Buffer handle to free 672 * 673 * \return 0 on success\n 674 * <0 - Negative POSIX Error code 675 * 676 * \note In the case of memory shared between different applications all 677 * resources will be physically freed only all such applications 678 * will be terminated 679 * \note If is UMD responsibility to free buffer only when there is no 680 * more GPU access 681 * 682 * \sa amdgpu_bo_set_metadata(), amdgpu_bo_alloc() 683 * 684 */ 685 int amdgpu_bo_free(amdgpu_bo_handle buf_handle); 686 687 /** 688 * Request CPU access to GPU accessible memory 689 * 690 * \param buf_handle - \c [in] Buffer handle 691 * \param cpu - \c [out] CPU address to be used for access 692 * 693 * \return 0 on success\n 694 * <0 - Negative POSIX Error code 695 * 696 * \sa amdgpu_bo_cpu_unmap() 697 * 698 */ 699 int amdgpu_bo_cpu_map(amdgpu_bo_handle buf_handle, void **cpu); 700 701 /** 702 * Release CPU access to GPU memory 703 * 704 * \param buf_handle - \c [in] Buffer handle 705 * 706 * \return 0 on success\n 707 * <0 - Negative POSIX Error code 708 * 709 * \sa amdgpu_bo_cpu_map() 710 * 711 */ 712 int amdgpu_bo_cpu_unmap(amdgpu_bo_handle buf_handle); 713 714 /** 715 * Wait until a buffer is not used by the device. 716 * 717 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 718 * \param buf_handle - \c [in] Buffer handle. 719 * \param timeout_ns - Timeout in nanoseconds. 720 * \param buffer_busy - 0 if buffer is idle, all GPU access was completed 721 * and no GPU access is scheduled. 722 * 1 GPU access is in fly or scheduled 723 * 724 * \return 0 - on success 725 * <0 - Negative POSIX Error code 726 */ 727 int amdgpu_bo_wait_for_idle(amdgpu_bo_handle buf_handle, 728 uint64_t timeout_ns, 729 bool *buffer_busy); 730 731 /** 732 * Creates a BO list handle for command submission. 733 * 734 * \param dev - \c [in] Device handle. 735 * See #amdgpu_device_initialize() 736 * \param number_of_resources - \c [in] Number of BOs in the list 737 * \param resources - \c [in] List of BO handles 738 * \param resource_prios - \c [in] Optional priority for each handle 739 * \param result - \c [out] Created BO list handle 740 * 741 * \return 0 on success\n 742 * <0 - Negative POSIX Error code 743 * 744 * \sa amdgpu_bo_list_destroy() 745 */ 746 int amdgpu_bo_list_create(amdgpu_device_handle dev, 747 uint32_t number_of_resources, 748 amdgpu_bo_handle *resources, 749 uint8_t *resource_prios, 750 amdgpu_bo_list_handle *result); 751 752 /** 753 * Destroys a BO list handle. 754 * 755 * \param handle - \c [in] BO list handle. 756 * 757 * \return 0 on success\n 758 * <0 - Negative POSIX Error code 759 * 760 * \sa amdgpu_bo_list_create() 761 */ 762 int amdgpu_bo_list_destroy(amdgpu_bo_list_handle handle); 763 764 /** 765 * Update resources for existing BO list 766 * 767 * \param handle - \c [in] BO list handle 768 * \param number_of_resources - \c [in] Number of BOs in the list 769 * \param resources - \c [in] List of BO handles 770 * \param resource_prios - \c [in] Optional priority for each handle 771 * 772 * \return 0 on success\n 773 * <0 - Negative POSIX Error code 774 * 775 * \sa amdgpu_bo_list_update() 776 */ 777 int amdgpu_bo_list_update(amdgpu_bo_list_handle handle, 778 uint32_t number_of_resources, 779 amdgpu_bo_handle *resources, 780 uint8_t *resource_prios); 781 782 /* 783 * GPU Execution context 784 * 785 */ 786 787 /** 788 * Create GPU execution Context 789 * 790 * For the purpose of GPU Scheduler and GPU Robustness extensions it is 791 * necessary to have information/identify rendering/compute contexts. 792 * It also may be needed to associate some specific requirements with such 793 * contexts. Kernel driver will guarantee that submission from the same 794 * context will always be executed in order (first come, first serve). 795 * 796 * 797 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 798 * \param context - \c [out] GPU Context handle 799 * 800 * \return 0 on success\n 801 * <0 - Negative POSIX Error code 802 * 803 * \sa amdgpu_cs_ctx_free() 804 * 805 */ 806 int amdgpu_cs_ctx_create(amdgpu_device_handle dev, 807 amdgpu_context_handle *context); 808 809 /** 810 * 811 * Destroy GPU execution context when not needed any more 812 * 813 * \param context - \c [in] GPU Context handle 814 * 815 * \return 0 on success\n 816 * <0 - Negative POSIX Error code 817 * 818 * \sa amdgpu_cs_ctx_create() 819 * 820 */ 821 int amdgpu_cs_ctx_free(amdgpu_context_handle context); 822 823 /** 824 * Query reset state for the specific GPU Context 825 * 826 * \param context - \c [in] GPU Context handle 827 * \param state - \c [out] One of AMDGPU_CTX_*_RESET 828 * \param hangs - \c [out] Number of hangs caused by the context. 829 * 830 * \return 0 on success\n 831 * <0 - Negative POSIX Error code 832 * 833 * \sa amdgpu_cs_ctx_create() 834 * 835 */ 836 int amdgpu_cs_query_reset_state(amdgpu_context_handle context, 837 uint32_t *state, uint32_t *hangs); 838 839 /* 840 * Command Buffers Management 841 * 842 */ 843 844 /** 845 * Send request to submit command buffers to hardware. 846 * 847 * Kernel driver could use GPU Scheduler to make decision when physically 848 * sent this request to the hardware. Accordingly this request could be put 849 * in queue and sent for execution later. The only guarantee is that request 850 * from the same GPU context to the same ip:ip_instance:ring will be executed in 851 * order. 852 * 853 * The caller can specify the user fence buffer/location with the fence_info in the 854 * cs_request.The sequence number is returned via the 'seq_no' parameter 855 * in ibs_request structure. 856 * 857 * 858 * \param dev - \c [in] Device handle. 859 * See #amdgpu_device_initialize() 860 * \param context - \c [in] GPU Context 861 * \param flags - \c [in] Global submission flags 862 * \param ibs_request - \c [in/out] Pointer to submission requests. 863 * We could submit to the several 864 * engines/rings simulteniously as 865 * 'atomic' operation 866 * \param number_of_requests - \c [in] Number of submission requests 867 * 868 * \return 0 on success\n 869 * <0 - Negative POSIX Error code 870 * 871 * \note It is required to pass correct resource list with buffer handles 872 * which will be accessible by command buffers from submission 873 * This will allow kernel driver to correctly implement "paging". 874 * Failure to do so will have unpredictable results. 875 * 876 * \sa amdgpu_command_buffer_alloc(), amdgpu_command_buffer_free(), 877 * amdgpu_cs_query_fence_status() 878 * 879 */ 880 int amdgpu_cs_submit(amdgpu_context_handle context, 881 uint64_t flags, 882 struct amdgpu_cs_request *ibs_request, 883 uint32_t number_of_requests); 884 885 /** 886 * Query status of Command Buffer Submission 887 * 888 * \param fence - \c [in] Structure describing fence to query 889 * \param timeout_ns - \c [in] Timeout value to wait 890 * \param flags - \c [in] Flags for the query 891 * \param expired - \c [out] If fence expired or not.\n 892 * 0 if fence is not expired\n 893 * !0 - otherwise 894 * 895 * \return 0 on success\n 896 * <0 - Negative POSIX Error code 897 * 898 * \note If UMD wants only to check operation status and returned immediately 899 * then timeout value as 0 must be passed. In this case success will be 900 * returned in the case if submission was completed or timeout error 901 * code. 902 * 903 * \sa amdgpu_cs_submit() 904 */ 905 int amdgpu_cs_query_fence_status(struct amdgpu_cs_fence *fence, 906 uint64_t timeout_ns, 907 uint64_t flags, 908 uint32_t *expired); 909 910 /* 911 * Query / Info API 912 * 913 */ 914 915 /** 916 * Query allocation size alignments 917 * 918 * UMD should query information about GPU VM MC size alignments requirements 919 * to be able correctly choose required allocation size and implement 920 * internal optimization if needed. 921 * 922 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 923 * \param info - \c [out] Pointer to structure to get size alignment 924 * requirements 925 * 926 * \return 0 on success\n 927 * <0 - Negative POSIX Error code 928 * 929 */ 930 int amdgpu_query_buffer_size_alignment(amdgpu_device_handle dev, 931 struct amdgpu_buffer_size_alignments 932 *info); 933 934 /** 935 * Query firmware versions 936 * 937 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 938 * \param fw_type - \c [in] AMDGPU_INFO_FW_* 939 * \param ip_instance - \c [in] Index of the IP block of the same type. 940 * \param index - \c [in] Index of the engine. (for SDMA and MEC) 941 * \param version - \c [out] Pointer to to the "version" return value 942 * \param feature - \c [out] Pointer to to the "feature" return value 943 * 944 * \return 0 on success\n 945 * <0 - Negative POSIX Error code 946 * 947 */ 948 int amdgpu_query_firmware_version(amdgpu_device_handle dev, unsigned fw_type, 949 unsigned ip_instance, unsigned index, 950 uint32_t *version, uint32_t *feature); 951 952 /** 953 * Query the number of HW IP instances of a certain type. 954 * 955 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 956 * \param type - \c [in] Hardware IP block type = AMDGPU_HW_IP_* 957 * \param count - \c [out] Pointer to structure to get information 958 * 959 * \return 0 on success\n 960 * <0 - Negative POSIX Error code 961 */ 962 int amdgpu_query_hw_ip_count(amdgpu_device_handle dev, unsigned type, 963 uint32_t *count); 964 965 /** 966 * Query engine information 967 * 968 * This query allows UMD to query information different engines and their 969 * capabilities. 970 * 971 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 972 * \param type - \c [in] Hardware IP block type = AMDGPU_HW_IP_* 973 * \param ip_instance - \c [in] Index of the IP block of the same type. 974 * \param info - \c [out] Pointer to structure to get information 975 * 976 * \return 0 on success\n 977 * <0 - Negative POSIX Error code 978 */ 979 int amdgpu_query_hw_ip_info(amdgpu_device_handle dev, unsigned type, 980 unsigned ip_instance, 981 struct drm_amdgpu_info_hw_ip *info); 982 983 /** 984 * Query heap information 985 * 986 * This query allows UMD to query potentially available memory resources and 987 * adjust their logic if necessary. 988 * 989 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 990 * \param heap - \c [in] Heap type 991 * \param info - \c [in] Pointer to structure to get needed information 992 * 993 * \return 0 on success\n 994 * <0 - Negative POSIX Error code 995 * 996 */ 997 int amdgpu_query_heap_info(amdgpu_device_handle dev, uint32_t heap, 998 uint32_t flags, struct amdgpu_heap_info *info); 999 1000 /** 1001 * Get the CRTC ID from the mode object ID 1002 * 1003 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 1004 * \param id - \c [in] Mode object ID 1005 * \param result - \c [in] Pointer to the CRTC ID 1006 * 1007 * \return 0 on success\n 1008 * <0 - Negative POSIX Error code 1009 * 1010 */ 1011 int amdgpu_query_crtc_from_id(amdgpu_device_handle dev, unsigned id, 1012 int32_t *result); 1013 1014 /** 1015 * Query GPU H/w Info 1016 * 1017 * Query hardware specific information 1018 * 1019 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 1020 * \param heap - \c [in] Heap type 1021 * \param info - \c [in] Pointer to structure to get needed information 1022 * 1023 * \return 0 on success\n 1024 * <0 - Negative POSIX Error code 1025 * 1026 */ 1027 int amdgpu_query_gpu_info(amdgpu_device_handle dev, 1028 struct amdgpu_gpu_info *info); 1029 1030 /** 1031 * Query hardware or driver information. 1032 * 1033 * The return size is query-specific and depends on the "info_id" parameter. 1034 * No more than "size" bytes is returned. 1035 * 1036 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 1037 * \param info_id - \c [in] AMDGPU_INFO_* 1038 * \param size - \c [in] Size of the returned value. 1039 * \param value - \c [out] Pointer to the return value. 1040 * 1041 * \return 0 on success\n 1042 * <0 - Negative POSIX error code 1043 * 1044 */ 1045 int amdgpu_query_info(amdgpu_device_handle dev, unsigned info_id, 1046 unsigned size, void *value); 1047 1048 /** 1049 * Query information about GDS 1050 * 1051 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 1052 * \param gds_info - \c [out] Pointer to structure to get GDS information 1053 * 1054 * \return 0 on success\n 1055 * <0 - Negative POSIX Error code 1056 * 1057 */ 1058 int amdgpu_query_gds_info(amdgpu_device_handle dev, 1059 struct amdgpu_gds_resource_info *gds_info); 1060 1061 /** 1062 * Read a set of consecutive memory-mapped registers. 1063 * Not all registers are allowed to be read by userspace. 1064 * 1065 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize( 1066 * \param dword_offset - \c [in] Register offset in dwords 1067 * \param count - \c [in] The number of registers to read starting 1068 * from the offset 1069 * \param instance - \c [in] GRBM_GFX_INDEX selector. It may have other 1070 * uses. Set it to 0xffffffff if unsure. 1071 * \param flags - \c [in] Flags with additional information. 1072 * \param values - \c [out] The pointer to return values. 1073 * 1074 * \return 0 on success\n 1075 * <0 - Negative POSIX error code 1076 * 1077 */ 1078 int amdgpu_read_mm_registers(amdgpu_device_handle dev, unsigned dword_offset, 1079 unsigned count, uint32_t instance, uint32_t flags, 1080 uint32_t *values); 1081 1082 /** 1083 * Flag to request VA address range in the 32bit address space 1084 */ 1085 #define AMDGPU_VA_RANGE_32_BIT 0x1 1086 1087 /** 1088 * Allocate virtual address range 1089 * 1090 * \param dev - [in] Device handle. See #amdgpu_device_initialize() 1091 * \param va_range_type - \c [in] Type of MC va range from which to allocate 1092 * \param size - \c [in] Size of range. Size must be correctly* aligned. 1093 * It is client responsibility to correctly aligned size based on the future 1094 * usage of allocated range. 1095 * \param va_base_alignment - \c [in] Overwrite base address alignment 1096 * requirement for GPU VM MC virtual 1097 * address assignment. Must be multiple of size alignments received as 1098 * 'amdgpu_buffer_size_alignments'. 1099 * If 0 use the default one. 1100 * \param va_base_required - \c [in] Specified required va base address. 1101 * If 0 then library choose available one. 1102 * If !0 value will be passed and those value already "in use" then 1103 * corresponding error status will be returned. 1104 * \param va_base_allocated - \c [out] On return: Allocated VA base to be used 1105 * by client. 1106 * \param va_range_handle - \c [out] On return: Handle assigned to allocation 1107 * \param flags - \c [in] flags for special VA range 1108 * 1109 * \return 0 on success\n 1110 * >0 - AMD specific error code\n 1111 * <0 - Negative POSIX Error code 1112 * 1113 * \notes \n 1114 * It is client responsibility to correctly handle VA assignments and usage. 1115 * Neither kernel driver nor libdrm_amdpgu are able to prevent and 1116 * detect wrong va assignemnt. 1117 * 1118 * It is client responsibility to correctly handle multi-GPU cases and to pass 1119 * the corresponding arrays of all devices handles where corresponding VA will 1120 * be used. 1121 * 1122 */ 1123 int amdgpu_va_range_alloc(amdgpu_device_handle dev, 1124 enum amdgpu_gpu_va_range va_range_type, 1125 uint64_t size, 1126 uint64_t va_base_alignment, 1127 uint64_t va_base_required, 1128 uint64_t *va_base_allocated, 1129 amdgpu_va_handle *va_range_handle, 1130 uint64_t flags); 1131 1132 /** 1133 * Free previously allocated virtual address range 1134 * 1135 * 1136 * \param va_range_handle - \c [in] Handle assigned to VA allocation 1137 * 1138 * \return 0 on success\n 1139 * >0 - AMD specific error code\n 1140 * <0 - Negative POSIX Error code 1141 * 1142 */ 1143 int amdgpu_va_range_free(amdgpu_va_handle va_range_handle); 1144 1145 /** 1146 * Query virtual address range 1147 * 1148 * UMD can query GPU VM range supported by each device 1149 * to initialize its own VAM accordingly. 1150 * 1151 * \param dev - [in] Device handle. See #amdgpu_device_initialize() 1152 * \param type - \c [in] Type of virtual address range 1153 * \param offset - \c [out] Start offset of virtual address range 1154 * \param size - \c [out] Size of virtual address range 1155 * 1156 * \return 0 on success\n 1157 * <0 - Negative POSIX Error code 1158 * 1159 */ 1160 1161 int amdgpu_va_range_query(amdgpu_device_handle dev, 1162 enum amdgpu_gpu_va_range type, 1163 uint64_t *start, 1164 uint64_t *end); 1165 1166 /** 1167 * VA mapping/unmapping for the buffer object 1168 * 1169 * \param bo - \c [in] BO handle 1170 * \param offset - \c [in] Start offset to map 1171 * \param size - \c [in] Size to map 1172 * \param addr - \c [in] Start virtual address. 1173 * \param flags - \c [in] Supported flags for mapping/unmapping 1174 * \param ops - \c [in] AMDGPU_VA_OP_MAP or AMDGPU_VA_OP_UNMAP 1175 * 1176 * \return 0 on success\n 1177 * <0 - Negative POSIX Error code 1178 * 1179 */ 1180 1181 int amdgpu_bo_va_op(amdgpu_bo_handle bo, 1182 uint64_t offset, 1183 uint64_t size, 1184 uint64_t addr, 1185 uint64_t flags, 1186 uint32_t ops); 1187 1188 /** 1189 * create semaphore 1190 * 1191 * \param sem - \c [out] semaphore handle 1192 * 1193 * \return 0 on success\n 1194 * <0 - Negative POSIX Error code 1195 * 1196 */ 1197 int amdgpu_cs_create_semaphore(amdgpu_semaphore_handle *sem); 1198 1199 /** 1200 * signal semaphore 1201 * 1202 * \param context - \c [in] GPU Context 1203 * \param ip_type - \c [in] Hardware IP block type = AMDGPU_HW_IP_* 1204 * \param ip_instance - \c [in] Index of the IP block of the same type 1205 * \param ring - \c [in] Specify ring index of the IP 1206 * \param sem - \c [in] semaphore handle 1207 * 1208 * \return 0 on success\n 1209 * <0 - Negative POSIX Error code 1210 * 1211 */ 1212 int amdgpu_cs_signal_semaphore(amdgpu_context_handle ctx, 1213 uint32_t ip_type, 1214 uint32_t ip_instance, 1215 uint32_t ring, 1216 amdgpu_semaphore_handle sem); 1217 1218 /** 1219 * wait semaphore 1220 * 1221 * \param context - \c [in] GPU Context 1222 * \param ip_type - \c [in] Hardware IP block type = AMDGPU_HW_IP_* 1223 * \param ip_instance - \c [in] Index of the IP block of the same type 1224 * \param ring - \c [in] Specify ring index of the IP 1225 * \param sem - \c [in] semaphore handle 1226 * 1227 * \return 0 on success\n 1228 * <0 - Negative POSIX Error code 1229 * 1230 */ 1231 int amdgpu_cs_wait_semaphore(amdgpu_context_handle ctx, 1232 uint32_t ip_type, 1233 uint32_t ip_instance, 1234 uint32_t ring, 1235 amdgpu_semaphore_handle sem); 1236 1237 /** 1238 * destroy semaphore 1239 * 1240 * \param sem - \c [in] semaphore handle 1241 * 1242 * \return 0 on success\n 1243 * <0 - Negative POSIX Error code 1244 * 1245 */ 1246 int amdgpu_cs_destroy_semaphore(amdgpu_semaphore_handle sem); 1247 1248 /** 1249 * Get the ASIC marketing name 1250 * 1251 * \param dev - \c [in] Device handle. See #amdgpu_device_initialize() 1252 * 1253 * \return the constant string of the marketing name 1254 * "NULL" means the ASIC is not found 1255 */ 1256 const char *amdgpu_get_marketing_name(amdgpu_device_handle dev); 1257 1258 #endif /* #ifdef _AMDGPU_H_ */ 1259
