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. Minimum requested size must be PAGE_SIZE */
 116         __u32 cb_size;
 117         /* Context ID - Currently not in use */
 118         __u32 ctx_id;
 119         __u32 pad;
 120 };
 121
 122 struct hl_cb_out {
 123         /* Handle of CB */
 124         __u64 cb_handle;
 125 };
 126
 127 union hl_cb_args {
 128         struct hl_cb_in in;
 129         struct hl_cb_out out;
 130 };
 131
 132 /*
 133  * This structure size must always be fixed to 64-bytes for backward
 134  * compatibility
 135  */
 136 struct hl_cs_chunk {
 137         /*
 138          * For external queue, this represents a Handle of CB on the Host
 139          * For internal queue, this represents an SRAM or DRAM address of the
 140          * internal CB
 141          */
 142         __u64 cb_handle;
 143         /* Index of queue to put the CB on */
 144         __u32 queue_index;
 145         /*
 146          * Size of command buffer with valid packets
 147          * Can be smaller then actual CB size
 148          */
 149         __u32 cb_size;
 150         /* HL_CS_CHUNK_FLAGS_* */
 151         __u32 cs_chunk_flags;
 152         /* Align structure to 64 bytes */
 153         __u32 pad[11];
 154 };
 155
 156 #define HL_CS_FLAGS_FORCE_RESTORE       0x1
 157
 158 #define HL_CS_STATUS_SUCCESS            0
 159
 160 struct hl_cs_in {
 161         /* this holds address of array of hl_cs_chunk for restore phase */
 162         __u64 chunks_restore;
 163         /* this holds address of array of hl_cs_chunk for execution phase */
 164         __u64 chunks_execute;
 165         /* this holds address of array of hl_cs_chunk for store phase -
 166          * Currently not in use
 167          */
 168         __u64 chunks_store;
 169         /* Number of chunks in restore phase array */
 170         __u32 num_chunks_restore;
 171         /* Number of chunks in execution array */
 172         __u32 num_chunks_execute;
 173         /* Number of chunks in restore phase array - Currently not in use */
 174         __u32 num_chunks_store;
 175         /* HL_CS_FLAGS_* */
 176         __u32 cs_flags;
 177         /* Context ID - Currently not in use */
 178         __u32 ctx_id;
 179 };
 180
 181 struct hl_cs_out {
 182         /* this holds the sequence number of the CS to pass to wait ioctl */
 183         __u64 seq;
 184         /* HL_CS_STATUS_* */
 185         __u32 status;
 186         __u32 pad;
 187 };
 188
 189 union hl_cs_args {
 190         struct hl_cs_in in;
 191         struct hl_cs_out out;
 192 };
 193
 194 struct hl_wait_cs_in {
 195         /* Command submission sequence number */
 196         __u64 seq;
 197         /* Absolute timeout to wait in microseconds */
 198         __u64 timeout_us;
 199         /* Context ID - Currently not in use */
 200         __u32 ctx_id;
 201         __u32 pad;
 202 };
 203
 204 #define HL_WAIT_CS_STATUS_COMPLETED     0
 205 #define HL_WAIT_CS_STATUS_BUSY          1
 206 #define HL_WAIT_CS_STATUS_TIMEDOUT      2
 207 #define HL_WAIT_CS_STATUS_ABORTED       3
 208 #define HL_WAIT_CS_STATUS_INTERRUPTED   4
 209
 210 struct hl_wait_cs_out {
 211         /* HL_WAIT_CS_STATUS_* */
 212         __u32 status;
 213         __u32 pad;
 214 };
 215
 216 union hl_wait_cs_args {
 217         struct hl_wait_cs_in in;
 218         struct hl_wait_cs_out out;
 219 };
 220
 221 /* Opcode to alloc device memory */
 222 #define HL_MEM_OP_ALLOC                 0
 223 /* Opcode to free previously allocated device memory */
 224 #define HL_MEM_OP_FREE                  1
 225 /* Opcode to map host memory */
 226 #define HL_MEM_OP_MAP                   2
 227 /* Opcode to unmap previously mapped host memory */
 228 #define HL_MEM_OP_UNMAP                 3
 229
 230 /* Memory flags */
 231 #define HL_MEM_CONTIGUOUS       0x1
 232 #define HL_MEM_SHARED           0x2
 233 #define HL_MEM_USERPTR          0x4
 234
 235 struct hl_mem_in {
 236         union {
 237                 /* HL_MEM_OP_ALLOC- allocate device memory */
 238                 struct {
 239                         /* Size to alloc */
 240                         __u64 mem_size;
 241                 } alloc;
 242
 243                 /* HL_MEM_OP_FREE - free device memory */
 244                 struct {
 245                         /* Handle returned from HL_MEM_OP_ALLOC */
 246                         __u64 handle;
 247                 } free;
 248
 249                 /* HL_MEM_OP_MAP - map device memory */
 250                 struct {
 251                         /*
 252                          * Requested virtual address of mapped memory.
 253                          * KMD will try to map the requested region to this
 254                          * hint address, as long as the address is valid and
 255                          * not already mapped. The user should check the
 256                          * returned address of the IOCTL to make sure he got
 257                          * the hint address. Passing 0 here means that KMD
 258                          * will choose the address itself.
 259                          */
 260                         __u64 hint_addr;
 261                         /* Handle returned from HL_MEM_OP_ALLOC */
 262                         __u64 handle;
 263                 } map_device;
 264
 265                 /* HL_MEM_OP_MAP - map host memory */
 266                 struct {
 267                         /* Address of allocated host memory */
 268                         __u64 host_virt_addr;
 269                         /*
 270                          * Requested virtual address of mapped memory.
 271                          * KMD will try to map the requested region to this
 272                          * hint address, as long as the address is valid and
 273                          * not already mapped. The user should check the
 274                          * returned address of the IOCTL to make sure he got
 275                          * the hint address. Passing 0 here means that KMD
 276                          * will choose the address itself.
 277                          */
 278                         __u64 hint_addr;
 279                         /* Size of allocated host memory */
 280                         __u64 mem_size;
 281                 } map_host;
 282
 283                 /* HL_MEM_OP_UNMAP - unmap host memory */
 284                 struct {
 285                         /* Virtual address returned from HL_MEM_OP_MAP */
 286                         __u64 device_virt_addr;
 287                 } unmap;
 288         };
 289
 290         /* HL_MEM_OP_* */
 291         __u32 op;
 292         /* HL_MEM_* flags */
 293         __u32 flags;
 294         /* Context ID - Currently not in use */
 295         __u32 ctx_id;
 296         __u32 pad;
 297 };
 298
 299 struct hl_mem_out {
 300         union {
 301                 /*
 302                  * Used for HL_MEM_OP_MAP as the virtual address that was
 303                  * assigned in the device VA space.
 304                  * A value of 0 means the requested operation failed.
 305                  */
 306                 __u64 device_virt_addr;
 307
 308                 /*
 309                  * Used for HL_MEM_OP_ALLOC. This is the assigned
 310                  * handle for the allocated memory
 311                  */
 312                 __u64 handle;
 313         };
 314 };
 315
 316 union hl_mem_args {
 317         struct hl_mem_in in;
 318         struct hl_mem_out out;
 319 };
 320
 321 /*
 322  * Various information operations such as:
 323  * - H/W IP information
 324  * - Current dram usage
 325  *
 326  * The user calls this IOCTL with an opcode that describes the required
 327  * information. The user should supply a pointer to a user-allocated memory
 328  * chunk, which will be filled by the driver with the requested information.
 329  *
 330  * The user supplies the maximum amount of size to copy into the user's memory,
 331  * in order to prevent data corruption in case of differences between the
 332  * definitions of structures in kernel and userspace, e.g. in case of old
 333  * userspace and new kernel driver
 334  */
 335 #define HL_IOCTL_INFO   \
 336                 _IOWR('H', 0x01, struct hl_info_args)
 337
 338 /*
 339  * Command Buffer
 340  * - Request a Command Buffer
 341  * - Destroy a Command Buffer
 342  *
 343  * The command buffers are memory blocks that reside in DMA-able address
 344  * space and are physically contiguous so they can be accessed by the device
 345  * directly. They are allocated using the coherent DMA API.
 346  *
 347  * When creating a new CB, the IOCTL returns a handle of it, and the user-space
 348  * process needs to use that handle to mmap the buffer so it can access them.
 349  *
 350  */
 351 #define HL_IOCTL_CB             \
 352                 _IOWR('H', 0x02, union hl_cb_args)
 353
 354 /*
 355  * Command Submission
 356  *
 357  * To submit work to the device, the user need to call this IOCTL with a set
 358  * of JOBS. That set of JOBS constitutes a CS object.
 359  * Each JOB will be enqueued on a specific queue, according to the user's input.
 360  * There can be more then one JOB per queue.
 361  *
 362  * There are two types of queues - external and internal. External queues
 363  * are DMA queues which transfer data from/to the Host. All other queues are
 364  * internal. The driver will get completion notifications from the device only
 365  * on JOBS which are enqueued in the external queues.
 366  *
 367  * This IOCTL is asynchronous in regard to the actual execution of the CS. This
 368  * means it returns immediately after ALL the JOBS were enqueued on their
 369  * relevant queues. Therefore, the user mustn't assume the CS has been completed
 370  * or has even started to execute.
 371  *
 372  * Upon successful enqueue, the IOCTL returns an opaque handle which the user
 373  * can use with the "Wait for CS" IOCTL to check whether the handle's CS
 374  * external JOBS have been completed. Note that if the CS has internal JOBS
 375  * which can execute AFTER the external JOBS have finished, the driver might
 376  * report that the CS has finished executing BEFORE the internal JOBS have
 377  * actually finish executing.
 378  *
 379  * The CS IOCTL will receive three sets of JOBS. One set is for "restore" phase,
 380  * a second set is for "execution" phase and a third set is for "store" phase.
 381  * The JOBS on the "restore" phase are enqueued only after context-switch
 382  * (or if its the first CS for this context). The user can also order the
 383  * driver to run the "restore" phase explicitly
 384  *
 385  */
 386 #define HL_IOCTL_CS                     \
 387                 _IOWR('H', 0x03, union hl_cs_args)
 388
 389 /*
 390  * Wait for Command Submission
 391  *
 392  * The user can call this IOCTL with a handle it received from the CS IOCTL
 393  * to wait until the handle's CS has finished executing. The user will wait
 394  * inside the kernel until the CS has finished or until the user-requeusted
 395  * timeout has expired.
 396  *
 397  * The return value of the IOCTL is a standard Linux error code. The possible
 398  * values are:
 399  *
 400  * EINTR     - Kernel waiting has been interrupted, e.g. due to OS signal
 401  *             that the user process received
 402  * ETIMEDOUT - The CS has caused a timeout on the device
 403  * EIO       - The CS was aborted (usually because the device was reset)
 404  * ENODEV    - The device wants to do hard-reset (so user need to close FD)
 405  *
 406  * The driver also returns a custom define inside the IOCTL which can be:
 407  *
 408  * HL_WAIT_CS_STATUS_COMPLETED   - The CS has been completed successfully (0)
 409  * HL_WAIT_CS_STATUS_BUSY        - The CS is still executing (0)
 410  * HL_WAIT_CS_STATUS_TIMEDOUT    - The CS has caused a timeout on the device
 411  *                                 (ETIMEDOUT)
 412  * HL_WAIT_CS_STATUS_ABORTED     - The CS was aborted, usually because the
 413  *                                 device was reset (EIO)
 414  * HL_WAIT_CS_STATUS_INTERRUPTED - Waiting for the CS was interrupted (EINTR)
 415  *
 416  */
 417
 418 #define HL_IOCTL_WAIT_CS                        \
 419                 _IOWR('H', 0x04, union hl_wait_cs_args)
 420
 421 /*
 422  * Memory
 423  * - Map host memory to device MMU
 424  * - Unmap host memory from device MMU
 425  *
 426  * This IOCTL allows the user to map host memory to the device MMU
 427  *
 428  * For host memory, the IOCTL doesn't allocate memory. The user is supposed
 429  * to allocate the memory in user-space (malloc/new). The driver pins the
 430  * physical pages (up to the allowed limit by the OS), assigns a virtual
 431  * address in the device VA space and initializes the device MMU.
 432  *
 433  * There is an option for the user to specify the requested virtual address.
 434  *
 435  */
 436 #define HL_IOCTL_MEMORY         \
 437                 _IOWR('H', 0x05, union hl_mem_args)
 438
 439 #define HL_COMMAND_START        0x01
 440 #define HL_COMMAND_END          0x06
 441
 442 #endif /* HABANALABS_H_ */