Loading...
1/* SPDX-License-Identifier: MIT */
2/*
3 * Copyright © 2023-2024 Intel Corporation
4 */
5
6#ifndef _ABI_GUC_RELAY_ACTIONS_ABI_H_
7#define _ABI_GUC_RELAY_ACTIONS_ABI_H_
8
9#include "abi/guc_relay_communication_abi.h"
10
11/**
12 * DOC: GuC Relay VF/PF ABI Version
13 *
14 * The _`GUC_RELAY_VERSION_BASE` defines minimum VF/PF ABI version that
15 * drivers must support. Currently this is version 1.0.
16 *
17 * The _`GUC_RELAY_VERSION_LATEST` defines latest VF/PF ABI version that
18 * drivers may use. Currently this is version 1.0.
19 *
20 * Some platforms may require different base VF/PF ABI version.
21 * No supported VF/PF ABI version can be 0.0.
22 */
23
24#define GUC_RELAY_VERSION_BASE_MAJOR 1
25#define GUC_RELAY_VERSION_BASE_MINOR 0
26
27#define GUC_RELAY_VERSION_LATEST_MAJOR 1
28#define GUC_RELAY_VERSION_LATEST_MINOR 0
29
30/**
31 * DOC: GuC Relay Actions
32 *
33 * The following actions are supported from VF/PF ABI version 1.0:
34 *
35 * * `VF2PF_HANDSHAKE`_
36 * * `VF2PF_QUERY_RUNTIME`_
37 */
38
39/**
40 * DOC: VF2PF_HANDSHAKE
41 *
42 * This `Relay Message`_ is used by the VF to establish ABI version with the PF.
43 *
44 * Prior to exchanging any other messages, both VF driver and PF driver must
45 * negotiate the VF/PF ABI version that will be used in their communication.
46 *
47 * The VF driver shall use @MAJOR and @MINOR fields to pass requested ABI version.
48 * The VF driver may use special version 0.0 (both @MAJOR and @MINOR set to 0)
49 * to request latest (or any) ABI version that is supported by the PF driver.
50 *
51 * This message definition shall be supported by all future ABI versions.
52 * This message definition shall not be changed by future ABI versions.
53 *
54 * +---+-------+--------------------------------------------------------------+
55 * | | Bits | Description |
56 * +===+=======+==============================================================+
57 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
58 * | +-------+--------------------------------------------------------------+
59 * | | 30:28 | TYPE = GUC_HXG_TYPE_REQUEST_ |
60 * | +-------+--------------------------------------------------------------+
61 * | | 27:16 | DATA0 = MBZ |
62 * | +-------+--------------------------------------------------------------+
63 * | | 15:0 | ACTION = _`GUC_RELAY_ACTION_VF2PF_HANDSHAKE` = 0x0001 |
64 * +---+-------+--------------------------------------------------------------+
65 * | 1 | 31:16 | **MAJOR** - requested major version of the VFPF interface |
66 * | | | (use MAJOR_ANY to request latest version supported by PF) |
67 * | +-------+--------------------------------------------------------------+
68 * | | 15:0 | **MINOR** - requested minor version of the VFPF interface |
69 * | | | (use MINOR_ANY to request latest version supported by PF) |
70 * +---+-------+--------------------------------------------------------------+
71 *
72 * +---+-------+--------------------------------------------------------------+
73 * | | Bits | Description |
74 * +===+=======+==============================================================+
75 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
76 * | +-------+--------------------------------------------------------------+
77 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_SUCCESS_ |
78 * | +-------+--------------------------------------------------------------+
79 * | | 27:0 | DATA0 = MBZ |
80 * +---+-------+--------------------------------------------------------------+
81 * | 1 | 31:16 | **MAJOR** - agreed major version of the VFPF interface |
82 * | +-------+--------------------------------------------------------------+
83 * | | 15:0 | **MINOR** - agreed minor version of the VFPF interface |
84 * +---+-------+--------------------------------------------------------------+
85 */
86#define GUC_RELAY_ACTION_VF2PF_HANDSHAKE 0x0001u
87
88#define VF2PF_HANDSHAKE_REQUEST_MSG_LEN 2u
89#define VF2PF_HANDSHAKE_REQUEST_MSG_0_MBZ GUC_HXG_REQUEST_MSG_0_DATA0
90#define VF2PF_HANDSHAKE_REQUEST_MSG_1_MAJOR (0xffffu << 16)
91#define VF2PF_HANDSHAKE_MAJOR_ANY 0
92#define VF2PF_HANDSHAKE_REQUEST_MSG_1_MINOR (0xffffu << 0)
93#define VF2PF_HANDSHAKE_MINOR_ANY 0
94
95#define VF2PF_HANDSHAKE_RESPONSE_MSG_LEN 2u
96#define VF2PF_HANDSHAKE_RESPONSE_MSG_0_MBZ GUC_HXG_RESPONSE_MSG_0_DATA0
97#define VF2PF_HANDSHAKE_RESPONSE_MSG_1_MAJOR (0xffffu << 16)
98#define VF2PF_HANDSHAKE_RESPONSE_MSG_1_MINOR (0xffffu << 0)
99
100/**
101 * DOC: VF2PF_QUERY_RUNTIME
102 *
103 * This `Relay Message`_ is used by the VF to query values of runtime registers.
104 *
105 * On some platforms, VF drivers may not have access to the some fuse registers
106 * (referred here as 'runtime registers') and therefore VF drivers need to ask
107 * the PF driver to obtain their values.
108 *
109 * However, the list of such registers, and their values, is fully owned and
110 * maintained by the PF driver and the VF driver may only initiate the query
111 * sequence and indicate in the @START field the starting index of the next
112 * requested register from this predefined list.
113 *
114 * In the response, the PF driver will return tuple of 32-bit register offset and
115 * the 32-bit value of that register (respectively @REG_OFFSET and @REG_VALUE).
116 *
117 * The VF driver can use @LIMIT field to limit number of returned register tuples.
118 * If @LIMIT is unset then PF decides about number of returned register tuples.
119 *
120 * This message definition is supported from ABI version 1.0.
121 *
122 * +---+-------+--------------------------------------------------------------+
123 * | | Bits | Description |
124 * +===+=======+==============================================================+
125 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
126 * | +-------+--------------------------------------------------------------+
127 * | | 30:28 | TYPE = GUC_HXG_TYPE_REQUEST_ |
128 * | +-------+--------------------------------------------------------------+
129 * | | 27:16 | DATA0 = **LIMIT** - limit number of returned entries |
130 * | | | (use zero to not enforce any limits on the response) |
131 * | +-------+--------------------------------------------------------------+
132 * | | 15:0 | ACTION = _`GUC_RELAY_ACTION_VF2PF_QUERY_RUNTIME` = 0x0101 |
133 * +---+-------+--------------------------------------------------------------+
134 * | 1 | 31:0 | DATA1 = **START** - index of the first requested entry |
135 * +---+-------+--------------------------------------------------------------+
136 *
137 * +---+-------+--------------------------------------------------------------+
138 * | | Bits | Description |
139 * +===+=======+==============================================================+
140 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
141 * | +-------+--------------------------------------------------------------+
142 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_SUCCESS_ |
143 * | +-------+--------------------------------------------------------------+
144 * | | 27:0 | DATA0 = **COUNT** - number of entries included in response |
145 * +---+-------+--------------------------------------------------------------+
146 * | 1 | 31:0 | DATA1 = **REMAINING** - number of remaining entries |
147 * +---+-------+--------------------------------------------------------------+
148 * | 2 | 31:0 | DATA2 = **REG_OFFSET** - offset of register[START] |
149 * +---+-------+--------------------------------------------------------------+
150 * | 3 | 31:0 | DATA3 = **REG_VALUE** - value of register[START] |
151 * +---+-------+--------------------------------------------------------------+
152 * | | | |
153 * +---+-------+--------------------------------------------------------------+
154 * |n-1| 31:0 | REG_OFFSET - offset of register[START + x] |
155 * +---+-------+--------------------------------------------------------------+
156 * | n | 31:0 | REG_VALUE - value of register[START + x] |
157 * +---+-------+--------------------------------------------------------------+
158 */
159#define GUC_RELAY_ACTION_VF2PF_QUERY_RUNTIME 0x0101u
160
161#define VF2PF_QUERY_RUNTIME_REQUEST_MSG_LEN 2u
162#define VF2PF_QUERY_RUNTIME_REQUEST_MSG_0_LIMIT GUC_HXG_REQUEST_MSG_0_DATA0
163#define VF2PF_QUERY_RUNTIME_NO_LIMIT 0u
164#define VF2PF_QUERY_RUNTIME_REQUEST_MSG_1_START GUC_HXG_REQUEST_MSG_n_DATAn
165
166#define VF2PF_QUERY_RUNTIME_RESPONSE_MSG_MIN_LEN (GUC_HXG_MSG_MIN_LEN + 1u)
167#define VF2PF_QUERY_RUNTIME_RESPONSE_MSG_MAX_LEN \
168 (VF2PF_QUERY_RUNTIME_RESPONSE_MSG_MIN_LEN + VF2PF_QUERY_RUNTIME_MAX_COUNT * 2)
169#define VF2PF_QUERY_RUNTIME_RESPONSE_MSG_0_COUNT GUC_HXG_RESPONSE_MSG_0_DATA0
170#define VF2PF_QUERY_RUNTIME_MIN_COUNT 0
171#define VF2PF_QUERY_RUNTIME_MAX_COUNT \
172 ((GUC_RELAY_MSG_MAX_LEN - VF2PF_QUERY_RUNTIME_RESPONSE_MSG_MIN_LEN) / 2)
173#define VF2PF_QUERY_RUNTIME_RESPONSE_MSG_1_REMAINING GUC_HXG_RESPONSE_MSG_n_DATAn
174#define VF2PF_QUERY_RUNTIME_RESPONSE_DATAn_REG_OFFSETx GUC_HXG_RESPONSE_MSG_n_DATAn
175#define VF2PF_QUERY_RUNTIME_RESPONSE_DATAn_REG_VALUEx GUC_HXG_RESPONSE_MSG_n_DATAn
176
177/**
178 * DOC: GuC Relay Debug Actions
179 *
180 * This range of action codes is reserved for debugging purposes only and should
181 * be used only on debug builds. These actions may not be supported by the
182 * production drivers. Their definitions could be changed in the future.
183 *
184 * _`GUC_RELAY_ACTION_DEBUG_ONLY_START` = 0xDEB0
185 * _`GUC_RELAY_ACTION_DEBUG_ONLY_END` = 0xDEFF
186 */
187
188#define GUC_RELAY_ACTION_DEBUG_ONLY_START 0xDEB0
189#define GUC_RELAY_ACTION_DEBUG_ONLY_END 0xDEFF
190
191/**
192 * DOC: VFXPF_TESTLOOP
193 *
194 * This `Relay Message`_ is used to selftest the `GuC Relay Communication`_.
195 *
196 * The following opcodes are defined:
197 * VFXPF_TESTLOOP_OPCODE_NOP_ will return no data.
198 * VFXPF_TESTLOOP_OPCODE_BUSY_ will reply with BUSY response first.
199 * VFXPF_TESTLOOP_OPCODE_RETRY_ will reply with RETRY response instead.
200 * VFXPF_TESTLOOP_OPCODE_ECHO_ will return same data as received.
201 * VFXPF_TESTLOOP_OPCODE_FAIL_ will always fail with error.
202 *
203 * +---+-------+--------------------------------------------------------------+
204 * | | Bits | Description |
205 * +===+=======+==============================================================+
206 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
207 * | +-------+--------------------------------------------------------------+
208 * | | 30:28 | TYPE = GUC_HXG_TYPE_REQUEST_ or GUC_HXG_TYPE_FAST_REQUEST_ |
209 * | | | or GUC_HXG_TYPE_EVENT_ |
210 * | +-------+--------------------------------------------------------------+
211 * | | 27:16 | **OPCODE** |
212 * | | | - _`VFXPF_TESTLOOP_OPCODE_NOP` = 0x0 |
213 * | | | - _`VFXPF_TESTLOOP_OPCODE_BUSY` = 0xB |
214 * | | | - _`VFXPF_TESTLOOP_OPCODE_RETRY` = 0xD |
215 * | | | - _`VFXPF_TESTLOOP_OPCODE_ECHO` = 0xE |
216 * | | | - _`VFXPF_TESTLOOP_OPCODE_FAIL` = 0xF |
217 * | +-------+--------------------------------------------------------------+
218 * | | 15:0 | ACTION = _`IOV_ACTION_SELFTEST_RELAY` |
219 * +---+-------+--------------------------------------------------------------+
220 * | 1 | 31:0 | **DATA1** = optional, depends on **OPCODE**: |
221 * | | | for VFXPF_TESTLOOP_OPCODE_BUSY_: time in ms for reply |
222 * | | | for VFXPF_TESTLOOP_OPCODE_FAIL_: expected error |
223 * | | | for VFXPF_TESTLOOP_OPCODE_ECHO_: payload |
224 * +---+-------+--------------------------------------------------------------+
225 * |...| 31:0 | **DATAn** = only for **OPCODE** VFXPF_TESTLOOP_OPCODE_ECHO_ |
226 * +---+-------+--------------------------------------------------------------+
227 *
228 * +---+-------+--------------------------------------------------------------+
229 * | | Bits | Description |
230 * +===+=======+==============================================================+
231 * | 0 | 31 | ORIGIN = GUC_HXG_ORIGIN_HOST_ |
232 * | +-------+--------------------------------------------------------------+
233 * | | 30:28 | TYPE = GUC_HXG_TYPE_RESPONSE_SUCCESS_ |
234 * | +-------+--------------------------------------------------------------+
235 * | | 27:0 | DATA0 = MBZ |
236 * +---+-------+--------------------------------------------------------------+
237 * |...| 31:0 | DATAn = only for **OPCODE** VFXPF_TESTLOOP_OPCODE_ECHO_ |
238 * +---+-------+--------------------------------------------------------------+
239 */
240#define GUC_RELAY_ACTION_VFXPF_TESTLOOP (GUC_RELAY_ACTION_DEBUG_ONLY_START + 1)
241#define VFXPF_TESTLOOP_OPCODE_NOP 0x0
242#define VFXPF_TESTLOOP_OPCODE_BUSY 0xB
243#define VFXPF_TESTLOOP_OPCODE_RETRY 0xD
244#define VFXPF_TESTLOOP_OPCODE_ECHO 0xE
245#define VFXPF_TESTLOOP_OPCODE_FAIL 0xF
246
247#endif