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			(0x1 << 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 
229 enum 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