drivers/gpu/drm/xe/abi/guc_relay_communication_abi.h

   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