guc_messages_abi.h revision 1.2
1/* SPDX-License-Identifier: MIT */ 2/* 3 * Copyright �� 2014-2021 Intel Corporation 4 */ 5 6#ifndef _ABI_GUC_MESSAGES_ABI_H 7#define _ABI_GUC_MESSAGES_ABI_H 8 9/** 10 * DOC: HXG Message 11 * 12 * All messages exchanged with GuC are defined using 32 bit dwords. 13 * First dword is treated as a message header. Remaining dwords are optional. 14 * 15 * +---+-------+--------------------------------------------------------------+ 16 * | | Bits | Description | 17 * +===+=======+==============================================================+ 18 * | | | | 19 * | 0 | 31 | **ORIGIN** - originator of the message | 20 * | | | - _`GUC_HXG_ORIGIN_HOST` = 0 | 21 * | | | - _`GUC_HXG_ORIGIN_GUC` = 1 | 22 * | | | | 23 * | +-------+--------------------------------------------------------------+ 24 * | | 30:28 | **TYPE** - message type | 25 * | | | - _`GUC_HXG_TYPE_REQUEST` = 0 | 26 * | | | - _`GUC_HXG_TYPE_EVENT` = 1 | 27 * | | | - _`GUC_HXG_TYPE_NO_RESPONSE_BUSY` = 3 | 28 * | | | - _`GUC_HXG_TYPE_NO_RESPONSE_RETRY` = 5 | 29 * | | | - _`GUC_HXG_TYPE_RESPONSE_FAILURE` = 6 | 30 * | | | - _`GUC_HXG_TYPE_RESPONSE_SUCCESS` = 7 | 31 * | +-------+--------------------------------------------------------------+ 32 * | | 27:0 | **AUX** - auxiliary data (depends on TYPE) | 33 * +---+-------+--------------------------------------------------------------+ 34 * | 1 | 31:0 | | 35 * +---+-------+ | 36 * |...| | **PAYLOAD** - optional payload (depends on TYPE) | 37 * +---+-------+ | 38 * | n | 31:0 | | 39 * +---+-------+--------------------------------------------------------------+ 40 */ 41 42#define GUC_HXG_MSG_MIN_LEN 1u 43#define GUC_HXG_MSG_0_ORIGIN (0x1U << 31) 44#define GUC_HXG_ORIGIN_HOST 0u 45#define GUC_HXG_ORIGIN_GUC 1u 46#define GUC_HXG_MSG_0_TYPE (0x7 << 28) 47#define GUC_HXG_TYPE_REQUEST 0u 48#define GUC_HXG_TYPE_EVENT 1u 49#define GUC_HXG_TYPE_NO_RESPONSE_BUSY 3u 50#define GUC_HXG_TYPE_NO_RESPONSE_RETRY 5u 51#define GUC_HXG_TYPE_RESPONSE_FAILURE 6u 52#define GUC_HXG_TYPE_RESPONSE_SUCCESS 7u 53#define GUC_HXG_MSG_0_AUX (0xfffffff << 0) 54#define GUC_HXG_MSG_n_PAYLOAD (0xffffffff << 0) 55 56/** 57 * DOC: HXG Request 58 * 59 * The `HXG Request`_ message should be used to initiate synchronous activity 60 * for which confirmation or return data is expected. 61 * 62 * The recipient of this message shall use `HXG Response`_, `HXG Failure`_ 63 * or `HXG Retry`_ message as a definite reply, and may use `HXG Busy`_ 64 * message as a intermediate reply. 65 * 66 * Format of @DATA0 and all @DATAn fields depends on the @ACTION code. 67 * 68 * +---+-------+--------------------------------------------------------------+ 69 * | | Bits | Description | 70 * +===+=======+==============================================================+ 71 * | 0 | 31 | ORIGIN | 72 * | +-------+--------------------------------------------------------------+ 73 * | | 30:28 | TYPE = GUC_HXG_TYPE_REQUEST_ | 74 * | +-------+--------------------------------------------------------------+ 75 * | | 27:16 | **DATA0** - request data (depends on ACTION) | 76 * | +-------+--------------------------------------------------------------+ 77 * | | 15:0 | **ACTION** - requested action code | 78 * +---+-------+--------------------------------------------------------------+ 79 * | 1 | 31:0 | | 80 * +---+-------+ | 81 * |...| | **DATAn** - optional data (depends on ACTION) | 82 * +---+-------+ | 83 * | n | 31:0 | | 84 * +---+-------+--------------------------------------------------------------+ 85 */ 86 87#define GUC_HXG_REQUEST_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 88#define GUC_HXG_REQUEST_MSG_0_DATA0 (0xfff << 16) 89#define GUC_HXG_REQUEST_MSG_0_ACTION (0xffff << 0) 90#define GUC_HXG_REQUEST_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 91 92/** 93 * DOC: HXG Event 94 * 95 * The `HXG Event`_ message should be used to initiate asynchronous activity 96 * that does not involves immediate confirmation nor data. 97 * 98 * Format of @DATA0 and all @DATAn fields depends on the @ACTION code. 99 * 100 * +---+-------+--------------------------------------------------------------+ 101 * | | Bits | Description | 102 * +===+=======+==============================================================+ 103 * | 0 | 31 | ORIGIN | 104 * | +-------+--------------------------------------------------------------+ 105 * | | 30:28 | TYPE = GUC_HXG_TYPE_EVENT_ | 106 * | +-------+--------------------------------------------------------------+ 107 * | | 27:16 | **DATA0** - event data (depends on ACTION) | 108 * | +-------+--------------------------------------------------------------+ 109 * | | 15:0 | **ACTION** - event action code | 110 * +---+-------+--------------------------------------------------------------+ 111 * | 1 | 31:0 | | 112 * +---+-------+ | 113 * |...| | **DATAn** - optional event data (depends on ACTION) | 114 * +---+-------+ | 115 * | n | 31:0 | | 116 * +---+-------+--------------------------------------------------------------+ 117 */ 118 119#define GUC_HXG_EVENT_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 120#define GUC_HXG_EVENT_MSG_0_DATA0 (0xfff << 16) 121#define GUC_HXG_EVENT_MSG_0_ACTION (0xffff << 0) 122#define GUC_HXG_EVENT_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 123 124/** 125 * DOC: HXG Busy 126 * 127 * The `HXG Busy`_ message may be used to acknowledge reception of the `HXG Request`_ 128 * message if the recipient expects that it processing will be longer than default 129 * timeout. 130 * 131 * The @COUNTER field may be used as a progress indicator. 132 * 133 * +---+-------+--------------------------------------------------------------+ 134 * | | Bits | Description | 135 * +===+=======+==============================================================+ 136 * | 0 | 31 | ORIGIN | 137 * | +-------+--------------------------------------------------------------+ 138 * | | 30:28 | TYPE = GUC_HXG_TYPE_NO_RESPONSE_BUSY_ | 139 * | +-------+--------------------------------------------------------------+ 140 * | | 27:0 | **COUNTER** - progress indicator | 141 * +---+-------+--------------------------------------------------------------+ 142 */ 143 144#define GUC_HXG_BUSY_MSG_LEN GUC_HXG_MSG_MIN_LEN 145#define GUC_HXG_BUSY_MSG_0_COUNTER GUC_HXG_MSG_0_AUX 146 147/** 148 * DOC: HXG Retry 149 * 150 * The `HXG Retry`_ message should be used by recipient to indicate that the 151 * `HXG Request`_ message was dropped and it should be resent again. 152 * 153 * The @REASON field may be used to provide additional information. 154 * 155 * +---+-------+--------------------------------------------------------------+ 156 * | | Bits | Description | 157 * +===+=======+==============================================================+ 158 * | 0 | 31 | ORIGIN | 159 * | +-------+--------------------------------------------------------------+ 160 * | | 30:28 | TYPE = GUC_HXG_TYPE_NO_RESPONSE_RETRY_ | 161 * | +-------+--------------------------------------------------------------+ 162 * | | 27:0 | **REASON** - reason for retry | 163 * | | | - _`GUC_HXG_RETRY_REASON_UNSPECIFIED` = 0 | 164 * +---+-------+--------------------------------------------------------------+ 165 */ 166 167#define GUC_HXG_RETRY_MSG_LEN GUC_HXG_MSG_MIN_LEN 168#define GUC_HXG_RETRY_MSG_0_REASON GUC_HXG_MSG_0_AUX 169#define GUC_HXG_RETRY_REASON_UNSPECIFIED 0u 170 171/** 172 * DOC: HXG Failure 173 * 174 * The `HXG Failure`_ message shall be used as a reply to the `HXG Request`_ 175 * message that could not be processed due to an error. 176 * 177 * +---+-------+--------------------------------------------------------------+ 178 * | | Bits | Description | 179 * +===+=======+==============================================================+ 180 * | 0 | 31 | ORIGIN | 181 * | +-------+--------------------------------------------------------------+ 182 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_FAILURE_ | 183 * | +-------+--------------------------------------------------------------+ 184 * | | 27:16 | **HINT** - additional error hint | 185 * | +-------+--------------------------------------------------------------+ 186 * | | 15:0 | **ERROR** - error/result code | 187 * +---+-------+--------------------------------------------------------------+ 188 */ 189 190#define GUC_HXG_FAILURE_MSG_LEN GUC_HXG_MSG_MIN_LEN 191#define GUC_HXG_FAILURE_MSG_0_HINT (0xfff << 16) 192#define GUC_HXG_FAILURE_MSG_0_ERROR (0xffff << 0) 193 194/** 195 * DOC: HXG Response 196 * 197 * The `HXG Response`_ message shall be used as a reply to the `HXG Request`_ 198 * message that was successfully processed without an error. 199 * 200 * +---+-------+--------------------------------------------------------------+ 201 * | | Bits | Description | 202 * +===+=======+==============================================================+ 203 * | 0 | 31 | ORIGIN | 204 * | +-------+--------------------------------------------------------------+ 205 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_SUCCESS_ | 206 * | +-------+--------------------------------------------------------------+ 207 * | | 27:0 | **DATA0** - data (depends on ACTION from `HXG Request`_) | 208 * +---+-------+--------------------------------------------------------------+ 209 * | 1 | 31:0 | | 210 * +---+-------+ | 211 * |...| | **DATAn** - data (depends on ACTION from `HXG Request`_) | 212 * +---+-------+ | 213 * | n | 31:0 | | 214 * +---+-------+--------------------------------------------------------------+ 215 */ 216 217#define GUC_HXG_RESPONSE_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 218#define GUC_HXG_RESPONSE_MSG_0_DATA0 GUC_HXG_MSG_0_AUX 219#define GUC_HXG_RESPONSE_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 220 221/* deprecated */ 222#define INTEL_GUC_MSG_TYPE_SHIFT 28 223#define INTEL_GUC_MSG_TYPE_MASK (0xF << INTEL_GUC_MSG_TYPE_SHIFT) 224#define INTEL_GUC_MSG_DATA_SHIFT 16 225#define INTEL_GUC_MSG_DATA_MASK (0xFFF << INTEL_GUC_MSG_DATA_SHIFT) 226#define INTEL_GUC_MSG_CODE_SHIFT 0 227#define INTEL_GUC_MSG_CODE_MASK (0xFFFF << INTEL_GUC_MSG_CODE_SHIFT) 228 229enum intel_guc_msg_type { 230 INTEL_GUC_MSG_TYPE_REQUEST = 0x0, 231 INTEL_GUC_MSG_TYPE_RESPONSE = 0xF, 232}; 233 234#endif /* _ABI_GUC_MESSAGES_ABI_H */ 235