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
48struct 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;
59static_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