1 /* SPDX-License-Identifier: MIT */
3 * Copyright © 2014-2021 Intel Corporation
6 #ifndef _ABI_GUC_COMMUNICATION_CTB_ABI_H
7 #define _ABI_GUC_COMMUNICATION_CTB_ABI_H
9 #include <linux/types.h>
10 #include <linux/build_bug.h>
12 #include "guc_messages_abi.h"
17 * Circular buffer used to send `CTB Message`_
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 |
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 * +---+-------+--------------------------------------------------------------+
47 struct guc_ct_buffer_desc {
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)
57 static_assert(sizeof(struct guc_ct_buffer_desc) == 64);
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) |
79 * +---+-------+--------------------------------------------------------------+
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)
92 * DOC: CTB HXG Message
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 * +---+-------+--------------------------------------------------------------+
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
117 * DOC: CTB based communication
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).
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)::
129 * | DESCRIPTOR | +=================+============+========+
130 * +============+ | | MESSAGE(s) | |
131 * | address |--------->+=================+============+========+
133 * | head | ^-----head--------^
135 * | tail | ^---------tail-----------------^
137 * | size | ^---------------size--------------------^
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::
143 * +------------+---------+---------+---------+
145 * +------------+---------+---------+---------+
146 * | msg[0] | [1] | ... | [n-1] |
147 * +------------+---------+---------+---------+
148 * | MESSAGE | MESSAGE PAYLOAD |
149 * + HEADER +---------+---------+---------+
151 * +======+=====+=========+=========+=========+
152 * | 31:16| code| | | |
153 * +------+-----+ | | |
154 * | 15:5|flags| | | |
155 * +------+-----+ | | |
157 * +------+-----+---------+---------+---------+
159 * ^-------------len-------------^
161 * The message header consists of:
163 * - **len**, indicates length of the message payload (in u32)
164 * - **code**, indicates message code
165 * - **flags**, holds various bits to control message handling
169 * Definition of the command transport message header (DW0)
171 * bit[4..0] message len (in dwords)
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
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
189 #endif /* _ABI_GUC_COMMUNICATION_CTB_ABI_H */