amdgpu/amdgpu.h

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