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