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