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