xref: /linux/drivers/gpu/drm/xe/abi/guc_relay_communication_abi.h (revision b7e1e969c887c897947fdc3754fe9b0c24acb155)
1 /* SPDX-License-Identifier: MIT */
2 /*
3  * Copyright © 2023 Intel Corporation
4  */
5 
6 #ifndef _ABI_GUC_RELAY_COMMUNICATION_ABI_H
7 #define _ABI_GUC_RELAY_COMMUNICATION_ABI_H
8 
9 #include <linux/build_bug.h>
10 
11 #include "guc_actions_sriov_abi.h"
12 #include "guc_communication_ctb_abi.h"
13 #include "guc_messages_abi.h"
14 
15 /**
16  * DOC: GuC Relay Communication
17  *
18  * The communication between Virtual Function (VF) drivers and Physical Function
19  * (PF) drivers is based on the GuC firmware acting as a proxy (relay) agent.
20  *
21  * To communicate with the PF driver, VF's drivers use `VF2GUC_RELAY_TO_PF`_
22  * action that takes the `Relay Message`_ as opaque payload and requires the
23  * relay message identifier (RID) as additional parameter.
24  *
25  * This identifier is used by the drivers to match related messages.
26  *
27  * The GuC forwards this `Relay Message`_ and its identifier to the PF driver
28  * in `GUC2PF_RELAY_FROM_VF`_ action. This event message additionally contains
29  * the identifier of the origin VF (VFID).
30  *
31  * Likewise, to communicate with the VF drivers, PF driver use
32  * `VF2GUC_RELAY_TO_PF`_ action that in addition to the `Relay Message`_
33  * and the relay message identifier (RID) also takes the target VF identifier.
34  *
35  * The GuC uses this target VFID from the message to select where to send the
36  * `GUC2VF_RELAY_FROM_PF`_ with the embedded `Relay Message`_ with response::
37  *
38  *      VF                             GuC                              PF
39  *      |                               |                               |
40  *     [ ] VF2GUC_RELAY_TO_PF           |                               |
41  *     [ ]---------------------------> [ ]                              |
42  *     [ ] { rid, msg }                [ ]                              |
43  *     [ ]                             [ ] GUC2PF_RELAY_FROM_VF         |
44  *     [ ]                             [ ]---------------------------> [ ]
45  *     [ ]                              |  { VFID, rid, msg }          [ ]
46  *     [ ]                              |                              [ ]
47  *     [ ]                              |           PF2GUC_RELAY_TO_VF [ ]
48  *     [ ]                             [ ] <---------------------------[ ]
49  *     [ ]                             [ ]        { VFID, rid, reply }  |
50  *     [ ]        GUC2VF_RELAY_FROM_PF [ ]                              |
51  *     [ ] <---------------------------[ ]                              |
52  *      |               { rid, reply }  |                               |
53  *      |                               |                               |
54  *
55  * It is also possible that PF driver will initiate communication with the
56  * selected VF driver. The same GuC action messages will be used::
57  *
58  *      VF                             GuC                              PF
59  *      |                               |                               |
60  *      |                               |           PF2GUC_RELAY_TO_VF [ ]
61  *      |                              [ ] <---------------------------[ ]
62  *      |                              [ ]          { VFID, rid, msg } [ ]
63  *      |         GUC2VF_RELAY_FROM_PF [ ]                             [ ]
64  *     [ ] <---------------------------[ ]                             [ ]
65  *     [ ]                { rid, msg }  |                              [ ]
66  *     [ ]                              |                              [ ]
67  *     [ ] VF2GUC_RELAY_TO_PF           |                              [ ]
68  *     [ ]---------------------------> [ ]                             [ ]
69  *      |  { rid, reply }              [ ]                             [ ]
70  *      |                              [ ] GUC2PF_RELAY_FROM_VF        [ ]
71  *      |                              [ ]---------------------------> [ ]
72  *      |                               | { VFID, rid, reply }          |
73  *      |                               |                               |
74  */
75 
76 /**
77  * DOC: Relay Message
78  *
79  * The `Relay Message`_ is used by Physical Function (PF) driver and Virtual
80  * Function (VF) drivers to communicate using `GuC Relay Communication`_.
81  *
82  * Format of the `Relay Message`_ follows format of the generic `HXG Message`_.
83  *
84  *  +--------------------------------------------------------------------------+
85  *  |  `Relay Message`_                                                        |
86  *  +==========================================================================+
87  *  |  `HXG Message`_                                                          |
88  *  +--------------------------------------------------------------------------+
89  *
90  * Maximum length of the `Relay Message`_ is limited by the maximum length of
91  * the `CTB HXG Message`_ and format of the `GUC2PF_RELAY_FROM_VF`_ message.
92  */
93 
94 #define GUC_RELAY_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN
95 #define GUC_RELAY_MSG_MAX_LEN \
96 	(GUC_CTB_MAX_DWORDS - GUC2PF_RELAY_FROM_VF_EVENT_MSG_MIN_LEN)
97 
98 static_assert(PF2GUC_RELAY_TO_VF_REQUEST_MSG_MIN_LEN >
99 	      VF2GUC_RELAY_TO_PF_REQUEST_MSG_MIN_LEN);
100 
101 /**
102  * DOC: Relay Error Codes
103  *
104  * The `GuC Relay Communication`_ can be used to pass `Relay Message`_ between
105  * drivers that run on different Operating Systems. To help in troubleshooting,
106  * `GuC Relay Communication`_ uses error codes that mostly match errno values.
107  */
108 
109 #define GUC_RELAY_ERROR_UNDISCLOSED			0
110 #define GUC_RELAY_ERROR_OPERATION_NOT_PERMITTED		1	/* EPERM */
111 #define GUC_RELAY_ERROR_PERMISSION_DENIED		13	/* EACCES */
112 #define GUC_RELAY_ERROR_INVALID_ARGUMENT		22	/* EINVAL */
113 #define GUC_RELAY_ERROR_INVALID_REQUEST_CODE		56	/* EBADRQC */
114 #define GUC_RELAY_ERROR_NO_DATA_AVAILABLE		61	/* ENODATA */
115 #define GUC_RELAY_ERROR_PROTOCOL_ERROR			71	/* EPROTO */
116 #define GUC_RELAY_ERROR_MESSAGE_SIZE			90	/* EMSGSIZE */
117 
118 #endif
119