[linux-block.git] / drivers / gpu / drm / xe / abi / guc_relay_communication_abi.h

/* SPDX-License-Identifier: MIT */
/*
 * Copyright © 2023 Intel Corporation
 */

#ifndef _ABI_GUC_RELAY_COMMUNICATION_ABI_H
#define _ABI_GUC_RELAY_COMMUNICATION_ABI_H

#include <linux/build_bug.h>

#include "guc_actions_sriov_abi.h"
#include "guc_communication_ctb_abi.h"
#include "guc_messages_abi.h"

/**
 * DOC: GuC Relay Communication
 *
 * The communication between Virtual Function (VF) drivers and Physical Function
 * (PF) drivers is based on the GuC firmware acting as a proxy (relay) agent.
 *
 * To communicate with the PF driver, VF's drivers use `VF2GUC_RELAY_TO_PF`_
 * action that takes the `Relay Message`_ as opaque payload and requires the
 * relay message identifier (RID) as additional parameter.
 *
 * This identifier is used by the drivers to match related messages.
 *
 * The GuC forwards this `Relay Message`_ and its identifier to the PF driver
 * in `GUC2PF_RELAY_FROM_VF`_ action. This event message additionally contains
 * the identifier of the origin VF (VFID).
 *
 * Likewise, to communicate with the VF drivers, PF driver use
 * `VF2GUC_RELAY_TO_PF`_ action that in addition to the `Relay Message`_
 * and the relay message identifier (RID) also takes the target VF identifier.
 *
 * The GuC uses this target VFID from the message to select where to send the
 * `GUC2VF_RELAY_FROM_PF`_ with the embedded `Relay Message`_ with response::
 *
 *      VF                             GuC                              PF
 *      |                               |                               |
 *     [ ] VF2GUC_RELAY_TO_PF           |                               |
 *     [ ]---------------------------> [ ]                              |
 *     [ ] { rid, msg }                [ ]                              |
 *     [ ]                             [ ] GUC2PF_RELAY_FROM_VF         |
 *     [ ]                             [ ]---------------------------> [ ]
 *     [ ]                              |  { VFID, rid, msg }          [ ]
 *     [ ]                              |                              [ ]
 *     [ ]                              |           PF2GUC_RELAY_TO_VF [ ]
 *     [ ]                             [ ] <---------------------------[ ]
 *     [ ]                             [ ]        { VFID, rid, reply }  |
 *     [ ]        GUC2VF_RELAY_FROM_PF [ ]                              |
 *     [ ] <---------------------------[ ]                              |
 *      |               { rid, reply }  |                               |
 *      |                               |                               |
 *
 * It is also possible that PF driver will initiate communication with the
 * selected VF driver. The same GuC action messages will be used::
 *
 *      VF                             GuC                              PF
 *      |                               |                               |
 *      |                               |           PF2GUC_RELAY_TO_VF [ ]
 *      |                              [ ] <---------------------------[ ]
 *      |                              [ ]          { VFID, rid, msg } [ ]
 *      |         GUC2VF_RELAY_FROM_PF [ ]                             [ ]
 *     [ ] <---------------------------[ ]                             [ ]
 *     [ ]                { rid, msg }  |                              [ ]
 *     [ ]                              |                              [ ]
 *     [ ] VF2GUC_RELAY_TO_PF           |                              [ ]
 *     [ ]---------------------------> [ ]                             [ ]
 *      |  { rid, reply }              [ ]                             [ ]
 *      |                              [ ] GUC2PF_RELAY_FROM_VF        [ ]
 *      |                              [ ]---------------------------> [ ]
 *      |                               | { VFID, rid, reply }          |
 *      |                               |                               |
 */

/**
 * DOC: Relay Message
 *
 * The `Relay Message`_ is used by Physical Function (PF) driver and Virtual
 * Function (VF) drivers to communicate using `GuC Relay Communication`_.
 *
 * Format of the `Relay Message`_ follows format of the generic `HXG Message`_.
 *
 *  +--------------------------------------------------------------------------+
 *  |  `Relay Message`_                                                        |
 *  +==========================================================================+
 *  |  `HXG Message`_                                                          |
 *  +--------------------------------------------------------------------------+
 *
 * Maximum length of the `Relay Message`_ is limited by the maximum length of
 * the `CTB HXG Message`_ and format of the `GUC2PF_RELAY_FROM_VF`_ message.
 */

#define GUC_RELAY_MSG_MIN_LEN GUC_HXG_MSG_MIN_LEN
#define GUC_RELAY_MSG_MAX_LEN \
	(GUC_CTB_MAX_DWORDS - GUC2PF_RELAY_FROM_VF_EVENT_MSG_MIN_LEN)

static_assert(PF2GUC_RELAY_TO_VF_REQUEST_MSG_MIN_LEN >
	      VF2GUC_RELAY_TO_PF_REQUEST_MSG_MIN_LEN);

/**
 * DOC: Relay Error Codes
 *
 * The `GuC Relay Communication`_ can be used to pass `Relay Message`_ between
 * drivers that run on different Operating Systems. To help in troubleshooting,
 * `GuC Relay Communication`_ uses error codes that mostly match errno values.
 */

#define GUC_RELAY_ERROR_UNDISCLOSED			0
#define GUC_RELAY_ERROR_OPERATION_NOT_PERMITTED		1	/* EPERM */
#define GUC_RELAY_ERROR_PERMISSION_DENIED		13	/* EACCES */
#define GUC_RELAY_ERROR_INVALID_ARGUMENT		22	/* EINVAL */
#define GUC_RELAY_ERROR_INVALID_REQUEST_CODE		56	/* EBADRQC */
#define GUC_RELAY_ERROR_NO_DATA_AVAILABLE		61	/* ENODATA */
#define GUC_RELAY_ERROR_PROTOCOL_ERROR			71	/* EPROTO */
#define GUC_RELAY_ERROR_MESSAGE_SIZE			90	/* EMSGSIZE */

#endif
Commit	Line	Data
fa6c12e0 MW	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