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
 98static_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