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