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