1 /* SPDX-License-Identifier: BSD-3-Clause 2 * 3 * Copyright(c) 2016 Intel Corporation. All rights reserved. 4 * 5 * Author: Liam Girdwood <liam.r.girdwood@linux.intel.com> 6 * Keyon Jie <yang.jie@linux.intel.com> 7 */ 8 9 /** 10 * \file include/ipc/header.h 11 * \brief IPC command header 12 * \author Liam Girdwood <liam.r.girdwood@linux.intel.com> 13 * \author Keyon Jie <yang.jie@linux.intel.com> 14 */ 15 16 #ifndef __IPC_HEADER_H__ 17 #define __IPC_HEADER_H__ 18 19 #include <stdint.h> 20 21 /** 22 * Common IPC logic uses standard types for abstract IPC features. This means all ABI MAJOR 23 * abstraction is done in the IPC layer only and not in the surrounding infrastructure. 24 */ 25 #if CONFIG_IPC_MAJOR_3 26 #include <ipc3/header.h> 27 #elif CONFIG_IPC_MAJOR_4 28 #include <ipc4/header.h> 29 #endif 30 31 /** 32 * Generic IPC Header structure - Header for all IPC structures which provides 33 * abstraction of IPC header implementation for different IPC ABI MAJOR types. 34 */ 35 struct ipc_cmd_hdr; 36 37 #define ipc_to_hdr(x) ((struct ipc_cmd_hdr *)x) 38 39 /** \addtogroup sof_uapi uAPI 40 * SOF uAPI specification 41 * 42 * **Overview** 43 * 44 * The SOF Audio DSP firmware defines an Inter-Process Communication 45 * (IPC) interface to facilitate communication with the host. 46 * 47 * The SOF IPC is bi-directional. Messages can be initiated by the 48 * host and acknowledged by the DSP. Similarly, they can be initiated 49 * by the DSP and acknowledged by the host. 50 * 51 * IPC messages are divided into several groups: global, topology, 52 * power management, component, stream, DAI, trace, and a separate 53 * "firmware ready" message. Multiple messages can also be grouped 54 * into a message that belong to a compound group. Most messages are 55 * sent by the host to the DSP; only the following messages are sent 56 * by the DSP to the host: 57 * - firmware ready: sent only once during initialization 58 * - trace: optional, contains firmware trace data 59 * - position update: only used if position data cannot be 60 * transferred in a memory window or if forced by the kernel 61 * configuration 62 * 63 * **Message encoding** 64 * 65 * All multi-byte protocol fields are encoded with little-endian 66 * byte-order. 67 * 68 * **Message structure** 69 * 70 * IPC messages have a fixed header and variable length payload. 71 * 72 * 0 1 2 3 73 * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 74 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 75 * | Size | 76 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 77 * | Command | 78 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 79 * 80 * The header contains size of the IPC message and a 32bit Command 81 * identifier with following structure: 82 * 83 * 0xGCCCNNNN is little-endian value where 84 * - G is the Global Type (4 bits) 85 * - C is the Command Type (12 bits) 86 * - N is the ID Number (16 bits) - monotonic and overflows 87 * 88 * The Global and Command Types together define the structure of the 89 * payload. E.g. for topology IPC message COMP_NEW structure is (ABI 90 * 3.17.0 example): 91 * 92 * 0 1 2 3 93 * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 94 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 95 * | Size (Total size including Extended Data) | 96 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 97 * | Command (G=TPLG_MSG, C=COMP_NEW) | 98 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 99 * | Component ID | 100 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 101 * | Type | 102 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 103 * | Pipeline ID | 104 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 105 * | Core | 106 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 107 * | Extended Data size | 108 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 109 * | Type specific payload, size varies based on Component ID. | 110 * | Ends at: Total size - Extended Data size | 111 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 112 * | extended data, including e.g. UUID | 113 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 114 * 115 * \see sof_ipc_comp 116 * 117 * **Reply Messages** 118 * 119 * Reply messages are defined per Command. The response IPC messages 120 * have a common layout, but some Commands have extended fields 121 * defined. The common format is: 122 * 123 * 0 1 2 3 124 * 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 125 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 126 * | Size | 127 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 128 * | Command (G=REPLY, C=0) | 129 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 130 * | Error | 131 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 132 * 133 * \see sof_ipc_reply 134 * 135 * **IPC ABI version compatibility rules** 136 * 137 * 1. FW binaries will only support one MAJOR ABI version which is advertised 138 * to host at FW boot. 139 * 140 * 2. Host drivers will support the current and older MAJOR ABI versions of 141 * the IPC ABI (up to a certain age to be determined by market information). 142 * 143 * 3. MINOR and PATCH ABI versions can differ between host and FW but must be 144 * backwards compatible on both host and FW. 145 * 146 * IPC messages sizes can be different for sender and receiver if MINOR or 147 * PATCH ABI versions differ as new fields can be added to the end of 148 * messages. 149 * 150 * i) SenderVersion > ReceiverVersion: 151 * Receiver only copies its own ABI structure size. 152 * 153 * ii) ReceiverVersion > SenderVersion: 154 * Receiver copies its own ABI size and zero pads 155 * new fields. i.e. new structure fields must be non 156 * zero to be activated. 157 * 158 * Guidelines for extending ABI compatible messages :- 159 * 160 * - i) Use reserved fields. 161 * 162 * - ii) Grow structure at the end. 163 * 164 * - iii) Iff (i) and (ii) are not possible then MAJOR ABI is bumped. 165 * 166 * @{ 167 */ 168 169 /** \name Global Message - Generic 170 * @{ 171 */ 172 173 /** Shift-left bits to extract the global cmd type */ 174 #define SOF_GLB_TYPE_SHIFT 28 175 #define SOF_GLB_TYPE_MASK (0xfUL << SOF_GLB_TYPE_SHIFT) 176 #define SOF_GLB_TYPE(x) ((x) << SOF_GLB_TYPE_SHIFT) 177 178 /** @} */ 179 180 /** \name Command Message - Generic 181 * @{ 182 */ 183 184 /** Shift-left bits to extract the command type */ 185 #define SOF_CMD_TYPE_SHIFT 16 186 #define SOF_CMD_TYPE_MASK (0xfffL << SOF_CMD_TYPE_SHIFT) 187 #define SOF_CMD_TYPE(x) ((x) << SOF_CMD_TYPE_SHIFT) 188 189 /** @} */ 190 191 /** \name Global Message Types 192 * @{ 193 */ 194 195 #define SOF_IPC_GLB_REPLY SOF_GLB_TYPE(0x1U) 196 #define SOF_IPC_GLB_COMPOUND SOF_GLB_TYPE(0x2U) 197 #define SOF_IPC_GLB_TPLG_MSG SOF_GLB_TYPE(0x3U) 198 #define SOF_IPC_GLB_PM_MSG SOF_GLB_TYPE(0x4U) 199 #define SOF_IPC_GLB_COMP_MSG SOF_GLB_TYPE(0x5U) 200 #define SOF_IPC_GLB_STREAM_MSG SOF_GLB_TYPE(0x6U) 201 #define SOF_IPC_FW_READY SOF_GLB_TYPE(0x7U) 202 #define SOF_IPC_GLB_DAI_MSG SOF_GLB_TYPE(0x8U) 203 #define SOF_IPC_GLB_TRACE_MSG SOF_GLB_TYPE(0x9U) 204 #define SOF_IPC_GLB_GDB_DEBUG SOF_GLB_TYPE(0xAU) 205 #define SOF_IPC_GLB_TEST SOF_GLB_TYPE(0xBU) 206 #define SOF_IPC_GLB_PROBE SOF_GLB_TYPE(0xCU) 207 #define SOF_IPC_GLB_DEBUG SOF_GLB_TYPE(0xDU) 208 209 /** @} */ 210 211 /** \name DSP Command: Topology 212 * \anchor tplg_cmd_type 213 * @{ 214 */ 215 216 #define SOF_IPC_TPLG_COMP_NEW SOF_CMD_TYPE(0x001) 217 #define SOF_IPC_TPLG_COMP_FREE SOF_CMD_TYPE(0x002) 218 #define SOF_IPC_TPLG_COMP_CONNECT SOF_CMD_TYPE(0x003) 219 #define SOF_IPC_TPLG_PIPE_NEW SOF_CMD_TYPE(0x010) 220 #define SOF_IPC_TPLG_PIPE_FREE SOF_CMD_TYPE(0x011) 221 #define SOF_IPC_TPLG_PIPE_CONNECT SOF_CMD_TYPE(0x012) 222 #define SOF_IPC_TPLG_PIPE_COMPLETE SOF_CMD_TYPE(0x013) 223 #define SOF_IPC_TPLG_BUFFER_NEW SOF_CMD_TYPE(0x020) 224 #define SOF_IPC_TPLG_BUFFER_FREE SOF_CMD_TYPE(0x021) 225 226 /** @} */ 227 228 /** \name DSP Command: PM 229 * @{ 230 */ 231 232 #define SOF_IPC_PM_CTX_SAVE SOF_CMD_TYPE(0x001) 233 #define SOF_IPC_PM_CTX_RESTORE SOF_CMD_TYPE(0x002) 234 #define SOF_IPC_PM_CTX_SIZE SOF_CMD_TYPE(0x003) 235 #define SOF_IPC_PM_CLK_SET SOF_CMD_TYPE(0x004) 236 #define SOF_IPC_PM_CLK_GET SOF_CMD_TYPE(0x005) 237 #define SOF_IPC_PM_CLK_REQ SOF_CMD_TYPE(0x006) 238 #define SOF_IPC_PM_CORE_ENABLE SOF_CMD_TYPE(0x007) 239 #define SOF_IPC_PM_GATE SOF_CMD_TYPE(0x008) 240 241 /** @} */ 242 243 /** \name DSP Command: Component runtime config - multiple different types 244 * @{ 245 */ 246 247 #define SOF_IPC_COMP_SET_VALUE SOF_CMD_TYPE(0x001) 248 #define SOF_IPC_COMP_GET_VALUE SOF_CMD_TYPE(0x002) 249 #define SOF_IPC_COMP_SET_DATA SOF_CMD_TYPE(0x003) 250 #define SOF_IPC_COMP_GET_DATA SOF_CMD_TYPE(0x004) 251 #define SOF_IPC_COMP_NOTIFICATION SOF_CMD_TYPE(0x005) 252 253 /** @} */ 254 255 /** \name DSP Command: DAI messages 256 * @{ 257 */ 258 #define SOF_IPC_DAI_CONFIG SOF_CMD_TYPE(0x001) 259 #define SOF_IPC_DAI_LOOPBACK SOF_CMD_TYPE(0x002) 260 261 /** @} */ 262 263 /** \name DSP Command: Stream 264 * @{ 265 */ 266 #define SOF_IPC_STREAM_PCM_PARAMS SOF_CMD_TYPE(0x001) 267 #define SOF_IPC_STREAM_PCM_PARAMS_REPLY SOF_CMD_TYPE(0x002) 268 #define SOF_IPC_STREAM_PCM_FREE SOF_CMD_TYPE(0x003) 269 #define SOF_IPC_STREAM_TRIG_START SOF_CMD_TYPE(0x004) 270 #define SOF_IPC_STREAM_TRIG_STOP SOF_CMD_TYPE(0x005) 271 #define SOF_IPC_STREAM_TRIG_PAUSE SOF_CMD_TYPE(0x006) 272 #define SOF_IPC_STREAM_TRIG_RELEASE SOF_CMD_TYPE(0x007) 273 #define SOF_IPC_STREAM_TRIG_DRAIN SOF_CMD_TYPE(0x008) 274 #define SOF_IPC_STREAM_TRIG_XRUN SOF_CMD_TYPE(0x009) 275 #define SOF_IPC_STREAM_POSITION SOF_CMD_TYPE(0x00a) 276 #define SOF_IPC_STREAM_VORBIS_PARAMS SOF_CMD_TYPE(0x010) 277 #define SOF_IPC_STREAM_VORBIS_FREE SOF_CMD_TYPE(0x011) 278 279 /** @} */ 280 281 /** \name DSP Command: Trace and debug 282 * @{ 283 */ 284 285 #define SOF_IPC_TRACE_DMA_PARAMS SOF_CMD_TYPE(0x001) 286 #define SOF_IPC_TRACE_DMA_POSITION SOF_CMD_TYPE(0x002) 287 #define SOF_IPC_TRACE_DMA_PARAMS_EXT SOF_CMD_TYPE(0x003) 288 #define SOF_IPC_TRACE_FILTER_UPDATE SOF_CMD_TYPE(0x004) /**< ABI3.17 */ 289 #define SOF_IPC_TRACE_DMA_FREE SOF_CMD_TYPE(0x005) /**< ABI3.20 */ 290 291 /** @} */ 292 293 /** \name DSP Command: Probes 294 * @{ 295 */ 296 297 #define SOF_IPC_PROBE_INIT SOF_CMD_TYPE(0x001) 298 #define SOF_IPC_PROBE_DEINIT SOF_CMD_TYPE(0x002) 299 #define SOF_IPC_PROBE_DMA_ADD SOF_CMD_TYPE(0x003) 300 #define SOF_IPC_PROBE_DMA_INFO SOF_CMD_TYPE(0x004) 301 #define SOF_IPC_PROBE_DMA_REMOVE SOF_CMD_TYPE(0x005) 302 #define SOF_IPC_PROBE_POINT_ADD SOF_CMD_TYPE(0x006) 303 #define SOF_IPC_PROBE_POINT_INFO SOF_CMD_TYPE(0x007) 304 #define SOF_IPC_PROBE_POINT_REMOVE SOF_CMD_TYPE(0x008) 305 306 /** @} */ 307 308 /** \name DSP Command: Debug - additional services 309 * @{ 310 */ 311 312 #define SOF_IPC_DEBUG_MEM_USAGE SOF_CMD_TYPE(0x001) 313 314 /** @} */ 315 316 /** \name DSP Command: Test - Debug build only 317 * @{ 318 */ 319 320 #define SOF_IPC_TEST_IPC_FLOOD SOF_CMD_TYPE(0x001) 321 322 /** @} */ 323 324 /** \name IPC Message Definitions 325 * @{ 326 */ 327 328 /** Get message component id */ 329 #define SOF_IPC_MESSAGE_ID(x) ((x) & 0xffff) 330 331 /** Maximum message size for mailbox Tx/Rx */ 332 #define SOF_IPC_MSG_MAX_SIZE 384 333 334 /** @} */ 335 336 /** 337 * Structure Header - Header for all IPC structures except command structs. 338 * The size can be greater than the structure size and that means there is 339 * extended bespoke data beyond the end of the structure including variable 340 * arrays. 341 */ 342 struct sof_ipc_hdr { 343 uint32_t size; /**< size of structure */ 344 } __attribute__((packed, aligned(4))); 345 346 /** 347 * Command Header - Header for all IPC commands. Identifies IPC message. 348 * The size can be greater than the structure size and that means there is 349 * extended bespoke data beyond the end of the structure including variable 350 * arrays. 351 */ 352 struct sof_ipc_cmd_hdr { 353 uint32_t size; /**< size of structure */ 354 uint32_t cmd; /**< SOF_IPC_GLB_ + cmd */ 355 } __attribute__((packed, aligned(4))); 356 357 /** 358 * Generic reply message. Some commands override this with their own reply 359 * types that must include this at start. 360 */ 361 struct sof_ipc_reply { 362 struct sof_ipc_cmd_hdr hdr; 363 int32_t error; /**< negative error numbers */ 364 } __attribute__((packed, aligned(4))); 365 366 /** 367 * Compound commands - SOF_IPC_GLB_COMPOUND. 368 * 369 * Compound commands are sent to the DSP as a single IPC operation. The 370 * commands are split into blocks and each block has a header. This header 371 * identifies the command type and the number of commands before the next 372 * header. 373 */ 374 struct sof_ipc_compound_hdr { 375 struct sof_ipc_cmd_hdr hdr; 376 uint32_t count; /**< count of 0 means end of compound sequence */ 377 } __attribute__((packed, aligned(4))); 378 379 /** 380 * OOPS header architecture specific data. 381 */ 382 struct sof_ipc_dsp_oops_arch_hdr { 383 uint32_t arch; /* Identifier of architecture */ 384 uint32_t totalsize; /* Total size of oops message */ 385 } __attribute__((packed, aligned(4))); 386 387 /** 388 * OOPS header platform specific data. 389 */ 390 struct sof_ipc_dsp_oops_plat_hdr { 391 uint32_t configidhi; /* ConfigID hi 32bits */ 392 uint32_t configidlo; /* ConfigID lo 32bits */ 393 uint32_t numaregs; /* Special regs num */ 394 uint32_t stackoffset; /* Offset to stack pointer from beginning of 395 * oops message 396 */ 397 uint32_t stackptr; /* Stack ptr */ 398 } __attribute__((packed, aligned(4))); 399 400 /** @}*/ 401 402 #endif /* __IPC_HEADER_H__ */ 403
