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