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 
11 /**
12  * DOC: CTB based communication
13  *
14  * The CTB (command transport buffer) communication between Host and GuC
15  * is based on u32 data stream written to the shared buffer. One buffer can
16  * be used to transmit data only in one direction (one-directional channel).
17  *
18  * Current status of the each buffer is stored in the buffer descriptor.
19  * Buffer descriptor holds tail and head fields that represents active data
20  * stream. The tail field is updated by the data producer (sender), and head
21  * field is updated by the data consumer (receiver)::
22  *
23  *      +------------+
24  *      | DESCRIPTOR |          +=================+============+========+
25  *      +============+          |                 | MESSAGE(s) |        |
26  *      | address    |--------->+=================+============+========+
27  *      +------------+
28  *      | head       |          ^-----head--------^
29  *      +------------+
30  *      | tail       |          ^---------tail-----------------^
31  *      +------------+
32  *      | size       |          ^---------------size--------------------^
33  *      +------------+
34  *
35  * Each message in data stream starts with the single u32 treated as a header,
36  * followed by optional set of u32 data that makes message specific payload::
37  *
38  *      +------------+---------+---------+---------+
39  *      |         MESSAGE                          |
40  *      +------------+---------+---------+---------+
41  *      |   msg[0]   |   [1]   |   ...   |  [n-1]  |
42  *      +------------+---------+---------+---------+
43  *      |   MESSAGE  |       MESSAGE PAYLOAD       |
44  *      +   HEADER   +---------+---------+---------+
45  *      |            |    0    |   ...   |    n    |
46  *      +======+=====+=========+=========+=========+
47  *      | 31:16| code|         |         |         |
48  *      +------+-----+         |         |         |
49  *      |  15:5|flags|         |         |         |
50  *      +------+-----+         |         |         |
51  *      |   4:0|  len|         |         |         |
52  *      +------+-----+---------+---------+---------+
53  *
54  *                   ^-------------len-------------^
55  *
56  * The message header consists of:
57  *
58  * - **len**, indicates length of the message payload (in u32)
59  * - **code**, indicates message code
60  * - **flags**, holds various bits to control message handling
61  */
62 
63 /*
64  * Describes single command transport buffer.
65  * Used by both guc-master and clients.
66  */
67 struct guc_ct_buffer_desc {
68 	u32 addr;		/* gfx address */
69 	u64 host_private;	/* host private data */
70 	u32 size;		/* size in bytes */
71 	u32 head;		/* offset updated by GuC*/
72 	u32 tail;		/* offset updated by owner */
73 	u32 is_in_error;	/* error indicator */
74 	u32 reserved1;
75 	u32 reserved2;
76 	u32 owner;		/* id of the channel owner */
77 	u32 owner_sub_id;	/* owner-defined field for extra tracking */
78 	u32 reserved[5];
79 } __packed;
80 
81 /* Type of command transport buffer */
82 #define INTEL_GUC_CT_BUFFER_TYPE_SEND	0x0u
83 #define INTEL_GUC_CT_BUFFER_TYPE_RECV	0x1u
84 
85 /*
86  * Definition of the command transport message header (DW0)
87  *
88  * bit[4..0]	message len (in dwords)
89  * bit[7..5]	reserved
90  * bit[8]	response (G2H only)
91  * bit[8]	write fence to desc (H2G only)
92  * bit[9]	write status to H2G buff (H2G only)
93  * bit[10]	send status back via G2H (H2G only)
94  * bit[15..11]	reserved
95  * bit[31..16]	action code
96  */
97 #define GUC_CT_MSG_LEN_SHIFT			0
98 #define GUC_CT_MSG_LEN_MASK			0x1F
99 #define GUC_CT_MSG_IS_RESPONSE			(1 << 8)
100 #define GUC_CT_MSG_WRITE_FENCE_TO_DESC		(1 << 8)
101 #define GUC_CT_MSG_WRITE_STATUS_TO_BUFF		(1 << 9)
102 #define GUC_CT_MSG_SEND_STATUS			(1 << 10)
103 #define GUC_CT_MSG_ACTION_SHIFT			16
104 #define GUC_CT_MSG_ACTION_MASK			0xFFFF
105 
106 #endif /* _ABI_GUC_COMMUNICATION_CTB_ABI_H */
107