1 // SPDX-License-Identifier: GPL-2.0-only
3 * include/uapi/misc/trinity.h: User-level header for trinity devices.
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>
14 #include <linux/types.h>
16 #define TRINITY_API_LEVEL 12
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
26 TRINITY_STATE_UNKNOWN = -1,
27 TRINITY_STATE_PAUSE = 0,
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
39 enum trinity_input_mode {
40 TRINITY_INPUT_UNKNOWN = -1,
41 TRINITY_INPUT_CPU = 0,
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
54 enum trinity_output_mode {
55 TRINITY_OUTPUT_UNKNOWN = -1,
56 TRINITY_OUTPUT_CPU_INTR = 0,
57 TRINITY_OUTPUT_CPU_POLL,
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
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
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
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 */
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
100 enum trinity_req_priority {
101 TRINITY_REQ_PRIORITY_LOW = 0,
102 TRINITY_REQ_PRIORITY_MID = 1,
103 TRINITY_REQ_PRIORITY_HIGH = 2,
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.
112 enum trinity_hwmem_type {
113 TRINITY_HWMEM_DMA_CONT = 0,
114 TRINITY_HWMEM_DMA_IOMMU,
118 #ifndef TASK_COMM_LEN
119 #define TASK_COMM_LEN 16
122 #define TRINITY_APP_NAME_MAX TASK_COMM_LEN
123 #define TRINITY_APP_STAT_MAX 10
124 #define TRINITY_REQ_STAT_MAX 10
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
136 struct trinity_ioctl_stat_app {
139 char name[TRINITY_APP_NAME_MAX];
140 enum trinity_app_status status;
142 __u32 num_total_reqs;
143 __u32 num_active_reqs;
145 __u64 total_alloc_mem;
146 __u64 total_freed_mem;
147 } __attribute__((packed));
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
154 struct trinity_ioctl_stat_apps {
156 struct trinity_ioctl_stat_app stat[TRINITY_APP_STAT_MAX];
157 } __attribute__((packed));
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
168 struct trinity_ioctl_stat_req {
172 enum trinity_req_priority priority;
173 enum trinity_req_status status;
177 } __attribute__((packed));
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
185 struct trinity_ioctl_stat_reqs {
188 struct trinity_ioctl_stat_req stat[TRINITY_REQ_STAT_MAX];
189 } __attribute__((packed));
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
197 struct trinity_ioctl_hwmem {
198 enum trinity_hwmem_type type;
201 } __attribute__((packed));
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
212 struct trinity_ioctl_profile_meta {
216 __s64 input_footprint;
217 __s64 output_footprint;
219 } __attribute__((packed));
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
228 struct trinity_ioctl_profile_buff {
232 void __user *profile_buf;
233 } __attribute__((packed));
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
249 struct trinity_ioctl_model {
252 __u64 program_offset_addr;
256 __u8 endp_trnt_model_common[0];
258 __u64 weight_offset_addr;
259 } __attribute__((packed));
261 __s32 metadata_dbuf_fd;
262 __s32 metadata_ext_dbuf_fd;
263 __u64 metadata_ext_size;
264 __u32 num_visa_insts;
265 } __attribute__((packed));
267 } __attribute__((packed));
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
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 */
290 /** model id received when setting the model in the NPU */
292 /** req id to distinguish each run_input */
299 __u8 endp_trnt_input_common[0];
301 /* added for TRIV-1 */
302 __u64 activation_offset_addr0;
303 __u64 activation_offset_addr1;
304 } __attribute__((packed));
306 /* added for TRIV-2 */
308 enum trinity_input_mode input_mode;
309 enum trinity_output_mode output_mode;
312 /* [optional] vd scheduler info */
314 struct { /* user request */
317 } __attribute__((packed));
318 struct { /* kernel request */
320 } __attribute__((packed));
322 } __attribute__((packed));
324 } __attribute__((packed));
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
333 * It's workaround structure for FPGA envionment
335 struct trinity_ioctl_fpga_memcpy {
338 void __user *user_addr;
340 } __attribute__((packed));
343 * struct to share device status to user space
344 * This will be moved to debugfs
347 struct trinity_status {
348 /** Processor Information */
351 /** Processor Status */
355 /** Control Status */
358 /** Monitor Registers */
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)
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)
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)
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
392 enum trinity_dev_type {
393 TRINITY_DEV_UNKNOWN = 0,
397 TRINITY_DEV_VISION2_CUSE, /* CUSE-based impl. for triv2 */
398 TRINITY_DEV_END /* sentinel */
402 * Major number cant be dynamic as ioctls need it,
404 #define TRINITY_DRIVER_MAGIC 0x88
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)
411 /** Device Information */
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)
426 /** Device Control */
428 /** Allocate driver-managed memory */
429 #define TRINITY_IOCTL_HWMEM_ALLOC TRINITY_IOW(21, struct trinity_ioctl_hwmem)
431 /** De-allocate driver-managed memory */
432 #define TRINITY_IOCTL_HWMEM_DEALLOC TRINITY_IOW(22, struct trinity_ioctl_hwmem)
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)
438 /** Unregister the model config associated with the given model_id */
439 #define TRINITY_IOCTL_DEREGISTER_MODEL TRINITY_IOW(24, __u64)
441 /** Run the device with the given input */
442 #define TRINITY_IOCTL_RUN_INPUT TRINITY_IOWR(25, struct trinity_ioctl_input)
444 /** Stop all requests submitted to the device */
445 #define TRINITY_IOCTL_STOP_REQUESTS TRINITY_IO(26)
447 /** Stop the target request with id returned by run_input */
448 #define TRINITY_IOCTL_STOP_REQUEST TRINITY_IOW(27, __s32)
450 /** Device Statistics/Profile */
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)
456 /** Get latest apps' stat of the opened device */
457 #define TRINITY_IOCTL_STAT_APPS TRINITY_IOR(52, struct trinity_ioctl_stat_apps)
459 /** Get latest reqs' stat in the target app */
460 #define TRINITY_IOCTL_STAT_REQS TRINITY_IOR(53, struct trinity_ioctl_stat_reqs)
462 /** Get profiling metadata of the request */
463 #define TRINITY_IOCTL_GET_PROFILE_META \
464 TRINITY_IOWR(54, struct trinity_ioctl_profile_meta)
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)
470 /** Device Testing/Workaround */
472 /** Driver-assisted memory copy for FPGA env. */
473 #define TRINITY_IOCTL_FPGA_MEMCPY \
474 TRINITY_IOWR(91, struct trinity_ioctl_fpga_memcpy)
476 /** A wrapper of trinity_run_internal_req() */
477 #define TRINITY_IOCTL_RUN_INTERNAL_REQ TRINITY_IOW(92, dev_t)
480 __s32 trinity_run_internal_req(dev_t);
482 #endif /* __TRINITY_H__ */