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