guc_communication_ctb_abi.h

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