include/uapi/misc/trinity.h

   1 // SPDX-License-Identifier: GPL-2.0-only
   2 /**
   3  * include/uapi/misc/trinity.h: User-level header for trinity devices.
   4  *
   5  * Copyright (C) 2020 Samsung Electronics
   6  * Copyright (C) 2020 Parichay Kapoor <pk.kapoor@samsung.com>
   7  * Copyright (C) 2020 Dongju Chae <dongju.chae@samsung.com>
   8  * Copyright (C) 2020 Wook Song <wook16.song@samsung.com>
   9  */
  10
  11 #ifndef __TRINITY_H__
  12 #define __TRINITY_H__
  13
  14 #include <linux/types.h>
  15
  16 #define TRINITY_API_LEVEL 12
  17
  18 /**
  19  * enum trinity_state - Enum that describes a trinity device state
  20  * @TRINITY_STATE_UNKNOWN: A device has unknown state
  21  * @TRINITY_STATE_PAUSE: A device is paused
  22  * @TRINITY_STATE_READY: A device is ready
  23  * @TRINITY_STATE_END: End of trinity_state
  24  */
  25 enum trinity_state {
  26         TRINITY_STATE_UNKNOWN = -1,
  27         TRINITY_STATE_PAUSE = 0,
  28         TRINITY_STATE_READY,
  29         TRINITY_STATE_END,
  30 };
  31
  32 /**
  33  * enum trinity_input_mode - Enum that describes an input source
  34  * @TRINITY_INPUT_UNKNOWN: Unknown input mode
  35  * @TRINITY_INPUT_CPU: Input feed by CPU
  36  * @TRINITY_INPUT_HW: Input feed by third-party HW
  37  * @TRINITY_INPUT_END: End of trinity_input_mode
  38  */
  39 enum trinity_input_mode {
  40         TRINITY_INPUT_UNKNOWN = -1,
  41         TRINITY_INPUT_CPU = 0,
  42         TRINITY_INPUT_HW,
  43         TRINITY_INPUT_END,
  44 };
  45
  46 /**
  47  * enum trinity_output_mode - Enum that describes an output source
  48  * @TRINITY_OUTPUT_UNKNOWN: Unknown output mode
  49  * @TRINITY_OUTPUT_CPU_INTR: Output completion handling by interrupt
  50  * @TRINITY_OUTPUT_CPU_POLL: Output completion handling by polling
  51  * @TRINITY_OUTPUT_HW: Output completion handling by third-party HW
  52  * @TRINITY_OUTPUT_END: End of trinity_output_mode
  53  */
  54 enum trinity_output_mode {
  55         TRINITY_OUTPUT_UNKNOWN = -1,
  56         TRINITY_OUTPUT_CPU_INTR = 0,
  57         TRINITY_OUTPUT_CPU_POLL,
  58         TRINITY_OUTPUT_HW,
  59         TRINITY_OUTPUT_END,
  60 };
  61
  62 /**
  63  * enum trinity_app_status - Enum that describes an app status
  64  * @TRINITY_APP_STATUS_UNKNOWN: Unknown app status
  65  * @TRINITY_APP_STATUS_ERROR: App has got some errors
  66  * @TRINITY_APP_STATUS_PENDING: App is currently pending
  67  * @TRINITY_APP_STATUS_STARTED: App was started
  68  * @TRINITY_APP_STATUS_TERMINATED: App was terminated
  69  */
  70 enum trinity_app_status {
  71         TRINITY_APP_STATUS_UNKNOWN = 0,
  72         TRINITY_APP_STATUS_ERROR = 1,
  73         TRINITY_APP_STATUS_PENDING = 2,
  74         TRINITY_APP_STATUS_STARTED = 3,
  75         TRINITY_APP_STATUS_TERMINATED = 4
  76 };
  77
  78 /**
  79  * enum trinity_req_status - Enum that describes a request status
  80  * @TRINITY_REQ_STATUS_UNKNOWN: Unknown request status
  81  * @TRINITY_REQ_STATUS_ERROR: Request has got some errors
  82  * @TRINITY_REQ_STATUS_PENDING: Request is currently pending
  83  * @TRINITY_REQ_STATUS_RUNING: Request is currently running
  84  * @TRINITY_REQ_STATUS_FINISHED: Request was finished
  85  */
  86 enum trinity_req_status {
  87         TRINITY_REQ_STATUS_UNKNOWN = 0,
  88         TRINITY_REQ_STATUS_ERROR = 1,
  89         TRINITY_REQ_STATUS_PENDING = 2, /* A request is submitted */
  90         TRINITY_REQ_STATUS_RUNNING = 3, /* A request is running on NPU */
  91         TRINITY_REQ_STATUS_FINISHED = 4 /* A request is just finished */
  92 };
  93
  94 /**
  95  * enum trinity_req_priority - Enum that describes a request priority
  96  * @TRINITY_REQ_PRIORITY_LOW: Low priority
  97  * @TRINITY_REQ_PRIORITY_MID: Mid priority scheduled with a higher chance than low one
  98  * @TRINITY_REQ_PRIORITY_HIGH: High priority preempting lower priority requests
  99  */
 100 enum trinity_req_priority {
 101         TRINITY_REQ_PRIORITY_LOW = 0,
 102         TRINITY_REQ_PRIORITY_MID = 1,
 103         TRINITY_REQ_PRIORITY_HIGH = 2,
 104 };
 105
 106 /**
 107  * enum trinity_hwmem_type - A type of DMA buffer allocation method.
 108  * @TRINITY_HWMEM_DMA_CONT: Use CMA to allocate backing stroage of DMA buffers.
 109  * @TRINITY_HWMEM_DMA_IOMMU: Use IOMMU to allocate backing stroage of DMA buffers.
 110  * @HWMEM_END: Sentinel.
 111  */
 112 enum trinity_hwmem_type {
 113         TRINITY_HWMEM_DMA_CONT = 0,
 114         TRINITY_HWMEM_DMA_IOMMU,
 115         TRINITY_HWMEM_END,
 116 };
 117
 118 #ifndef TASK_COMM_LEN
 119 #define TASK_COMM_LEN 16
 120 #endif
 121
 122 #define TRINITY_APP_NAME_MAX TASK_COMM_LEN
 123 #define TRINITY_APP_STAT_MAX 10
 124 #define TRINITY_REQ_STAT_MAX 10
 125
 126 /**
 127  * struct trinity_ioctl_stat_app - Describes stat of the target app
 128  * @app_id: Trinity app id (currently, equal to pid)
 129  * @name: Trinity app name
 130  * @status: Trinity app status
 131  * @num_total_reqs: Number of total requests in app (including finished ones)
 132  * @num_active_reqs: Number of active (running or pending) requests in app
 133  * @total_alloc_mem: Total size of allocated memory in the device
 134  * @total_freed_mem: Total size of freed memory in the device
 135  */
 136 struct trinity_ioctl_stat_app {
 137         __s32 app_id;
 138
 139         char name[TRINITY_APP_NAME_MAX];
 140         enum trinity_app_status status;
 141
 142         __u32 num_total_reqs;
 143         __u32 num_active_reqs;
 144
 145         __u64 total_alloc_mem;
 146         __u64 total_freed_mem;
 147 } __attribute__((packed));
 148
 149 /**
 150  * struct trinity_ioctl_stat_apps - Describes stats of the latest apps
 151  * @num_apps: Number of apps for the stat list
 152  * @stat: Stat of the latest apps
 153  */
 154 struct trinity_ioctl_stat_apps {
 155         __u32 num_apps;
 156         struct trinity_ioctl_stat_app stat[TRINITY_APP_STAT_MAX];
 157 } __attribute__((packed));
 158
 159 /**
 160  * struct trinity_ioctl_stat_req - Describes stat of the target request
 161  * @req_id: Trinity req id
 162  * @model_id: Trinity model id
 163  * @priority: Request priority (low, mid, or high)
 164  * @status: Request status
 165  * @sched_time: scheduling time in ms
 166  * @infer_time: inference time in ms
 167  */
 168 struct trinity_ioctl_stat_req {
 169         __s32 req_id;
 170         __u64 model_id;
 171
 172         enum trinity_req_priority priority;
 173         enum trinity_req_status status;
 174
 175         __u32 sched_time;
 176         __u32 infer_time;
 177 } __attribute__((packed));
 178
 179 /**
 180  * struct trinity_ioctl_stat_reqs - Describes stats of the latest reqs
 181  * @app_id: Trinity app id (0 means 'current')
 182  * @num_reqs: Number of reqs for stat list
 183  * @stat: Stat of the latest reqs
 184  */
 185 struct trinity_ioctl_stat_reqs {
 186         __s32 app_id;
 187         __u32 num_reqs;
 188         struct trinity_ioctl_stat_req stat[TRINITY_REQ_STAT_MAX];
 189 } __attribute__((packed));
 190
 191 /**
 192  * struct trinity_ioctl_hwmem - A structure that Describes hardware memory (hwmem)
 193  * @type: The type of hwmem type
 194  * @size: The size of hwmem
 195  * @dbuf_fd: File descriptor for dmabuf representing hwmem
 196  */
 197 struct trinity_ioctl_hwmem {
 198         enum trinity_hwmem_type type;
 199         __u64 size;
 200         __s32 dbuf_fd;
 201 } __attribute__((packed));
 202
 203 /**
 204  * struct trinity_ioctl_profile_meta - Describes profiling meta info.
 205  * @req_id: The target req id for profiling
 206  * @total_cycles: The total number of cycles of the given req
 207  * @total_ops: The total number of operations of the given req
 208  * @input_footprint: The DRAM footprint of input data
 209  * @output_footprint: The DRAM footprint of output data
 210  * @profile_size: The size of profiling data
 211  */
 212 struct trinity_ioctl_profile_meta {
 213         __s32 req_id;
 214         __s64 total_cycles;
 215         __u32 total_ops;
 216         __s64 input_footprint;
 217         __s64 output_footprint;
 218         __u32 profile_size;
 219 } __attribute__((packed));
 220
 221 /**
 222  * struct trinity_ioctl_profile_buff - Describes profiling buff info.
 223  * @req_id: The target req id for profiling
 224  * @profile_pos: The start position to extract profiling data
 225  * @profile_size: The size of user-allocated profiling buffer
 226  * @profile_buf: The profiling buffer which user allocated
 227  */
 228 struct trinity_ioctl_profile_buff {
 229         __s32 req_id;
 230         __u32 profile_pos;
 231         __u32 profile_size;
 232         void __user *profile_buf;
 233 } __attribute__((packed));
 234
 235 /**
 236  * struct trinity_ioctl_model - A structure that configure a model registered on NPU
 237  * @id: Id for NPU model to extract the base phys addr
 238  * @dbuf_fd: File descriptor for dmabuf representing the model
 239  * @program_offset_addr: Offset address for the instructions (NPU_PROG_BASE)
 240  * @program_size: Size of the program instructions (NPU_PROG_SIZE)
 241  * @version: The version of npubinfmt
 242  * @endp_trnt_model_common: Indicator for the end of common model parameters
 243  * @weight_offset_addr: Offset address for storing weights (NPU_WGT_BASE)
 244  * @metadata_dbuf_fd: File descriptor for dmabuf representing the metadata
 245  * @metadata_extra_addr: Offset address for the metadata extra
 246  * @metadata_extra_size: Size of the metadata extra
 247  * @num_visa_insts: Number of virtual ISA instructions
 248  */
 249 struct trinity_ioctl_model {
 250         __u64 id;
 251         __s32 dbuf_fd;
 252         __u64 program_offset_addr;
 253         __u64 program_size;
 254         __u32 version;
 255         union {
 256                 __u8 endp_trnt_model_common[0];
 257                 struct {
 258                         __u64 weight_offset_addr;
 259                 } __attribute__((packed));
 260                 struct {
 261                         __s32 metadata_dbuf_fd;
 262                         __s32 metadata_ext_dbuf_fd;
 263                         __u64 metadata_ext_size;
 264                         __u32 num_visa_insts;
 265                 } __attribute__((packed));
 266         };
 267 } __attribute__((packed));
 268
 269 /**
 270  * struct trinity_ioctl_input - A structure that configure an input passed to NPU
 271  * @dbuf_fd: File descriptor for dmabuf of I/O buffer (or segment table)
 272  * @model_id: Model id received when setting the model in the NPU
 273  * @req_id: Request id to distinguish each run_input
 274  * @timeout_ms: Timeout in ms, zero is regarded as preemption
 275  * @priority: Priority (LOW: 0, MID: 1, HIGH: 2)
 276  * @endp_trnt_input_common: Indicator for the end of common input parameters
 277  * @activation_offset_addr0: Offset address for storing weights (NPU_ACT_BASE0)
 278  * @activation_offset_addr1: Offset address for storing weights (NPU_ACT_BASE1)
 279  * @num_segments: Number of segments
 280  * @input_mode: Input mode (who is supposed to feed input)
 281  * @output_mode: Output mode (who is supposed to retrieve output)
 282  * @hw_input_seg: Third-party HW's input segment idx
 283  * @hw_output_seg: Third-party HW's output segment idx
 284  */
 285
 286 /** model configuration settings to pass input information to NPU */
 287 struct trinity_ioctl_input {
 288         /* id for I/O buffer (or segment table) to extract the base phys addr */
 289         __s32 dbuf_fd;
 290         /** model id received when setting the model in the NPU */
 291         __u64 model_id;
 292         /** req id to distinguish each run_input */
 293         __s32 req_id;
 294         /** timeout in ms */
 295         __s64 timeout_ms;
 296         /** priority */
 297         __u32 priority;
 298         union {
 299                 __u8 endp_trnt_input_common[0];
 300                 struct {
 301                         /* added for TRIV-1 */
 302                         __u64 activation_offset_addr0;
 303                         __u64 activation_offset_addr1;
 304                 } __attribute__((packed));
 305                 struct {
 306                         /* added for TRIV-2 */
 307                         __u32 num_segments;
 308                         enum trinity_input_mode input_mode;
 309                         enum trinity_output_mode output_mode;
 310                         __s32 hw_input_seg;
 311                         __s32 hw_output_seg;
 312                         /* [optional] vd scheduler info */
 313                         union {
 314                                 struct { /* user request */
 315                                         __u32 task_handle;
 316                                         __u32 subtask_idx;
 317                                 } __attribute__((packed));
 318                                 struct { /* kernel request */
 319                                         __u32 task_id;
 320                                 } __attribute__((packed));
 321                         };
 322                 } __attribute__((packed));
 323         };
 324 } __attribute__((packed));
 325
 326 /**
 327  * struct trinity_ioctl_fpga_memcpy - A structure that contains driver-assisted memcpy
 328  * @dbuf_fd: File descriptor for dmabuf of the target buffer
 329  * @dbuf_off: Offset from the dmabuf base address
 330  * @user_addr: Address of user-level buffer
 331  * @user_size: Size of user-level buffer
 332  *
 333  * It's workaround structure for FPGA envionment
 334  */
 335 struct trinity_ioctl_fpga_memcpy {
 336         __s32 dbuf_fd;
 337         __u32 dbuf_off;
 338         void __user *user_addr;
 339         __u64 user_size;
 340 } __attribute__((packed));
 341
 342 /*
 343  * struct to share device status to user space
 344  * This will be moved to debugfs
 345  */
 346 #if 0
 347 struct trinity_status {
 348         /** Processor Information */
 349         __u32 cp_info;
 350
 351         /** Processor Status */
 352         __u32 cp_proc_stat;
 353         __u32 npu_stat;
 354
 355         /** Control Status */
 356         __u32 cp_dmai_ctrl;
 357
 358         /** Monitor Registers */
 359         __u32 cp_cnt_cfg;
 360         __u32 cp_cnt_frl;
 361         __u32 cp_cnt_frh;
 362         __u32 cp_cnt_stl;
 363         __u32 cp_cnt_sth;
 364 };
 365 #endif
 366
 367 #define TRINITY_MASK_DEV       (0xFF000000)
 368 #define TRINITY_MASK_MAJOR_VER (0x00FF0000)
 369 #define TRINITY_MASK_MINOR_VER (0x0000FF00)
 370 #define TRINITY_MASK_EXTRA_VER (0x000000FF)
 371
 372 #define TRINITY_SHIFT_DEV       (24)
 373 #define TRINITY_SHIFT_MAJOR_VER (16)
 374 #define TRINITY_SHIFT_MINOR_VER (8)
 375 #define TRINITY_SHIFT_EXTRA_VER (0)
 376 #define TRINITY_SHIFT_MODEL_ID  (16)
 377
 378 #define trinity_gen_ver(dev, mj, mn, ex)                                       \
 379         (dev << TRINITY_SHIFT_DEV) | (mj << TRINITY_SHIFT_MAJOR_VER) |         \
 380                 (mn << TRINITY_SHIFT_MINOR_VER) |                              \
 381                 (ex << TRINITY_SHIFT_EXTRA_VER)
 382
 383 /**
 384  * enum trinity_dev_type - Enum that describes a trinity device type
 385  * @TRINITY_DEV_UNKNOWN: Unknown device type
 386  * @TRINITY_DEV_VISION: Trinity Vision (TRIV)
 387  * @TRINITY_DEV_AUDIO: Trinity Asr (TRIA)
 388  * @TRINITY_DEV_VISION2: Trinity Vision2 (TRIV2)
 389  * @TRINITY_DEV_VISION2_CUSE: Trinity Vision2 (TRIV2), CUSE-based impl.
 390  * @TRINITY_DEV_END: End of trinity_dev_type
 391  */
 392 enum trinity_dev_type {
 393         TRINITY_DEV_UNKNOWN = 0,
 394         TRINITY_DEV_VISION,
 395         TRINITY_DEV_AUDIO,
 396         TRINITY_DEV_VISION2,
 397         TRINITY_DEV_VISION2_CUSE, /* CUSE-based impl. for triv2 */
 398         TRINITY_DEV_END /* sentinel */
 399 };
 400
 401 /**
 402  * Major number cant be dynamic as ioctls need it,
 403  */
 404 #define TRINITY_DRIVER_MAGIC 0x88
 405
 406 #define TRINITY_IO(no)              _IO(TRINITY_DRIVER_MAGIC, no)
 407 #define TRINITY_IOR(no, data_type)  _IOR(TRINITY_DRIVER_MAGIC, no, data_type)
 408 #define TRINITY_IOW(no, data_type)  _IOW(TRINITY_DRIVER_MAGIC, no, data_type)
 409 #define TRINITY_IOWR(no, data_type) _IOWR(TRINITY_DRIVER_MAGIC, no, data_type)
 410
 411 /** Device Information */
 412
 413 /** Get the device version information from the driver */
 414 #define TRINITY_IOCTL_GET_VERSION TRINITY_IOR(1, __u32)
 415 /** Get the device API level from the driver */
 416 #define TRINITY_IOCTL_GET_API_LEVEL TRINITY_IOR(2, __u32)
 417 /** Get the device state from the driver */
 418 #define TRINITY_IOCTL_GET_STATE TRINITY_IOR(3, __s32)
 419 /** Get the device tops information from the driver */
 420 #define TRINITY_IOCTL_GET_TOPS TRINITY_IOR(4, __u32)
 421 /** Get the device dspm information from the driver */
 422 #define TRINITY_IOCTL_GET_DSPM TRINITY_IOR(5, __u32)
 423 /** Get the next request ID from the driver */
 424 #define TRINITY_IOCTL_GET_NEXT_REQUEST TRINITY_IOR(6, __s32)
 425
 426 /** Device Control */
 427
 428 /** Allocate driver-managed memory */
 429 #define TRINITY_IOCTL_HWMEM_ALLOC TRINITY_IOW(21, struct trinity_ioctl_hwmem)
 430
 431 /** De-allocate driver-managed memory */
 432 #define TRINITY_IOCTL_HWMEM_DEALLOC TRINITY_IOW(22, struct trinity_ioctl_hwmem)
 433
 434 /** Register the given model config in the device and return model id */
 435 #define TRINITY_IOCTL_REGISTER_MODEL                                           \
 436         TRINITY_IOWR(23, struct trinity_ioctl_model)
 437
 438 /** Unregister the model config associated with the given model_id */
 439 #define TRINITY_IOCTL_DEREGISTER_MODEL TRINITY_IOW(24, __u64)
 440
 441 /** Run the device with the given input */
 442 #define TRINITY_IOCTL_RUN_INPUT TRINITY_IOWR(25, struct trinity_ioctl_input)
 443
 444 /** Stop all requests submitted to the device */
 445 #define TRINITY_IOCTL_STOP_REQUESTS TRINITY_IO(26)
 446
 447 /** Stop the target request with id returned by run_input */
 448 #define TRINITY_IOCTL_STOP_REQUEST TRINITY_IOW(27, __s32)
 449
 450 /** Device Statistics/Profile */
 451
 452 /** Get the current app stat in the opened device */
 453 #define TRINITY_IOCTL_STAT_CURRENT_APP                                         \
 454         TRINITY_IOR(51, struct trinity_ioctl_stat_app)
 455
 456 /** Get latest apps' stat of the opened device */
 457 #define TRINITY_IOCTL_STAT_APPS TRINITY_IOR(52, struct trinity_ioctl_stat_apps)
 458
 459 /** Get latest reqs' stat in the target app */
 460 #define TRINITY_IOCTL_STAT_REQS TRINITY_IOR(53, struct trinity_ioctl_stat_reqs)
 461
 462 /** Get profiling metadata of the request */
 463 #define TRINITY_IOCTL_GET_PROFILE_META                                         \
 464         TRINITY_IOWR(54, struct trinity_ioctl_profile_meta)
 465
 466 /** Get profiling per-op data of the request */
 467 #define TRINITY_IOCTL_GET_PROFILE_BUFF                                         \
 468         TRINITY_IOWR(55, struct trinity_ioctl_profile_buff)
 469
 470 /** Device Testing/Workaround */
 471
 472 /** Driver-assisted memory copy for FPGA env. */
 473 #define TRINITY_IOCTL_FPGA_MEMCPY                                              \
 474         TRINITY_IOWR(91, struct trinity_ioctl_fpga_memcpy)
 475
 476 /** A wrapper of trinity_run_internal_req() */
 477 #define TRINITY_IOCTL_RUN_INTERNAL_REQ TRINITY_IOW(92, dev_t)
 478
 479 #ifdef __KERNEL__
 480 __s32 trinity_run_internal_req(dev_t);
 481 #endif
 482 #endif /* __TRINITY_H__ */