drivers/accel/ivpu/vpu_jsm_api.h

   1 /* SPDX-License-Identifier: MIT */
   2 /*
   3  * Copyright (C) 2020-2023 Intel Corporation
   4  */
   5
   6 /**
   7  * @file
   8  * @brief JSM shared definitions
   9  *
  10  * @ingroup Jsm
  11  * @brief JSM shared definitions
  12  * @{
  13  */
  14 #ifndef VPU_JSM_API_H
  15 #define VPU_JSM_API_H
  16
  17 /*
  18  * Major version changes that break backward compatibility
  19  */
  20 #define VPU_JSM_API_VER_MAJOR 3
  21
  22 /*
  23  * Minor version changes when API backward compatibility is preserved.
  24  */
  25 #define VPU_JSM_API_VER_MINOR 0
  26
  27 /*
  28  * API header changed (field names, documentation, formatting) but API itself has not been changed
  29  */
  30 #define VPU_JSM_API_VER_PATCH 1
  31
  32 /*
  33  * Index in the API version table
  34  */
  35 #define VPU_JSM_API_VER_INDEX 4
  36
  37 /*
  38  * Number of Priority Bands for Hardware Scheduling
  39  * Bands: RealTime, Focus, Normal, Idle
  40  */
  41 #define VPU_HWS_NUM_PRIORITY_BANDS 4
  42
  43 /* Max number of impacted contexts that can be dealt with the engine reset command */
  44 #define VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS 3
  45
  46 /** Pack the API structures for now, once alignment issues are fixed this can be removed */
  47 #pragma pack(push, 1)
  48
  49 /*
  50  * Engine indexes.
  51  */
  52 #define VPU_ENGINE_COMPUTE 0
  53 #define VPU_ENGINE_COPY    1
  54 #define VPU_ENGINE_NB      2
  55
  56 /*
  57  * VPU status values.
  58  */
  59 #define VPU_JSM_STATUS_SUCCESS                           0x0U
  60 #define VPU_JSM_STATUS_PARSING_ERR                       0x1U
  61 #define VPU_JSM_STATUS_PROCESSING_ERR                    0x2U
  62 #define VPU_JSM_STATUS_PREEMPTED                         0x3U
  63 #define VPU_JSM_STATUS_ABORTED                           0x4U
  64 #define VPU_JSM_STATUS_USER_CTX_VIOL_ERR                 0x5U
  65 #define VPU_JSM_STATUS_GLOBAL_CTX_VIOL_ERR               0x6U
  66 #define VPU_JSM_STATUS_MVNCI_WRONG_INPUT_FORMAT          0x7U
  67 #define VPU_JSM_STATUS_MVNCI_UNSUPPORTED_NETWORK_ELEMENT 0x8U
  68 #define VPU_JSM_STATUS_MVNCI_INVALID_HANDLE              0x9U
  69 #define VPU_JSM_STATUS_MVNCI_OUT_OF_RESOURCES            0xAU
  70 #define VPU_JSM_STATUS_MVNCI_NOT_IMPLEMENTED             0xBU
  71 #define VPU_JSM_STATUS_MVNCI_INTERNAL_ERROR              0xCU
  72 /* Job status returned when the job was preempted mid-inference */
  73 #define VPU_JSM_STATUS_PREEMPTED_MID_INFERENCE           0xDU
  74
  75 /*
  76  * Host <-> VPU IPC channels.
  77  * ASYNC commands use a high priority channel, other messages use low-priority ones.
  78  */
  79 #define VPU_IPC_CHAN_ASYNC_CMD 0
  80 #define VPU_IPC_CHAN_GEN_CMD   10
  81 #define VPU_IPC_CHAN_JOB_RET   11
  82
  83 /*
  84  * Job flags bit masks.
  85  */
  86 #define VPU_JOB_FLAGS_NULL_SUBMISSION_MASK 0x00000001
  87
  88 /*
  89  * Sizes of the reserved areas in jobs, in bytes.
  90  */
  91 #define VPU_JOB_RESERVED_BYTES       16
  92 /*
  93  * Sizes of the reserved areas in job queues, in bytes.
  94  */
  95 #define VPU_JOB_QUEUE_RESERVED_BYTES 52
  96
  97 /*
  98  * Max length (including trailing NULL char) of trace entity name (e.g., the
  99  * name of a logging destination or a loggable HW component).
 100  */
 101 #define VPU_TRACE_ENTITY_NAME_MAX_LEN 32
 102
 103 /*
 104  * Max length (including trailing NULL char) of a dyndbg command.
 105  *
 106  * NOTE: 96 is used so that the size of 'struct vpu_ipc_msg' in the JSM API is
 107  * 128 bytes (multiple of 64 bytes, the cache line size).
 108  */
 109 #define VPU_DYNDBG_CMD_MAX_LEN 96
 110
 111 /*
 112  * Job format.
 113  */
 114 struct vpu_job_queue_entry {
 115         u64 batch_buf_addr; /**< Address of VPU commands batch buffer */
 116         u32 job_id;       /**< Job ID */
 117         u32 flags; /**< Flags bit field, see VPU_JOB_FLAGS_* above */
 118         u64 root_page_table_addr; /**< Address of root page table to use for this job */
 119         u64 root_page_table_update_counter; /**< Page tables update events counter */
 120         u64 preemption_buffer_address; /**< Address of the preemption buffer to use for this job */
 121         u64 preemption_buffer_size; /**< Size of the preemption buffer to use for this job */
 122         u8 reserved_0[VPU_JOB_RESERVED_BYTES];
 123 };
 124
 125 /*
 126  * Job queue control registers.
 127  */
 128 struct vpu_job_queue_header {
 129         u32 engine_idx;
 130         u32 head;
 131         u32 tail;
 132         u8 reserved_0[VPU_JOB_QUEUE_RESERVED_BYTES];
 133 };
 134
 135 /*
 136  * Job queue format.
 137  */
 138 struct vpu_job_queue {
 139         struct vpu_job_queue_header header;
 140         struct vpu_job_queue_entry job[];
 141 };
 142
 143 /**
 144  * Logging entity types.
 145  *
 146  * This enum defines the different types of entities involved in logging.
 147  */
 148 enum vpu_trace_entity_type {
 149         /** Logging destination (entity where logs can be stored / printed). */
 150         VPU_TRACE_ENTITY_TYPE_DESTINATION = 1,
 151         /** Loggable HW component (HW entity that can be logged). */
 152         VPU_TRACE_ENTITY_TYPE_HW_COMPONENT = 2,
 153 };
 154
 155 /*
 156  * Host <-> VPU IPC messages types.
 157  */
 158 enum vpu_ipc_msg_type {
 159         VPU_JSM_MSG_UNKNOWN = 0xFFFFFFFF,
 160         /* IPC Host -> Device, Async commands */
 161         VPU_JSM_MSG_ASYNC_CMD = 0x1100,
 162         VPU_JSM_MSG_ENGINE_RESET = VPU_JSM_MSG_ASYNC_CMD,
 163         VPU_JSM_MSG_ENGINE_PREEMPT = 0x1101,
 164         VPU_JSM_MSG_REGISTER_DB = 0x1102,
 165         VPU_JSM_MSG_UNREGISTER_DB = 0x1103,
 166         VPU_JSM_MSG_QUERY_ENGINE_HB = 0x1104,
 167         VPU_JSM_MSG_GET_POWER_LEVEL_COUNT = 0x1105,
 168         VPU_JSM_MSG_GET_POWER_LEVEL = 0x1106,
 169         VPU_JSM_MSG_SET_POWER_LEVEL = 0x1107,
 170         /* @deprecated */
 171         VPU_JSM_MSG_METRIC_STREAMER_OPEN = 0x1108,
 172         /* @deprecated */
 173         VPU_JSM_MSG_METRIC_STREAMER_CLOSE = 0x1109,
 174         /** Configure logging (used to modify configuration passed in boot params). */
 175         VPU_JSM_MSG_TRACE_SET_CONFIG = 0x110a,
 176         /** Return current logging configuration. */
 177         VPU_JSM_MSG_TRACE_GET_CONFIG = 0x110b,
 178         /**
 179          * Get masks of destinations and HW components supported by the firmware
 180          * (may vary between HW generations and FW compile
 181          * time configurations)
 182          */
 183         VPU_JSM_MSG_TRACE_GET_CAPABILITY = 0x110c,
 184         /** Get the name of a destination or HW component. */
 185         VPU_JSM_MSG_TRACE_GET_NAME = 0x110d,
 186         /**
 187          * Release resource associated with host ssid . All jobs that belong to the host_ssid
 188          * aborted and removed from internal scheduling queues. All doorbells assigned
 189          * to the host_ssid are unregistered and any internal FW resources belonging to
 190          * the host_ssid are released.
 191          */
 192         VPU_JSM_MSG_SSID_RELEASE = 0x110e,
 193         /**
 194          * Start collecting metric data.
 195          * @see vpu_jsm_metric_streamer_start
 196          */
 197         VPU_JSM_MSG_METRIC_STREAMER_START = 0x110f,
 198         /**
 199          * Stop collecting metric data. This command will return success if it is called
 200          * for a metric stream that has already been stopped or was never started.
 201          * @see vpu_jsm_metric_streamer_stop
 202          */
 203         VPU_JSM_MSG_METRIC_STREAMER_STOP = 0x1110,
 204         /**
 205          * Update current and next buffer for metric data collection. This command can
 206          * also be used to request information about the number of collected samples
 207          * and the amount of data written to the buffer.
 208          * @see vpu_jsm_metric_streamer_update
 209          */
 210         VPU_JSM_MSG_METRIC_STREAMER_UPDATE = 0x1111,
 211         /**
 212          * Request description of selected metric groups and metric counters within
 213          * each group. The VPU will write the description of groups and counters to
 214          * the buffer specified in the command structure.
 215          * @see vpu_jsm_metric_streamer_start
 216          */
 217         VPU_JSM_MSG_METRIC_STREAMER_INFO = 0x1112,
 218         /** Control command: Priority band setup */
 219         VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP = 0x1113,
 220         /** Control command: Create command queue */
 221         VPU_JSM_MSG_CREATE_CMD_QUEUE = 0x1114,
 222         /** Control command: Destroy command queue */
 223         VPU_JSM_MSG_DESTROY_CMD_QUEUE = 0x1115,
 224         /** Control command: Set context scheduling properties */
 225         VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES = 0x1116,
 226         /*
 227          * Register a doorbell to notify VPU of new work. The doorbell may later be
 228          * deallocated or reassigned to another context.
 229          */
 230         VPU_JSM_MSG_HWS_REGISTER_DB = 0x1117,
 231         /* IPC Host -> Device, General commands */
 232         VPU_JSM_MSG_GENERAL_CMD = 0x1200,
 233         VPU_JSM_MSG_BLOB_DEINIT = VPU_JSM_MSG_GENERAL_CMD,
 234         /**
 235          * Control dyndbg behavior by executing a dyndbg command; equivalent to
 236          * Linux command: `echo '<dyndbg_cmd>' > <debugfs>/dynamic_debug/control`.
 237          */
 238         VPU_JSM_MSG_DYNDBG_CONTROL = 0x1201,
 239         /* IPC Device -> Host, Job completion */
 240         VPU_JSM_MSG_JOB_DONE = 0x2100,
 241         /* IPC Device -> Host, Async command completion */
 242         VPU_JSM_MSG_ASYNC_CMD_DONE = 0x2200,
 243         VPU_JSM_MSG_ENGINE_RESET_DONE = VPU_JSM_MSG_ASYNC_CMD_DONE,
 244         VPU_JSM_MSG_ENGINE_PREEMPT_DONE = 0x2201,
 245         VPU_JSM_MSG_REGISTER_DB_DONE = 0x2202,
 246         VPU_JSM_MSG_UNREGISTER_DB_DONE = 0x2203,
 247         VPU_JSM_MSG_QUERY_ENGINE_HB_DONE = 0x2204,
 248         VPU_JSM_MSG_GET_POWER_LEVEL_COUNT_DONE = 0x2205,
 249         VPU_JSM_MSG_GET_POWER_LEVEL_DONE = 0x2206,
 250         VPU_JSM_MSG_SET_POWER_LEVEL_DONE = 0x2207,
 251         /* @deprecated */
 252         VPU_JSM_MSG_METRIC_STREAMER_OPEN_DONE = 0x2208,
 253         /* @deprecated */
 254         VPU_JSM_MSG_METRIC_STREAMER_CLOSE_DONE = 0x2209,
 255         /** Response to VPU_JSM_MSG_TRACE_SET_CONFIG. */
 256         VPU_JSM_MSG_TRACE_SET_CONFIG_RSP = 0x220a,
 257         /** Response to VPU_JSM_MSG_TRACE_GET_CONFIG. */
 258         VPU_JSM_MSG_TRACE_GET_CONFIG_RSP = 0x220b,
 259         /** Response to VPU_JSM_MSG_TRACE_GET_CAPABILITY. */
 260         VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP = 0x220c,
 261         /** Response to VPU_JSM_MSG_TRACE_GET_NAME. */
 262         VPU_JSM_MSG_TRACE_GET_NAME_RSP = 0x220d,
 263         /** Response to VPU_JSM_MSG_SSID_RELEASE. */
 264         VPU_JSM_MSG_SSID_RELEASE_DONE = 0x220e,
 265         /**
 266          * Response to VPU_JSM_MSG_METRIC_STREAMER_START.
 267          * VPU will return an error result if metric collection cannot be started,
 268          * e.g. when the specified metric mask is invalid.
 269          * @see vpu_jsm_metric_streamer_done
 270          */
 271         VPU_JSM_MSG_METRIC_STREAMER_START_DONE = 0x220f,
 272         /**
 273          * Response to VPU_JSM_MSG_METRIC_STREAMER_STOP.
 274          * Returns information about collected metric data.
 275          * @see vpu_jsm_metric_streamer_done
 276          */
 277         VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE = 0x2210,
 278         /**
 279          * Response to VPU_JSM_MSG_METRIC_STREAMER_UPDATE.
 280          * Returns information about collected metric data.
 281          * @see vpu_jsm_metric_streamer_done
 282          */
 283         VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE = 0x2211,
 284         /**
 285          * Response to VPU_JSM_MSG_METRIC_STREAMER_INFO.
 286          * Returns a description of the metric groups and metric counters.
 287          * @see vpu_jsm_metric_streamer_done
 288          */
 289         VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE = 0x2212,
 290         /**
 291          * Asynchronous event sent from the VPU to the host either when the current
 292          * metric buffer is full or when the VPU has collected a multiple of
 293          * @notify_sample_count samples as indicated through the start command
 294          * (VPU_JSM_MSG_METRIC_STREAMER_START). Returns information about collected
 295          * metric data.
 296          * @see vpu_jsm_metric_streamer_done
 297          */
 298         VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION = 0x2213,
 299         /** Response to control command: Priority band setup */
 300         VPU_JSM_MSG_SET_PRIORITY_BAND_SETUP_RSP = 0x2214,
 301         /** Response to control command: Create command queue */
 302         VPU_JSM_MSG_CREATE_CMD_QUEUE_RSP = 0x2215,
 303         /** Response to control command: Destroy command queue */
 304         VPU_JSM_MSG_DESTROY_CMD_QUEUE_RSP = 0x2216,
 305         /** Response to control command: Set context scheduling properties */
 306         VPU_JSM_MSG_SET_CONTEXT_SCHED_PROPERTIES_RSP = 0x2217,
 307         /* IPC Device -> Host, General command completion */
 308         VPU_JSM_MSG_GENERAL_CMD_DONE = 0x2300,
 309         VPU_JSM_MSG_BLOB_DEINIT_DONE = VPU_JSM_MSG_GENERAL_CMD_DONE,
 310         /** Response to VPU_JSM_MSG_DYNDBG_CONTROL. */
 311         VPU_JSM_MSG_DYNDBG_CONTROL_RSP = 0x2301,
 312 };
 313
 314 enum vpu_ipc_msg_status { VPU_JSM_MSG_FREE, VPU_JSM_MSG_ALLOCATED };
 315
 316 /*
 317  * Host <-> LRT IPC message payload definitions
 318  */
 319 struct vpu_ipc_msg_payload_engine_reset {
 320         /* Engine to be reset. */
 321         u32 engine_idx;
 322         /* Reserved */
 323         u32 reserved_0;
 324 };
 325
 326 struct vpu_ipc_msg_payload_engine_preempt {
 327         /* Engine to be preempted. */
 328         u32 engine_idx;
 329         /* ID of the preemption request. */
 330         u32 preempt_id;
 331 };
 332
 333 /*
 334  * @brief Register doorbell command structure.
 335  * This structure supports doorbell registration for only OS scheduling.
 336  * @see VPU_JSM_MSG_REGISTER_DB
 337  */
 338 struct vpu_ipc_msg_payload_register_db {
 339         /* Index of the doorbell to register. */
 340         u32 db_idx;
 341         /* Reserved */
 342         u32 reserved_0;
 343         /* Virtual address in Global GTT pointing to the start of job queue. */
 344         u64 jobq_base;
 345         /* Size of the job queue in bytes. */
 346         u32 jobq_size;
 347         /* Host sub-stream ID for the context assigned to the doorbell. */
 348         u32 host_ssid;
 349 };
 350
 351 /**
 352  * @brief Unregister doorbell command structure.
 353  * Request structure to unregister a doorbell for both HW and OS scheduling.
 354  * @see VPU_JSM_MSG_UNREGISTER_DB
 355  */
 356 struct vpu_ipc_msg_payload_unregister_db {
 357         /* Index of the doorbell to unregister. */
 358         u32 db_idx;
 359         /* Reserved */
 360         u32 reserved_0;
 361 };
 362
 363 struct vpu_ipc_msg_payload_query_engine_hb {
 364         /* Engine to return heartbeat value. */
 365         u32 engine_idx;
 366         /* Reserved */
 367         u32 reserved_0;
 368 };
 369
 370 struct vpu_ipc_msg_payload_power_level {
 371         /**
 372          * Requested power level. The power level value is in the
 373          * range [0, power_level_count-1] where power_level_count
 374          * is the number of available power levels as returned by
 375          * the get power level count command. A power level of 0
 376          * corresponds to the maximum possible power level, while
 377          * power_level_count-1 corresponds to the minimum possible
 378          * power level. Values outside of this range are not
 379          * considered to be valid.
 380          */
 381         u32 power_level;
 382         /* Reserved */
 383         u32 reserved_0;
 384 };
 385
 386 struct vpu_ipc_msg_payload_ssid_release {
 387         /* Host sub-stream ID for the context to be released. */
 388         u32 host_ssid;
 389         /* Reserved */
 390         u32 reserved_0;
 391 };
 392
 393 /**
 394  * @brief Metric streamer start command structure.
 395  * This structure is also used with VPU_JSM_MSG_METRIC_STREAMER_INFO to request metric
 396  * groups and metric counters description from the firmware.
 397  * @see VPU_JSM_MSG_METRIC_STREAMER_START
 398  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
 399  */
 400 struct vpu_jsm_metric_streamer_start {
 401         /**
 402          * Bitmask to select the desired metric groups.
 403          * A metric group can belong only to one metric streamer instance at a time.
 404          * Since each metric streamer instance has a unique set of metric groups, it
 405          * can also identify a metric streamer instance if more than one instance was
 406          * started. If the VPU device does not support multiple metric streamer instances,
 407          * then VPU_JSM_MSG_METRIC_STREAMER_START will return an error even if the second
 408          * instance has different groups to the first.
 409          */
 410         u64 metric_group_mask;
 411         /** Sampling rate in nanoseconds. */
 412         u64 sampling_rate;
 413         /**
 414          * If > 0 the VPU will send a VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION message
 415          * after every @notify_sample_count samples is collected or dropped by the VPU.
 416          * If set to UINT_MAX the VPU will only generate a notification when the metric
 417          * buffer is full. If set to 0 the VPU will never generate a notification.
 418          */
 419         u32 notify_sample_count;
 420         u32 reserved_0;
 421         /**
 422          * Address and size of the buffer where the VPU will write metric data. The
 423          * VPU writes all counters from enabled metric groups one after another. If
 424          * there is no space left to write data at the next sample period the VPU
 425          * will switch to the next buffer (@see next_buffer_addr) and will optionally
 426          * send a notification to the host driver if @notify_sample_count is non-zero.
 427          * If @next_buffer_addr is NULL the VPU will stop collecting metric data.
 428          */
 429         u64 buffer_addr;
 430         u64 buffer_size;
 431         /**
 432          * Address and size of the next buffer to write metric data to after the initial
 433          * buffer is full. If the address is NULL the VPU will stop collecting metric
 434          * data.
 435          */
 436         u64 next_buffer_addr;
 437         u64 next_buffer_size;
 438 };
 439
 440 /**
 441  * @brief Metric streamer stop command structure.
 442  * @see VPU_JSM_MSG_METRIC_STREAMER_STOP
 443  */
 444 struct vpu_jsm_metric_streamer_stop {
 445         /** Bitmask to select the desired metric groups. */
 446         u64 metric_group_mask;
 447 };
 448
 449 /**
 450  * Provide VPU FW with buffers to write metric data.
 451  * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE
 452  */
 453 struct vpu_jsm_metric_streamer_update {
 454         /** Metric group mask that identifies metric streamer instance. */
 455         u64 metric_group_mask;
 456         /**
 457          * Address and size of the buffer where the VPU will write metric data. If
 458          * the buffer address is 0 or same as the currently used buffer the VPU will
 459          * continue writing metric data to the current buffer. In this case the
 460          * buffer size is ignored and the size of the current buffer is unchanged.
 461          * If the address is non-zero and differs from the current buffer address the
 462          * VPU will immediately switch data collection to the new buffer.
 463          */
 464         u64 buffer_addr;
 465         u64 buffer_size;
 466         /**
 467          * Address and size of the next buffer to write metric data after the initial
 468          * buffer is full. If the address is NULL the VPU will stop collecting metric
 469          * data but will continue to record dropped samples.
 470          *
 471          * Note that there is a hazard possible if both buffer_addr and the next_buffer_addr
 472          * are non-zero in same update request. It is the host's responsibility to ensure
 473          * that both addresses make sense even if the VPU just switched to writing samples
 474          * from the current to the next buffer.
 475          */
 476         u64 next_buffer_addr;
 477         u64 next_buffer_size;
 478 };
 479
 480 struct vpu_ipc_msg_payload_blob_deinit {
 481         /* 64-bit unique ID for the blob to be de-initialized. */
 482         u64 blob_id;
 483 };
 484
 485 struct vpu_ipc_msg_payload_job_done {
 486         /* Engine to which the job was submitted. */
 487         u32 engine_idx;
 488         /* Index of the doorbell to which the job was submitted */
 489         u32 db_idx;
 490         /* ID of the completed job */
 491         u32 job_id;
 492         /* Status of the completed job */
 493         u32 job_status;
 494         /* Host SSID */
 495         u32 host_ssid;
 496         /* Zero Padding */
 497         u32 reserved_0;
 498         /* Command queue id */
 499         u64 cmdq_id;
 500 };
 501
 502 struct vpu_jsm_engine_reset_context {
 503         /* Host SSID */
 504         u32 host_ssid;
 505         /* Zero Padding */
 506         u32 reserved_0;
 507         /* Command queue id */
 508         u64 cmdq_id;
 509         /* Flags: 0: cause of hang; 1: collateral damage of reset */
 510         u64 flags;
 511 };
 512
 513 struct vpu_ipc_msg_payload_engine_reset_done {
 514         /* Engine ordinal */
 515         u32 engine_idx;
 516         /* Number of impacted contexts */
 517         u32 num_impacted_contexts;
 518         /* Array of impacted command queue ids and their flags */
 519         struct vpu_jsm_engine_reset_context
 520                 impacted_contexts[VPU_MAX_ENGINE_RESET_IMPACTED_CONTEXTS];
 521 };
 522
 523 struct vpu_ipc_msg_payload_engine_preempt_done {
 524         /* Engine preempted. */
 525         u32 engine_idx;
 526         /* ID of the preemption request. */
 527         u32 preempt_id;
 528 };
 529
 530 /**
 531  * Response structure for register doorbell command for both OS
 532  * and HW scheduling.
 533  * @see VPU_JSM_MSG_REGISTER_DB
 534  * @see VPU_JSM_MSG_HWS_REGISTER_DB
 535  */
 536 struct vpu_ipc_msg_payload_register_db_done {
 537         /* Index of the registered doorbell. */
 538         u32 db_idx;
 539         /* Reserved */
 540         u32 reserved_0;
 541 };
 542
 543 /**
 544  * Response structure for unregister doorbell command for both OS
 545  * and HW scheduling.
 546  * @see VPU_JSM_MSG_UNREGISTER_DB
 547  */
 548 struct vpu_ipc_msg_payload_unregister_db_done {
 549         /* Index of the unregistered doorbell. */
 550         u32 db_idx;
 551         /* Reserved */
 552         u32 reserved_0;
 553 };
 554
 555 struct vpu_ipc_msg_payload_query_engine_hb_done {
 556         /* Engine returning heartbeat value. */
 557         u32 engine_idx;
 558         /* Reserved */
 559         u32 reserved_0;
 560         /* Heartbeat value. */
 561         u64 heartbeat;
 562 };
 563
 564 struct vpu_ipc_msg_payload_get_power_level_count_done {
 565         /**
 566          * Number of supported power levels. The maximum possible
 567          * value of power_level_count is 16 but this may vary across
 568          * implementations.
 569          */
 570         u32 power_level_count;
 571         /* Reserved */
 572         u32 reserved_0;
 573         /**
 574          * Power consumption limit for each supported power level in
 575          * [0-100%] range relative to power level 0.
 576          */
 577         u8 power_limit[16];
 578 };
 579
 580 struct vpu_ipc_msg_payload_blob_deinit_done {
 581         /* 64-bit unique ID for the blob de-initialized. */
 582         u64 blob_id;
 583 };
 584
 585 /* HWS priority band setup request / response */
 586 struct vpu_ipc_msg_payload_hws_priority_band_setup {
 587         /*
 588          * Grace period in 100ns units when preempting another priority band for
 589          * this priority band
 590          */
 591         u32 grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
 592         /*
 593          * Default quantum in 100ns units for scheduling across processes
 594          * within a priority band
 595          */
 596         u64 process_quantum[VPU_HWS_NUM_PRIORITY_BANDS];
 597         /*
 598          * Default grace period in 100ns units for processes that preempt each
 599          * other within a priority band
 600          */
 601         u64 process_grace_period[VPU_HWS_NUM_PRIORITY_BANDS];
 602         /*
 603          * For normal priority band, specifies the target VPU percentage
 604          * in situations when it's starved by the focus band.
 605          */
 606         u32 normal_band_percentage;
 607         /* Reserved */
 608         u32 reserved_0;
 609 };
 610
 611 /* HWS create command queue request */
 612 struct vpu_ipc_msg_payload_hws_create_cmdq {
 613         /* Process id */
 614         u64 process_id;
 615         /* Host SSID */
 616         u32 host_ssid;
 617         /* Zero Padding */
 618         u32 reserved;
 619         /* Command queue id */
 620         u64 cmdq_id;
 621         /* Command queue base */
 622         u64 cmdq_base;
 623         /* Command queue size */
 624         u32 cmdq_size;
 625         /* Reserved */
 626         u32 reserved_0;
 627 };
 628
 629 /* HWS create command queue response */
 630 struct vpu_ipc_msg_payload_hws_create_cmdq_rsp {
 631         /* Process id */
 632         u64 process_id;
 633         /* Host SSID */
 634         u32 host_ssid;
 635         /* Zero Padding */
 636         u32 reserved;
 637         /* Command queue id */
 638         u64 cmdq_id;
 639 };
 640
 641 /* HWS destroy command queue request / response */
 642 struct vpu_ipc_msg_payload_hws_destroy_cmdq {
 643         /* Host SSID */
 644         u32 host_ssid;
 645         /* Zero Padding */
 646         u32 reserved;
 647         /* Command queue id */
 648         u64 cmdq_id;
 649 };
 650
 651 /* HWS set context scheduling properties request / response */
 652 struct vpu_ipc_msg_payload_hws_set_context_sched_properties {
 653         /* Host SSID */
 654         u32 host_ssid;
 655         /* Zero Padding */
 656         u32 reserved_0;
 657         /* Command queue id */
 658         u64 cmdq_id;
 659         /* Priority band to assign to work of this context */
 660         u32 priority_band;
 661         /* Inside realtime band assigns a further priority */
 662         u32 realtime_priority_level;
 663         /* Priority relative to other contexts in the same process */
 664         u32 in_process_priority;
 665         /* Zero padding / Reserved */
 666         u32 reserved_1;
 667         /* Context quantum relative to other contexts of same priority in the same process */
 668         u64 context_quantum;
 669         /* Grace period when preempting context of the same priority within the same process */
 670         u64 grace_period_same_priority;
 671         /* Grace period when preempting context of a lower priority within the same process */
 672         u64 grace_period_lower_priority;
 673 };
 674
 675 /*
 676  * @brief Register doorbell command structure.
 677  * This structure supports doorbell registration for both HW and OS scheduling.
 678  * Note: Queue base and size are added here so that the same structure can be used for
 679  * OS scheduling and HW scheduling. For OS scheduling, cmdq_id will be ignored
 680  * and cmdq_base and cmdq_size will be used. For HW scheduling, cmdq_base and cmdq_size will be
 681  * ignored and cmdq_id is used.
 682  * @see VPU_JSM_MSG_HWS_REGISTER_DB
 683  */
 684 struct vpu_jsm_hws_register_db {
 685         /* Index of the doorbell to register. */
 686         u32 db_id;
 687         /* Host sub-stream ID for the context assigned to the doorbell. */
 688         u32 host_ssid;
 689         /* ID of the command queue associated with the doorbell. */
 690         u64 cmdq_id;
 691         /* Virtual address pointing to the start of command queue. */
 692         u64 cmdq_base;
 693         /* Size of the command queue in bytes. */
 694         u64 cmdq_size;
 695 };
 696
 697 /**
 698  * Payload for VPU_JSM_MSG_TRACE_SET_CONFIG[_RSP] and
 699  * VPU_JSM_MSG_TRACE_GET_CONFIG_RSP messages.
 700  *
 701  * The payload is interpreted differently depending on the type of message:
 702  *
 703  * - For VPU_JSM_MSG_TRACE_SET_CONFIG, the payload specifies the desired
 704  *   logging configuration to be set.
 705  *
 706  * - For VPU_JSM_MSG_TRACE_SET_CONFIG_RSP, the payload reports the logging
 707  *   configuration that was set after a VPU_JSM_MSG_TRACE_SET_CONFIG request.
 708  *   The host can compare this payload with the one it sent in the
 709  *   VPU_JSM_MSG_TRACE_SET_CONFIG request to check whether or not the
 710  *   configuration was set as desired.
 711  *
 712  * - VPU_JSM_MSG_TRACE_GET_CONFIG_RSP, the payload reports the current logging
 713  *   configuration.
 714  */
 715 struct vpu_ipc_msg_payload_trace_config {
 716         /**
 717          * Logging level (currently set or to be set); see 'mvLog_t' enum for
 718          * acceptable values. The specified logging level applies to all
 719          * destinations and HW components
 720          */
 721         u32 trace_level;
 722         /**
 723          * Bitmask of logging destinations (currently enabled or to be enabled);
 724          * bitwise OR of values defined in logging_destination enum.
 725          */
 726         u32 trace_destination_mask;
 727         /**
 728          * Bitmask of loggable HW components (currently enabled or to be enabled);
 729          * bitwise OR of values defined in loggable_hw_component enum.
 730          */
 731         u64 trace_hw_component_mask;
 732         u64 reserved_0; /**< Reserved for future extensions. */
 733 };
 734
 735 /**
 736  * Payload for VPU_JSM_MSG_TRACE_GET_CAPABILITY_RSP messages.
 737  */
 738 struct vpu_ipc_msg_payload_trace_capability_rsp {
 739         u32 trace_destination_mask; /**< Bitmask of supported logging destinations. */
 740         u32 reserved_0;
 741         u64 trace_hw_component_mask; /**< Bitmask of supported loggable HW components. */
 742         u64 reserved_1; /**< Reserved for future extensions. */
 743 };
 744
 745 /**
 746  * Payload for VPU_JSM_MSG_TRACE_GET_NAME requests.
 747  */
 748 struct vpu_ipc_msg_payload_trace_get_name {
 749         /**
 750          * The type of the entity to query name for; see logging_entity_type for
 751          * possible values.
 752          */
 753         u32 entity_type;
 754         u32 reserved_0;
 755         /**
 756          * The ID of the entity to query name for; possible values depends on the
 757          * entity type.
 758          */
 759         u64 entity_id;
 760 };
 761
 762 /**
 763  * Payload for VPU_JSM_MSG_TRACE_GET_NAME_RSP responses.
 764  */
 765 struct vpu_ipc_msg_payload_trace_get_name_rsp {
 766         /**
 767          * The type of the entity whose name was queried; see logging_entity_type
 768          * for possible values.
 769          */
 770         u32 entity_type;
 771         u32 reserved_0;
 772         /**
 773          * The ID of the entity whose name was queried; possible values depends on
 774          * the entity type.
 775          */
 776         u64 entity_id;
 777         /** Reserved for future extensions. */
 778         u64 reserved_1;
 779         /** The name of the entity. */
 780         char entity_name[VPU_TRACE_ENTITY_NAME_MAX_LEN];
 781 };
 782
 783 /**
 784  * Data sent from the VPU to the host in all metric streamer response messages
 785  * and in asynchronous notification.
 786  * @see VPU_JSM_MSG_METRIC_STREAMER_START_DONE
 787  * @see VPU_JSM_MSG_METRIC_STREAMER_STOP_DONE
 788  * @see VPU_JSM_MSG_METRIC_STREAMER_UPDATE_DONE
 789  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO_DONE
 790  * @see VPU_JSM_MSG_METRIC_STREAMER_NOTIFICATION
 791  */
 792 struct vpu_jsm_metric_streamer_done {
 793         /** Metric group mask that identifies metric streamer instance. */
 794         u64 metric_group_mask;
 795         /**
 796          * Size in bytes of single sample - total size of all enabled counters.
 797          * Some VPU implementations may align sample_size to more than 8 bytes.
 798          */
 799         u32 sample_size;
 800         u32 reserved_0;
 801         /**
 802          * Number of samples collected since the metric streamer was started.
 803          * This will be 0 if the metric streamer was not started.
 804          */
 805         u32 samples_collected;
 806         /**
 807          * Number of samples dropped since the metric streamer was started. This
 808          * is incremented every time the metric streamer is not able to write
 809          * collected samples because the current buffer is full and there is no
 810          * next buffer to switch to.
 811          */
 812         u32 samples_dropped;
 813         /** Address of the buffer that contains the latest metric data. */
 814         u64 buffer_addr;
 815         /**
 816          * Number of bytes written into the metric data buffer. In response to the
 817          * VPU_JSM_MSG_METRIC_STREAMER_INFO request this field contains the size of
 818          * all group and counter descriptors. The size is updated even if the buffer
 819          * in the request was NULL or too small to hold descriptors of all counters
 820          */
 821         u64 bytes_written;
 822 };
 823
 824 /**
 825  * Metric group description placed in the metric buffer after successful completion
 826  * of the VPU_JSM_MSG_METRIC_STREAMER_INFO command. This is followed by one or more
 827  * @vpu_jsm_metric_counter_descriptor records.
 828  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
 829  */
 830 struct vpu_jsm_metric_group_descriptor {
 831         /**
 832          * Offset to the next metric group (8-byte aligned). If this offset is 0 this
 833          * is the last descriptor. The value of metric_info_size must be greater than
 834          * or equal to sizeof(struct vpu_jsm_metric_group_descriptor) + name_string_size
 835          * + description_string_size and must be 8-byte aligned.
 836          */
 837         u32 next_metric_group_info_offset;
 838         /**
 839          * Offset to the first metric counter description record (8-byte aligned).
 840          * @see vpu_jsm_metric_counter_descriptor
 841          */
 842         u32 next_metric_counter_info_offset;
 843         /** Index of the group. This corresponds to bit index in metric_group_mask. */
 844         u32 group_id;
 845         /** Number of counters in the metric group. */
 846         u32 num_counters;
 847         /** Data size for all counters, must be a multiple of 8 bytes.*/
 848         u32 metric_group_data_size;
 849         /**
 850          * Metric group domain number. Cannot use multiple, simultaneous metric groups
 851          * from the same domain.
 852          */
 853         u32 domain;
 854         /**
 855          * Counter name string size. The string must include a null termination character.
 856          * The FW may use a fixed size name or send a different name for each counter.
 857          * If the VPU uses fixed size strings, all characters from the end of the name
 858          * to the of the fixed size character array must be zeroed.
 859          */
 860         u32 name_string_size;
 861         /** Counter description string size, @see name_string_size */
 862         u32 description_string_size;
 863         u64 reserved_0;
 864         /**
 865          * Right after this structure, the VPU writes name and description of
 866          * the metric group.
 867          */
 868 };
 869
 870 /**
 871  * Metric counter description, placed in the buffer after vpu_jsm_metric_group_descriptor.
 872  * @see VPU_JSM_MSG_METRIC_STREAMER_INFO
 873  */
 874 struct vpu_jsm_metric_counter_descriptor {
 875         /**
 876          * Offset to the next counter in a group (8-byte aligned). If this offset is
 877          * 0 this is the last counter in the group.
 878          */
 879         u32 next_metric_counter_info_offset;
 880         /**
 881          * Offset to the counter data from the start of samples in this metric group.
 882          * Note that metric_data_offset % metric_data_size must be 0.
 883          */
 884         u32 metric_data_offset;
 885         /** Size of the metric counter data in bytes. */
 886         u32 metric_data_size;
 887         /** Metric type, see Level Zero API for definitions. */
 888         u32 tier;
 889         /** Metric type, see set_metric_type_t for definitions. */
 890         u32 metric_type;
 891         /** Metric type, see set_value_type_t for definitions. */
 892         u32 metric_value_type;
 893         /**
 894          * Counter name string size. The string must include a null termination character.
 895          * The FW may use a fixed size name or send a different name for each counter.
 896          * If the VPU uses fixed size strings, all characters from the end of the name
 897          * to the of the fixed size character array must be zeroed.
 898          */
 899         u32 name_string_size;
 900         /** Counter description string size, @see name_string_size */
 901         u32 description_string_size;
 902         /** Counter component name string size, @see name_string_size */
 903         u32 component_string_size;
 904         /** Counter string size, @see name_string_size */
 905         u32 units_string_size;
 906         u64 reserved_0;
 907         /**
 908          * Right after this structure, the VPU writes name, description
 909          * component and unit strings.
 910          */
 911 };
 912
 913 /**
 914  * Payload for VPU_JSM_MSG_DYNDBG_CONTROL requests.
 915  *
 916  * VPU_JSM_MSG_DYNDBG_CONTROL are used to control the VPU FW Dynamic Debug
 917  * feature, which allows developers to selectively enable / disable MVLOG_DEBUG
 918  * messages. This is equivalent to the Dynamic Debug functionality provided by
 919  * Linux
 920  * (https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html)
 921  * The host can control Dynamic Debug behavior by sending dyndbg commands, which
 922  * have the same syntax as Linux
 923  * dyndbg commands.
 924  *
 925  * NOTE: in order for MVLOG_DEBUG messages to be actually printed, the host
 926  * still has to set the logging level to MVLOG_DEBUG, using the
 927  * VPU_JSM_MSG_TRACE_SET_CONFIG command.
 928  *
 929  * The host can see the current dynamic debug configuration by executing a
 930  * special 'show' command. The dyndbg configuration will be printed to the
 931  * configured logging destination using MVLOG_INFO logging level.
 932  */
 933 struct vpu_ipc_msg_payload_dyndbg_control {
 934         /**
 935          * Dyndbg command (same format as Linux dyndbg); must be a NULL-terminated
 936          * string.
 937          */
 938         char dyndbg_cmd[VPU_DYNDBG_CMD_MAX_LEN];
 939 };
 940
 941 /*
 942  * Payloads union, used to define complete message format.
 943  */
 944 union vpu_ipc_msg_payload {
 945         struct vpu_ipc_msg_payload_engine_reset engine_reset;
 946         struct vpu_ipc_msg_payload_engine_preempt engine_preempt;
 947         struct vpu_ipc_msg_payload_register_db register_db;
 948         struct vpu_ipc_msg_payload_unregister_db unregister_db;
 949         struct vpu_ipc_msg_payload_query_engine_hb query_engine_hb;
 950         struct vpu_ipc_msg_payload_power_level power_level;
 951         struct vpu_jsm_metric_streamer_start metric_streamer_start;
 952         struct vpu_jsm_metric_streamer_stop metric_streamer_stop;
 953         struct vpu_jsm_metric_streamer_update metric_streamer_update;
 954         struct vpu_ipc_msg_payload_blob_deinit blob_deinit;
 955         struct vpu_ipc_msg_payload_ssid_release ssid_release;
 956         struct vpu_jsm_hws_register_db hws_register_db;
 957         struct vpu_ipc_msg_payload_job_done job_done;
 958         struct vpu_ipc_msg_payload_engine_reset_done engine_reset_done;
 959         struct vpu_ipc_msg_payload_engine_preempt_done engine_preempt_done;
 960         struct vpu_ipc_msg_payload_register_db_done register_db_done;
 961         struct vpu_ipc_msg_payload_unregister_db_done unregister_db_done;
 962         struct vpu_ipc_msg_payload_query_engine_hb_done query_engine_hb_done;
 963         struct vpu_ipc_msg_payload_get_power_level_count_done get_power_level_count_done;
 964         struct vpu_jsm_metric_streamer_done metric_streamer_done;
 965         struct vpu_ipc_msg_payload_blob_deinit_done blob_deinit_done;
 966         struct vpu_ipc_msg_payload_trace_config trace_config;
 967         struct vpu_ipc_msg_payload_trace_capability_rsp trace_capability;
 968         struct vpu_ipc_msg_payload_trace_get_name trace_get_name;
 969         struct vpu_ipc_msg_payload_trace_get_name_rsp trace_get_name_rsp;
 970         struct vpu_ipc_msg_payload_dyndbg_control dyndbg_control;
 971         struct vpu_ipc_msg_payload_hws_priority_band_setup hws_priority_band_setup;
 972         struct vpu_ipc_msg_payload_hws_create_cmdq hws_create_cmdq;
 973         struct vpu_ipc_msg_payload_hws_create_cmdq_rsp hws_create_cmdq_rsp;
 974         struct vpu_ipc_msg_payload_hws_destroy_cmdq hws_destroy_cmdq;
 975         struct vpu_ipc_msg_payload_hws_set_context_sched_properties
 976                 hws_set_context_sched_properties;
 977 };
 978
 979 /*
 980  * Host <-> LRT IPC message base structure.
 981  *
 982  * NOTE: All instances of this object must be aligned on a 64B boundary
 983  * to allow proper handling of VPU cache operations.
 984  */
 985 struct vpu_jsm_msg {
 986         /* Reserved */
 987         u64 reserved_0;
 988         /* Message type, see vpu_ipc_msg_type enum. */
 989         u32 type;
 990         /* Buffer status, see vpu_ipc_msg_status enum. */
 991         u32 status;
 992         /*
 993          * Request ID, provided by the host in a request message and passed
 994          * back by VPU in the response message.
 995          */
 996         u32 request_id;
 997         /* Request return code set by the VPU, see VPU_JSM_STATUS_* defines. */
 998         u32 result;
 999         u64 reserved_1;
1000         /* Message payload depending on message type, see vpu_ipc_msg_payload union. */
1001         union vpu_ipc_msg_payload payload;
1002 };
1003
1004 #pragma pack(pop)
1005
1006 #endif
1007
1008 ///@}