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_FAST_REQUEST` = 2 | 28 * | | | - _`GUC_HXG_TYPE_NO_RESPONSE_BUSY` = 3 | 29 * | | | - _`GUC_HXG_TYPE_NO_RESPONSE_RETRY` = 5 | 30 * | | | - _`GUC_HXG_TYPE_RESPONSE_FAILURE` = 6 | 31 * | | | - _`GUC_HXG_TYPE_RESPONSE_SUCCESS` = 7 | 32 * | +-------+--------------------------------------------------------------+ 33 * | | 27:0 | **AUX** - auxiliary data (depends on TYPE) | 34 * +---+-------+--------------------------------------------------------------+ 35 * | 1 | 31:0 | | 36 * +---+-------+ | 37 * |...| | **PAYLOAD** - optional payload (depends on TYPE) | 38 * +---+-------+ | 39 * | n | 31:0 | | 40 * +---+-------+--------------------------------------------------------------+ 41 */ 42 43 #define GUC_HXG_MSG_MIN_LEN 1u 44 #define GUC_HXG_MSG_0_ORIGIN (0x1u << 31) 45 #define GUC_HXG_ORIGIN_HOST 0u 46 #define GUC_HXG_ORIGIN_GUC 1u 47 #define GUC_HXG_MSG_0_TYPE (0x7u << 28) 48 #define GUC_HXG_TYPE_REQUEST 0u 49 #define GUC_HXG_TYPE_EVENT 1u 50 #define GUC_HXG_TYPE_FAST_REQUEST 2u 51 #define GUC_HXG_TYPE_NO_RESPONSE_BUSY 3u 52 #define GUC_HXG_TYPE_NO_RESPONSE_RETRY 5u 53 #define GUC_HXG_TYPE_RESPONSE_FAILURE 6u 54 #define GUC_HXG_TYPE_RESPONSE_SUCCESS 7u 55 #define GUC_HXG_MSG_0_AUX (0xfffffffu << 0) 56 #define GUC_HXG_MSG_n_PAYLOAD (0xffffffffu << 0) 57 58 /** 59 * DOC: HXG Request 60 * 61 * The `HXG Request`_ message should be used to initiate synchronous activity 62 * for which confirmation or return data is expected. 63 * 64 * The recipient of this message shall use `HXG Response`_, `HXG Failure`_ 65 * or `HXG Retry`_ message as a definite reply, and may use `HXG Busy`_ 66 * message as a intermediate reply. 67 * 68 * Format of @DATA0 and all @DATAn fields depends on the @ACTION code. 69 * 70 * +---+-------+--------------------------------------------------------------+ 71 * | | Bits | Description | 72 * +===+=======+==============================================================+ 73 * | 0 | 31 | ORIGIN | 74 * | +-------+--------------------------------------------------------------+ 75 * | | 30:28 | TYPE = GUC_HXG_TYPE_REQUEST_ | 76 * | +-------+--------------------------------------------------------------+ 77 * | | 27:16 | **DATA0** - request data (depends on ACTION) | 78 * | +-------+--------------------------------------------------------------+ 79 * | | 15:0 | **ACTION** - requested action code | 80 * +---+-------+--------------------------------------------------------------+ 81 * | 1 | 31:0 | | 82 * +---+-------+ | 83 * |...| | **DATAn** - optional data (depends on ACTION) | 84 * +---+-------+ | 85 * | n | 31:0 | | 86 * +---+-------+--------------------------------------------------------------+ 87 */ 88 89 #define GUC_HXG_REQUEST_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 90 #define GUC_HXG_REQUEST_MSG_0_DATA0 (0xfffu << 16) 91 #define GUC_HXG_REQUEST_MSG_0_ACTION (0xffffu << 0) 92 #define GUC_HXG_REQUEST_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 93 94 /** 95 * DOC: HXG Fast Request 96 * 97 * The `HXG Request`_ message should be used to initiate asynchronous activity 98 * for which confirmation or return data is not expected. 99 * 100 * If confirmation is required then `HXG Request`_ shall be used instead. 101 * 102 * The recipient of this message may only use `HXG Failure`_ message if it was 103 * unable to accept this request (like invalid data). 104 * 105 * Format of `HXG Fast Request`_ message is same as `HXG Request`_ except @TYPE. 106 * 107 * +---+-------+--------------------------------------------------------------+ 108 * | | Bits | Description | 109 * +===+=======+==============================================================+ 110 * | 0 | 31 | ORIGIN - see `HXG Message`_ | 111 * | +-------+--------------------------------------------------------------+ 112 * | | 30:28 | TYPE = `GUC_HXG_TYPE_FAST_REQUEST`_ | 113 * | +-------+--------------------------------------------------------------+ 114 * | | 27:16 | DATA0 - see `HXG Request`_ | 115 * | +-------+--------------------------------------------------------------+ 116 * | | 15:0 | ACTION - see `HXG Request`_ | 117 * +---+-------+--------------------------------------------------------------+ 118 * |...| | DATAn - see `HXG Request`_ | 119 * +---+-------+--------------------------------------------------------------+ 120 */ 121 122 /** 123 * DOC: HXG Event 124 * 125 * The `HXG Event`_ message should be used to initiate asynchronous activity 126 * that does not involves immediate confirmation nor data. 127 * 128 * Format of @DATA0 and all @DATAn fields depends on the @ACTION code. 129 * 130 * +---+-------+--------------------------------------------------------------+ 131 * | | Bits | Description | 132 * +===+=======+==============================================================+ 133 * | 0 | 31 | ORIGIN | 134 * | +-------+--------------------------------------------------------------+ 135 * | | 30:28 | TYPE = GUC_HXG_TYPE_EVENT_ | 136 * | +-------+--------------------------------------------------------------+ 137 * | | 27:16 | **DATA0** - event data (depends on ACTION) | 138 * | +-------+--------------------------------------------------------------+ 139 * | | 15:0 | **ACTION** - event action code | 140 * +---+-------+--------------------------------------------------------------+ 141 * | 1 | 31:0 | | 142 * +---+-------+ | 143 * |...| | **DATAn** - optional event data (depends on ACTION) | 144 * +---+-------+ | 145 * | n | 31:0 | | 146 * +---+-------+--------------------------------------------------------------+ 147 */ 148 149 #define GUC_HXG_EVENT_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 150 #define GUC_HXG_EVENT_MSG_0_DATA0 (0xfffu << 16) 151 #define GUC_HXG_EVENT_MSG_0_ACTION (0xffffu << 0) 152 #define GUC_HXG_EVENT_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 153 154 /** 155 * DOC: HXG Busy 156 * 157 * The `HXG Busy`_ message may be used to acknowledge reception of the `HXG Request`_ 158 * message if the recipient expects that it processing will be longer than default 159 * timeout. 160 * 161 * The @COUNTER field may be used as a progress indicator. 162 * 163 * +---+-------+--------------------------------------------------------------+ 164 * | | Bits | Description | 165 * +===+=======+==============================================================+ 166 * | 0 | 31 | ORIGIN | 167 * | +-------+--------------------------------------------------------------+ 168 * | | 30:28 | TYPE = GUC_HXG_TYPE_NO_RESPONSE_BUSY_ | 169 * | +-------+--------------------------------------------------------------+ 170 * | | 27:0 | **COUNTER** - progress indicator | 171 * +---+-------+--------------------------------------------------------------+ 172 */ 173 174 #define GUC_HXG_BUSY_MSG_LEN GUC_HXG_MSG_MIN_LEN 175 #define GUC_HXG_BUSY_MSG_0_COUNTER GUC_HXG_MSG_0_AUX 176 177 /** 178 * DOC: HXG Retry 179 * 180 * The `HXG Retry`_ message should be used by recipient to indicate that the 181 * `HXG Request`_ message was dropped and it should be resent again. 182 * 183 * The @REASON field may be used to provide additional information. 184 * 185 * +---+-------+--------------------------------------------------------------+ 186 * | | Bits | Description | 187 * +===+=======+==============================================================+ 188 * | 0 | 31 | ORIGIN | 189 * | +-------+--------------------------------------------------------------+ 190 * | | 30:28 | TYPE = GUC_HXG_TYPE_NO_RESPONSE_RETRY_ | 191 * | +-------+--------------------------------------------------------------+ 192 * | | 27:0 | **REASON** - reason for retry | 193 * | | | - _`GUC_HXG_RETRY_REASON_UNSPECIFIED` = 0 | 194 * +---+-------+--------------------------------------------------------------+ 195 */ 196 197 #define GUC_HXG_RETRY_MSG_LEN GUC_HXG_MSG_MIN_LEN 198 #define GUC_HXG_RETRY_MSG_0_REASON GUC_HXG_MSG_0_AUX 199 #define GUC_HXG_RETRY_REASON_UNSPECIFIED 0u 200 201 /** 202 * DOC: HXG Failure 203 * 204 * The `HXG Failure`_ message shall be used as a reply to the `HXG Request`_ 205 * message that could not be processed due to an error. 206 * 207 * +---+-------+--------------------------------------------------------------+ 208 * | | Bits | Description | 209 * +===+=======+==============================================================+ 210 * | 0 | 31 | ORIGIN | 211 * | +-------+--------------------------------------------------------------+ 212 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_FAILURE_ | 213 * | +-------+--------------------------------------------------------------+ 214 * | | 27:16 | **HINT** - additional error hint | 215 * | +-------+--------------------------------------------------------------+ 216 * | | 15:0 | **ERROR** - error/result code | 217 * +---+-------+--------------------------------------------------------------+ 218 */ 219 220 #define GUC_HXG_FAILURE_MSG_LEN GUC_HXG_MSG_MIN_LEN 221 #define GUC_HXG_FAILURE_MSG_0_HINT (0xfffu << 16) 222 #define GUC_HXG_FAILURE_MSG_0_ERROR (0xffffu << 0) 223 224 /** 225 * DOC: HXG Response 226 * 227 * The `HXG Response`_ message shall be used as a reply to the `HXG Request`_ 228 * message that was successfully processed without an error. 229 * 230 * +---+-------+--------------------------------------------------------------+ 231 * | | Bits | Description | 232 * +===+=======+==============================================================+ 233 * | 0 | 31 | ORIGIN | 234 * | +-------+--------------------------------------------------------------+ 235 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_SUCCESS_ | 236 * | +-------+--------------------------------------------------------------+ 237 * | | 27:0 | **DATA0** - data (depends on ACTION from `HXG Request`_) | 238 * +---+-------+--------------------------------------------------------------+ 239 * | 1 | 31:0 | | 240 * +---+-------+ | 241 * |...| | **DATAn** - data (depends on ACTION from `HXG Request`_) | 242 * +---+-------+ | 243 * | n | 31:0 | | 244 * +---+-------+--------------------------------------------------------------+ 245 */ 246 247 #define GUC_HXG_RESPONSE_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN 248 #define GUC_HXG_RESPONSE_MSG_0_DATA0 GUC_HXG_MSG_0_AUX 249 #define GUC_HXG_RESPONSE_MSG_n_DATAn GUC_HXG_MSG_n_PAYLOAD 250 251 #endif 252