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  *  |   |       |   - _`GUC_CTB_STATUS_UNUSED` = 8 (CTB is not in use)         |
41  *  +---+-------+--------------------------------------------------------------+
42  *  |...|       | RESERVED = MBZ                                               |
43  *  +---+-------+--------------------------------------------------------------+
44  *  | 15|  31:0 | RESERVED = MBZ                                               |
45  *  +---+-------+--------------------------------------------------------------+
46  */
47 
48 struct guc_ct_buffer_desc {
49 	u32 head;
50 	u32 tail;
51 	u32 status;
52 #define GUC_CTB_STATUS_NO_ERROR				0
53 #define GUC_CTB_STATUS_OVERFLOW				BIT(0)
54 #define GUC_CTB_STATUS_UNDERFLOW			BIT(1)
55 #define GUC_CTB_STATUS_MISMATCH				BIT(2)
56 #define GUC_CTB_STATUS_UNUSED				BIT(3)
57 	u32 reserved[13];
58 } __packed;
59 static_assert(sizeof(struct guc_ct_buffer_desc) == 64);
60 
61 /**
62  * DOC: CTB Message
63  *
64  *  +---+-------+--------------------------------------------------------------+
65  *  |   | Bits  | Description                                                  |
66  *  +===+=======+==============================================================+
67  *  | 0 | 31:16 | **FENCE** - message identifier                               |
68  *  |   +-------+--------------------------------------------------------------+
69  *  |   | 15:12 | **FORMAT** - format of the CTB message                       |
70  *  |   |       |  - _`GUC_CTB_FORMAT_HXG` = 0 - see `CTB HXG Message`_        |
71  *  |   +-------+--------------------------------------------------------------+
72  *  |   |  11:8 | **RESERVED**                                                 |
73  *  |   +-------+--------------------------------------------------------------+
74  *  |   |   7:0 | **NUM_DWORDS** - length of the CTB message (w/o header)      |
75  *  +---+-------+--------------------------------------------------------------+
76  *  | 1 |  31:0 | optional (depends on FORMAT)                                 |
77  *  +---+-------+                                                              |
78  *  |...|       |                                                              |
79  *  +---+-------+                                                              |
80  *  | n |  31:0 |                                                              |
81  *  +---+-------+--------------------------------------------------------------+
82  */
83 
84 #define GUC_CTB_HDR_LEN				1u
85 #define GUC_CTB_MSG_MIN_LEN			GUC_CTB_HDR_LEN
86 #define GUC_CTB_MSG_MAX_LEN			256u
87 #define GUC_CTB_MSG_0_FENCE			(0xffffU << 16)
88 #define GUC_CTB_MSG_0_FORMAT			(0xf << 12)
89 #define   GUC_CTB_FORMAT_HXG			0u
90 #define GUC_CTB_MSG_0_RESERVED			(0xf << 8)
91 #define GUC_CTB_MSG_0_NUM_DWORDS		(0xff << 0)
92 
93 /**
94  * DOC: CTB HXG Message
95  *
96  *  +---+-------+--------------------------------------------------------------+
97  *  |   | Bits  | Description                                                  |
98  *  +===+=======+==============================================================+
99  *  | 0 | 31:16 | FENCE                                                        |
100  *  |   +-------+--------------------------------------------------------------+
101  *  |   | 15:12 | FORMAT = GUC_CTB_FORMAT_HXG_                                 |
102  *  |   +-------+--------------------------------------------------------------+
103  *  |   |  11:8 | RESERVED = MBZ                                               |
104  *  |   +-------+--------------------------------------------------------------+
105  *  |   |   7:0 | NUM_DWORDS = length (in dwords) of the embedded HXG message  |
106  *  +---+-------+--------------------------------------------------------------+
107  *  | 1 |  31:0 |                                                              |
108  *  +---+-------+                                                              |
109  *  |...|       | [Embedded `HXG Message`_]                                    |
110  *  +---+-------+                                                              |
111  *  | n |  31:0 |                                                              |
112  *  +---+-------+--------------------------------------------------------------+
113  */
114 
115 #define GUC_CTB_HXG_MSG_MIN_LEN		(GUC_CTB_MSG_MIN_LEN + GUC_HXG_MSG_MIN_LEN)
116 #define GUC_CTB_HXG_MSG_MAX_LEN		GUC_CTB_MSG_MAX_LEN
117 
118 /**
119  * DOC: CTB based communication
120  *
121  * The CTB (command transport buffer) communication between Host and GuC
122  * is based on u32 data stream written to the shared buffer. One buffer can
123  * be used to transmit data only in one direction (one-directional channel).
124  *
125  * Current status of the each buffer is stored in the buffer descriptor.
126  * Buffer descriptor holds tail and head fields that represents active data
127  * stream. The tail field is updated by the data producer (sender), and head
128  * field is updated by the data consumer (receiver)::
129  *
130  *      +------------+
131  *      | DESCRIPTOR |          +=================+============+========+
132  *      +============+          |                 | MESSAGE(s) |        |
133  *      | address    |--------->+=================+============+========+
134  *      +------------+
135  *      | head       |          ^-----head--------^
136  *      +------------+
137  *      | tail       |          ^---------tail-----------------^
138  *      +------------+
139  *      | size       |          ^---------------size--------------------^
140  *      +------------+
141  *
142  * Each message in data stream starts with the single u32 treated as a header,
143  * followed by optional set of u32 data that makes message specific payload::
144  *
145  *      +------------+---------+---------+---------+
146  *      |         MESSAGE                          |
147  *      +------------+---------+---------+---------+
148  *      |   msg[0]   |   [1]   |   ...   |  [n-1]  |
149  *      +------------+---------+---------+---------+
150  *      |   MESSAGE  |       MESSAGE PAYLOAD       |
151  *      +   HEADER   +---------+---------+---------+
152  *      |            |    0    |   ...   |    n    |
153  *      +======+=====+=========+=========+=========+
154  *      | 31:16| code|         |         |         |
155  *      +------+-----+         |         |         |
156  *      |  15:5|flags|         |         |         |
157  *      +------+-----+         |         |         |
158  *      |   4:0|  len|         |         |         |
159  *      +------+-----+---------+---------+---------+
160  *
161  *                   ^-------------len-------------^
162  *
163  * The message header consists of:
164  *
165  * - **len**, indicates length of the message payload (in u32)
166  * - **code**, indicates message code
167  * - **flags**, holds various bits to control message handling
168  */
169 
170 #endif /* _ABI_GUC_COMMUNICATION_CTB_ABI_H */
171