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