include/uapi/misc/habanalabs.h

   1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
   2  *
   3  * Copyright 2016-2018 HabanaLabs, Ltd.
   4  * All Rights Reserved.
   5  *
   6  */
   7
   8 #ifndef HABANALABS_H_
   9 #define HABANALABS_H_
  10
  11 #include <linux/types.h>
  12 #include <linux/ioctl.h>
  13
  14 /*
  15  * Defines that are asic-specific but constitutes as ABI between kernel driver
  16  * and userspace
  17  */
  18 #define GOYA_KMD_SRAM_RESERVED_SIZE_FROM_START  0x8000  /* 32KB */
  19
  20 /*
  21  * Queue Numbering
  22  *
  23  * The external queues (DMA channels + CPU) MUST be before the internal queues
  24  * and each group (DMA channels + CPU and internal) must be contiguous inside
  25  * itself but there can be a gap between the two groups (although not
  26  * recommended)
  27  */
  28
  29 enum goya_queue_id {
  30         GOYA_QUEUE_ID_DMA_0 = 0,
  31         GOYA_QUEUE_ID_DMA_1,
  32         GOYA_QUEUE_ID_DMA_2,
  33         GOYA_QUEUE_ID_DMA_3,
  34         GOYA_QUEUE_ID_DMA_4,
  35         GOYA_QUEUE_ID_CPU_PQ,
  36         GOYA_QUEUE_ID_MME,
  37         GOYA_QUEUE_ID_TPC0,
  38         GOYA_QUEUE_ID_TPC1,
  39         GOYA_QUEUE_ID_TPC2,
  40         GOYA_QUEUE_ID_TPC3,
  41         GOYA_QUEUE_ID_TPC4,
  42         GOYA_QUEUE_ID_TPC5,
  43         GOYA_QUEUE_ID_TPC6,
  44         GOYA_QUEUE_ID_TPC7,
  45         GOYA_QUEUE_ID_SIZE
  46 };
  47
  48 /* Opcode for management ioctl */
  49 #define HL_INFO_HW_IP_INFO      0
  50 #define HL_INFO_HW_EVENTS       1
  51 #define HL_INFO_DRAM_USAGE      2
  52 #define HL_INFO_HW_IDLE         3
  53
  54 #define HL_INFO_VERSION_MAX_LEN 128
  55
  56 struct hl_info_hw_ip_info {
  57         __u64 sram_base_address;
  58         __u64 dram_base_address;
  59         __u64 dram_size;
  60         __u32 sram_size;
  61         __u32 num_of_events;
  62         __u32 device_id; /* PCI Device ID */
  63         __u32 reserved[3];
  64         __u32 armcp_cpld_version;
  65         __u32 psoc_pci_pll_nr;
  66         __u32 psoc_pci_pll_nf;
  67         __u32 psoc_pci_pll_od;
  68         __u32 psoc_pci_pll_div_factor;
  69         __u8 tpc_enabled_mask;
  70         __u8 dram_enabled;
  71         __u8 pad[2];
  72         __u8 armcp_version[HL_INFO_VERSION_MAX_LEN];
  73 };
  74
  75 struct hl_info_dram_usage {
  76         __u64 dram_free_mem;
  77         __u64 ctx_dram_mem;
  78 };
  79
  80 struct hl_info_hw_idle {
  81         __u32 is_idle;
  82         __u32 pad;
  83 };
  84
  85 struct hl_info_args {
  86         /* Location of relevant struct in userspace */
  87         __u64 return_pointer;
  88         /*
  89          * The size of the return value. Just like "size" in "snprintf",
  90          * it limits how many bytes the kernel can write
  91          *
  92          * For hw_events array, the size should be
  93          * hl_info_hw_ip_info.num_of_events * sizeof(__u32)
  94          */
  95         __u32 return_size;
  96
  97         /* HL_INFO_* */
  98         __u32 op;
  99
 100         /* Context ID - Currently not in use */
 101         __u32 ctx_id;
 102         __u32 pad;
 103 };
 104
 105 /* Opcode to create a new command buffer */
 106 #define HL_CB_OP_CREATE         0
 107 /* Opcode to destroy previously created command buffer */
 108 #define HL_CB_OP_DESTROY        1
 109
 110 struct hl_cb_in {
 111         /* Handle of CB or 0 if we want to create one */
 112         __u64 cb_handle;
 113         /* HL_CB_OP_* */
 114         __u32 op;
 115         /* Size of CB. Maximum size is 2MB. The minimum size that will be
 116          * allocated, regardless of this parameter's value, is PAGE_SIZE
 117          */
 118         __u32 cb_size;
 119         /* Context ID - Currently not in use */
 120         __u32 ctx_id;
 121         __u32 pad;
 122 };
 123
 124 struct hl_cb_out {
 125         /* Handle of CB */
 126         __u64 cb_handle;
 127 };
 128
 129 union hl_cb_args {
 130         struct hl_cb_in in;
 131         struct hl_cb_out out;
 132 };
 133
 134 /*
 135  * This structure size must always be fixed to 64-bytes for backward
 136  * compatibility
 137  */
 138 struct hl_cs_chunk {
 139         /*
 140          * For external queue, this represents a Handle of CB on the Host
 141          * For internal queue, this represents an SRAM or DRAM address of the
 142          * internal CB
 143          */
 144         __u64 cb_handle;
 145         /* Index of queue to put the CB on */
 146         __u32 queue_index;
 147         /*
 148          * Size of command buffer with valid packets
 149          * Can be smaller then actual CB size
 150          */
 151         __u32 cb_size;
 152         /* HL_CS_CHUNK_FLAGS_* */
 153         __u32 cs_chunk_flags;
 154         /* Align structure to 64 bytes */
 155         __u32 pad[11];
 156 };
 157
 158 #define HL_CS_FLAGS_FORCE_RESTORE       0x1
 159
 160 #define HL_CS_STATUS_SUCCESS            0
 161
 162 struct hl_cs_in {
 163         /* this holds address of array of hl_cs_chunk for restore phase */
 164         __u64 chunks_restore;
 165         /* this holds address of array of hl_cs_chunk for execution phase */
 166         __u64 chunks_execute;
 167         /* this holds address of array of hl_cs_chunk for store phase -
 168          * Currently not in use
 169          */
 170         __u64 chunks_store;
 171         /* Number of chunks in restore phase array */
 172         __u32 num_chunks_restore;
 173         /* Number of chunks in execution array */
 174         __u32 num_chunks_execute;
 175         /* Number of chunks in restore phase array - Currently not in use */
 176         __u32 num_chunks_store;
 177         /* HL_CS_FLAGS_* */
 178         __u32 cs_flags;
 179         /* Context ID - Currently not in use */
 180         __u32 ctx_id;
 181 };
 182
 183 struct hl_cs_out {
 184         /* this holds the sequence number of the CS to pass to wait ioctl */
 185         __u64 seq;
 186         /* HL_CS_STATUS_* */
 187         __u32 status;
 188         __u32 pad;
 189 };
 190
 191 union hl_cs_args {
 192         struct hl_cs_in in;
 193         struct hl_cs_out out;
 194 };
 195
 196 struct hl_wait_cs_in {
 197         /* Command submission sequence number */
 198         __u64 seq;
 199         /* Absolute timeout to wait in microseconds */
 200         __u64 timeout_us;
 201         /* Context ID - Currently not in use */
 202         __u32 ctx_id;
 203         __u32 pad;
 204 };
 205
 206 #define HL_WAIT_CS_STATUS_COMPLETED     0
 207 #define HL_WAIT_CS_STATUS_BUSY          1
 208 #define HL_WAIT_CS_STATUS_TIMEDOUT      2
 209 #define HL_WAIT_CS_STATUS_ABORTED       3
 210 #define HL_WAIT_CS_STATUS_INTERRUPTED   4
 211
 212 struct hl_wait_cs_out {
 213         /* HL_WAIT_CS_STATUS_* */
 214         __u32 status;
 215         __u32 pad;
 216 };
 217
 218 union hl_wait_cs_args {
 219         struct hl_wait_cs_in in;
 220         struct hl_wait_cs_out out;
 221 };
 222
 223 /* Opcode to alloc device memory */
 224 #define HL_MEM_OP_ALLOC                 0
 225 /* Opcode to free previously allocated device memory */
 226 #define HL_MEM_OP_FREE                  1
 227 /* Opcode to map host memory */
 228 #define HL_MEM_OP_MAP                   2
 229 /* Opcode to unmap previously mapped host memory */
 230 #define HL_MEM_OP_UNMAP                 3
 231
 232 /* Memory flags */
 233 #define HL_MEM_CONTIGUOUS       0x1
 234 #define HL_MEM_SHARED           0x2
 235 #define HL_MEM_USERPTR          0x4
 236
 237 struct hl_mem_in {
 238         union {
 239                 /* HL_MEM_OP_ALLOC- allocate device memory */
 240                 struct {
 241                         /* Size to alloc */
 242                         __u64 mem_size;
 243                 } alloc;
 244
 245                 /* HL_MEM_OP_FREE - free device memory */
 246                 struct {
 247                         /* Handle returned from HL_MEM_OP_ALLOC */
 248                         __u64 handle;
 249                 } free;
 250
 251                 /* HL_MEM_OP_MAP - map device memory */
 252                 struct {
 253                         /*
 254                          * Requested virtual address of mapped memory.
 255                          * KMD will try to map the requested region to this
 256                          * hint address, as long as the address is valid and
 257                          * not already mapped. The user should check the
 258                          * returned address of the IOCTL to make sure he got
 259                          * the hint address. Passing 0 here means that KMD
 260                          * will choose the address itself.
 261                          */
 262                         __u64 hint_addr;
 263                         /* Handle returned from HL_MEM_OP_ALLOC */
 264                         __u64 handle;
 265                 } map_device;
 266
 267                 /* HL_MEM_OP_MAP - map host memory */
 268                 struct {
 269                         /* Address of allocated host memory */
 270                         __u64 host_virt_addr;
 271                         /*
 272                          * Requested virtual address of mapped memory.
 273                          * KMD will try to map the requested region to this
 274                          * hint address, as long as the address is valid and
 275                          * not already mapped. The user should check the
 276                          * returned address of the IOCTL to make sure he got
 277                          * the hint address. Passing 0 here means that KMD
 278                          * will choose the address itself.
 279                          */
 280                         __u64 hint_addr;
 281                         /* Size of allocated host memory */
 282                         __u64 mem_size;
 283                 } map_host;
 284
 285                 /* HL_MEM_OP_UNMAP - unmap host memory */
 286                 struct {
 287                         /* Virtual address returned from HL_MEM_OP_MAP */
 288                         __u64 device_virt_addr;
 289                 } unmap;
 290         };
 291
 292         /* HL_MEM_OP_* */
 293         __u32 op;
 294         /* HL_MEM_* flags */
 295         __u32 flags;
 296         /* Context ID - Currently not in use */
 297         __u32 ctx_id;
 298         __u32 pad;
 299 };
 300
 301 struct hl_mem_out {
 302         union {
 303                 /*
 304                  * Used for HL_MEM_OP_MAP as the virtual address that was
 305                  * assigned in the device VA space.
 306                  * A value of 0 means the requested operation failed.
 307                  */
 308                 __u64 device_virt_addr;
 309
 310                 /*
 311                  * Used for HL_MEM_OP_ALLOC. This is the assigned
 312                  * handle for the allocated memory
 313                  */
 314                 __u64 handle;
 315         };
 316 };
 317
 318 union hl_mem_args {
 319         struct hl_mem_in in;
 320         struct hl_mem_out out;
 321 };
 322
 323 /*
 324  * Various information operations such as:
 325  * - H/W IP information
 326  * - Current dram usage
 327  *
 328  * The user calls this IOCTL with an opcode that describes the required
 329  * information. The user should supply a pointer to a user-allocated memory
 330  * chunk, which will be filled by the driver with the requested information.
 331  *
 332  * The user supplies the maximum amount of size to copy into the user's memory,
 333  * in order to prevent data corruption in case of differences between the
 334  * definitions of structures in kernel and userspace, e.g. in case of old
 335  * userspace and new kernel driver
 336  */
 337 #define HL_IOCTL_INFO   \
 338                 _IOWR('H', 0x01, struct hl_info_args)
 339
 340 /*
 341  * Command Buffer
 342  * - Request a Command Buffer
 343  * - Destroy a Command Buffer
 344  *
 345  * The command buffers are memory blocks that reside in DMA-able address
 346  * space and are physically contiguous so they can be accessed by the device
 347  * directly. They are allocated using the coherent DMA API.
 348  *
 349  * When creating a new CB, the IOCTL returns a handle of it, and the user-space
 350  * process needs to use that handle to mmap the buffer so it can access them.
 351  *
 352  */
 353 #define HL_IOCTL_CB             \
 354                 _IOWR('H', 0x02, union hl_cb_args)
 355
 356 /*
 357  * Command Submission
 358  *
 359  * To submit work to the device, the user need to call this IOCTL with a set
 360  * of JOBS. That set of JOBS constitutes a CS object.
 361  * Each JOB will be enqueued on a specific queue, according to the user's input.
 362  * There can be more then one JOB per queue.
 363  *
 364  * There are two types of queues - external and internal. External queues
 365  * are DMA queues which transfer data from/to the Host. All other queues are
 366  * internal. The driver will get completion notifications from the device only
 367  * on JOBS which are enqueued in the external queues.
 368  *
 369  * For jobs on external queues, the user needs to create command buffers
 370  * through the CB ioctl and give the CB's handle to the CS ioctl. For jobs on
 371  * internal queues, the user needs to prepare a "command buffer" with packets
 372  * on either the SRAM or DRAM, and give the device address of that buffer to
 373  * the CS ioctl.
 374  *
 375  * This IOCTL is asynchronous in regard to the actual execution of the CS. This
 376  * means it returns immediately after ALL the JOBS were enqueued on their
 377  * relevant queues. Therefore, the user mustn't assume the CS has been completed
 378  * or has even started to execute.
 379  *
 380  * Upon successful enqueue, the IOCTL returns an opaque handle which the user
 381  * can use with the "Wait for CS" IOCTL to check whether the handle's CS
 382  * external JOBS have been completed. Note that if the CS has internal JOBS
 383  * which can execute AFTER the external JOBS have finished, the driver might
 384  * report that the CS has finished executing BEFORE the internal JOBS have
 385  * actually finish executing.
 386  *
 387  * The CS IOCTL will receive three sets of JOBS. One set is for "restore" phase,
 388  * a second set is for "execution" phase and a third set is for "store" phase.
 389  * The JOBS on the "restore" phase are enqueued only after context-switch
 390  * (or if its the first CS for this context). The user can also order the
 391  * driver to run the "restore" phase explicitly
 392  *
 393  */
 394 #define HL_IOCTL_CS                     \
 395                 _IOWR('H', 0x03, union hl_cs_args)
 396
 397 /*
 398  * Wait for Command Submission
 399  *
 400  * The user can call this IOCTL with a handle it received from the CS IOCTL
 401  * to wait until the handle's CS has finished executing. The user will wait
 402  * inside the kernel until the CS has finished or until the user-requeusted
 403  * timeout has expired.
 404  *
 405  * The return value of the IOCTL is a standard Linux error code. The possible
 406  * values are:
 407  *
 408  * EINTR     - Kernel waiting has been interrupted, e.g. due to OS signal
 409  *             that the user process received
 410  * ETIMEDOUT - The CS has caused a timeout on the device
 411  * EIO       - The CS was aborted (usually because the device was reset)
 412  * ENODEV    - The device wants to do hard-reset (so user need to close FD)
 413  *
 414  * The driver also returns a custom define inside the IOCTL which can be:
 415  *
 416  * HL_WAIT_CS_STATUS_COMPLETED   - The CS has been completed successfully (0)
 417  * HL_WAIT_CS_STATUS_BUSY        - The CS is still executing (0)
 418  * HL_WAIT_CS_STATUS_TIMEDOUT    - The CS has caused a timeout on the device
 419  *                                 (ETIMEDOUT)
 420  * HL_WAIT_CS_STATUS_ABORTED     - The CS was aborted, usually because the
 421  *                                 device was reset (EIO)
 422  * HL_WAIT_CS_STATUS_INTERRUPTED - Waiting for the CS was interrupted (EINTR)
 423  *
 424  */
 425
 426 #define HL_IOCTL_WAIT_CS                        \
 427                 _IOWR('H', 0x04, union hl_wait_cs_args)
 428
 429 /*
 430  * Memory
 431  * - Map host memory to device MMU
 432  * - Unmap host memory from device MMU
 433  *
 434  * This IOCTL allows the user to map host memory to the device MMU
 435  *
 436  * For host memory, the IOCTL doesn't allocate memory. The user is supposed
 437  * to allocate the memory in user-space (malloc/new). The driver pins the
 438  * physical pages (up to the allowed limit by the OS), assigns a virtual
 439  * address in the device VA space and initializes the device MMU.
 440  *
 441  * There is an option for the user to specify the requested virtual address.
 442  *
 443  */
 444 #define HL_IOCTL_MEMORY         \
 445                 _IOWR('H', 0x05, union hl_mem_args)
 446
 447 #define HL_COMMAND_START        0x01
 448 #define HL_COMMAND_END          0x06
 449
 450 #endif /* HABANALABS_H_ */