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 stored in the buffer descriptor. 124 * Buffer descriptor holds tail and head fields that represents active data 125 * stream. The tail field is updated by the data producer (sender), and head 126 * field is updated by the data consumer (receiver):: 127 * 128 * +------------+ 129 * | DESCRIPTOR | +=================+============+========+ 130 * +============+ | | MESSAGE(s) | | 131 * | address |--------->+=================+============+========+ 132 * +------------+ 133 * | head | ^-----head--------^ 134 * +------------+ 135 * | tail | ^---------tail-----------------^ 136 * +------------+ 137 * | size | ^---------------size--------------------^ 138 * +------------+ 139 * 140 * Each message in data stream starts with the single u32 treated as a header, 141 * followed by optional set of u32 data that makes message specific payload:: 142 * 143 * +------------+---------+---------+---------+ 144 * | MESSAGE | 145 * +------------+---------+---------+---------+ 146 * | msg[0] | [1] | ... | [n-1] | 147 * +------------+---------+---------+---------+ 148 * | MESSAGE | MESSAGE PAYLOAD | 149 * + HEADER +---------+---------+---------+ 150 * | | 0 | ... | n | 151 * +======+=====+=========+=========+=========+ 152 * | 31:16| code| | | | 153 * +------+-----+ | | | 154 * | 15:5|flags| | | | 155 * +------+-----+ | | | 156 * | 4:0| len| | | | 157 * +------+-----+---------+---------+---------+ 158 * 159 * ^-------------len-------------^ 160 * 161 * The message header consists of: 162 * 163 * - **len**, indicates length of the message payload (in u32) 164 * - **code**, indicates message code 165 * - **flags**, holds various bits to control message handling 166 */ 167 168 /* 169 * Definition of the command transport message header (DW0) 170 * 171 * bit[4..0] message len (in dwords) 172 * bit[7..5] reserved 173 * bit[8] response (G2H only) 174 * bit[8] write fence to desc (H2G only) 175 * bit[9] write status to H2G buff (H2G only) 176 * bit[10] send status back via G2H (H2G only) 177 * bit[15..11] reserved 178 * bit[31..16] action code 179 */ 180 #define GUC_CT_MSG_LEN_SHIFT 0 181 #define GUC_CT_MSG_LEN_MASK 0x1F 182 #define GUC_CT_MSG_IS_RESPONSE (1 << 8) 183 #define GUC_CT_MSG_WRITE_FENCE_TO_DESC (1 << 8) 184 #define GUC_CT_MSG_WRITE_STATUS_TO_BUFF (1 << 9) 185 #define GUC_CT_MSG_SEND_STATUS (1 << 10) 186 #define GUC_CT_MSG_ACTION_SHIFT 16 187 #define GUC_CT_MSG_ACTION_MASK 0xFFFF 188 189 #endif /* _ABI_GUC_COMMUNICATION_CTB_ABI_H */ 190