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

   1 /* SPDX-License-Identifier: MIT */
   2 /*
   3  * Copyright © 2014-2021 Intel Corporation
   4  */
   5
   6 #ifndef _ABI_GUC_COMMUNICATION_CTB_ABI_H
   7 #define _ABI_GUC_COMMUNICATION_CTB_ABI_H
   8
   9 #include <linux/types.h>
  10 #include <linux/build_bug.h>
  11
  12 #include "guc_messages_abi.h"
  13
  14 /**
  15  * DOC: CT Buffer
  16  *
  17  * Circular buffer used to send `CTB Message`_
  18  */
  19
  20 /**
  21  * DOC: CTB Descriptor
  22  *
  23  *  +---+-------+--------------------------------------------------------------+
  24  *  |   | Bits  | Description                                                  |
  25  *  +===+=======+==============================================================+
  26  *  | 0 |  31:0 | **HEAD** - offset (in dwords) to the last dword that was     |
  27  *  |   |       | read from the `CT Buffer`_.                                  |
  28  *  |   |       | It can only be updated by the receiver.                      |
  29  *  +---+-------+--------------------------------------------------------------+
  30  *  | 1 |  31:0 | **TAIL** - offset (in dwords) to the last dword that was     |
  31  *  |   |       | written to the `CT Buffer`_.                                 |
  32  *  |   |       | It can only be updated by the sender.                        |
  33  *  +---+-------+--------------------------------------------------------------+
  34  *  | 2 |  31:0 | **STATUS** - status of the CTB                               |
  35  *  |   |       |                                                              |
  36  *  |   |       |   - _`GUC_CTB_STATUS_NO_ERROR` = 0 (normal operation)        |
  37  *  |   |       |   - _`GUC_CTB_STATUS_OVERFLOW` = 1 (head/tail too large)     |
  38  *  |   |       |   - _`GUC_CTB_STATUS_UNDERFLOW` = 2 (truncated message)      |
  39  *  |   |       |   - _`GUC_CTB_STATUS_MISMATCH` = 4 (head/tail modified)      |
  40  *  +---+-------+--------------------------------------------------------------+
  41  *  |...|       | RESERVED = MBZ                                               |
  42  *  +---+-------+--------------------------------------------------------------+
  43  *  | 15|  31:0 | RESERVED = MBZ                                               |
  44  *  +---+-------+--------------------------------------------------------------+
  45  */
  46
  47 struct guc_ct_buffer_desc {
  48         u32 head;
  49         u32 tail;
  50         u32 status;
  51 #define GUC_CTB_STATUS_NO_ERROR                         0
  52 #define GUC_CTB_STATUS_OVERFLOW                         (1 << 0)
  53 #define GUC_CTB_STATUS_UNDERFLOW                        (1 << 1)
  54 #define GUC_CTB_STATUS_MISMATCH                         (1 << 2)
  55         u32 reserved[13];
  56 } __packed;
  57 static_assert(sizeof(struct guc_ct_buffer_desc) == 64);
  58
  59 /**
  60  * DOC: CTB Message
  61  *
  62  *  +---+-------+--------------------------------------------------------------+
  63  *  |   | Bits  | Description                                                  |
  64  *  +===+=======+==============================================================+
  65  *  | 0 | 31:16 | **FENCE** - message identifier                               |
  66  *  |   +-------+--------------------------------------------------------------+
  67  *  |   | 15:12 | **FORMAT** - format of the CTB message                       |
  68  *  |   |       |  - _`GUC_CTB_FORMAT_HXG` = 0 - see `CTB HXG Message`_        |
  69  *  |   +-------+--------------------------------------------------------------+
  70  *  |   |  11:8 | **RESERVED**                                                 |
  71  *  |   +-------+--------------------------------------------------------------+
  72  *  |   |   7:0 | **NUM_DWORDS** - length of the CTB message (w/o header)      |
  73  *  +---+-------+--------------------------------------------------------------+
  74  *  | 1 |  31:0 | optional (depends on FORMAT)                                 |
  75  *  +---+-------+                                                              |
  76  *  |...|       |                                                              |
  77  *  +---+-------+                                                              |
  78  *  | n |  31:0 |                                                              |
  79  *  +---+-------+--------------------------------------------------------------+
  80  */
  81
  82 #define GUC_CTB_HDR_LEN                         1u
  83 #define GUC_CTB_MSG_MIN_LEN                     GUC_CTB_HDR_LEN
  84 #define GUC_CTB_MSG_MAX_LEN                     256u
  85 #define GUC_CTB_MSG_0_FENCE                     (0xffff << 16)
  86 #define GUC_CTB_MSG_0_FORMAT                    (0xf << 12)
  87 #define   GUC_CTB_FORMAT_HXG                    0u
  88 #define GUC_CTB_MSG_0_RESERVED                  (0xf << 8)
  89 #define GUC_CTB_MSG_0_NUM_DWORDS                (0xff << 0)
  90
  91 /**
  92  * DOC: CTB HXG Message
  93  *
  94  *  +---+-------+--------------------------------------------------------------+
  95  *  |   | Bits  | Description                                                  |
  96  *  +===+=======+==============================================================+
  97  *  | 0 | 31:16 | FENCE                                                        |
  98  *  |   +-------+--------------------------------------------------------------+
  99  *  |   | 15:12 | FORMAT = GUC_CTB_FORMAT_HXG_                                 |
 100  *  |   +-------+--------------------------------------------------------------+
 101  *  |   |  11:8 | RESERVED = MBZ                                               |
 102  *  |   +-------+--------------------------------------------------------------+
 103  *  |   |   7:0 | NUM_DWORDS = length (in dwords) of the embedded HXG message  |
 104  *  +---+-------+--------------------------------------------------------------+
 105  *  | 1 |  31:0 |                                                              |
 106  *  +---+-------+                                                              |
 107  *  |...|       | [Embedded `HXG Message`_]                                    |
 108  *  +---+-------+                                                              |
 109  *  | n |  31:0 |                                                              |
 110  *  +---+-------+--------------------------------------------------------------+
 111  */
 112
 113 #define GUC_CTB_HXG_MSG_MIN_LEN         (GUC_CTB_MSG_MIN_LEN + GUC_HXG_MSG_MIN_LEN)
 114 #define GUC_CTB_HXG_MSG_MAX_LEN         GUC_CTB_MSG_MAX_LEN
 115
 116 /**
 117  * DOC: CTB based communication
 118  *
 119  * The CTB (command transport buffer) communication between Host and GuC
 120  * is based on u32 data stream written to the shared buffer. One buffer can
 121  * be used to transmit data only in one direction (one-directional channel).
 122  *
 123  * Current status of the each buffer is maintained in the `CTB Descriptor`_.
 124  * Each message in data stream is encoded as `CTB HXG Message`_.
 125  */
 126
 127 #endif