| @@ -0,0 +1,450 @@ |
| 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_ */ |