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 (0x7 << 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 (0xfffffff << 0)
56#define GUC_HXG_MSG_n_PAYLOAD (0xffffffff << 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 (0xfff << 16)
91#define GUC_HXG_REQUEST_MSG_0_ACTION (0xffff << 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 (0xfff << 16)
151#define GUC_HXG_EVENT_MSG_0_ACTION (0xffff << 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 (0xfff << 16)
222#define GUC_HXG_FAILURE_MSG_0_ERROR (0xffff << 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/* deprecated */
252#define INTEL_GUC_MSG_TYPE_SHIFT 28
253#define INTEL_GUC_MSG_TYPE_MASK (0xF << INTEL_GUC_MSG_TYPE_SHIFT)
254#define INTEL_GUC_MSG_DATA_SHIFT 16
255#define INTEL_GUC_MSG_DATA_MASK (0xFFF << INTEL_GUC_MSG_DATA_SHIFT)
256#define INTEL_GUC_MSG_CODE_SHIFT 0
257#define INTEL_GUC_MSG_CODE_MASK (0xFFFF << INTEL_GUC_MSG_CODE_SHIFT)
258
259enum intel_guc_msg_type {
260 INTEL_GUC_MSG_TYPE_REQUEST = 0x0,
261 INTEL_GUC_MSG_TYPE_RESPONSE = 0xF,
262};
263
264#endif /* _ABI_GUC_MESSAGES_ABI_H */
265