amdgpu/amdgpu.h

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