xref: /linux/drivers/gpu/drm/nouveau/include/nvrm/535.113.01/common/shared/msgq/inc/msgq/msgq_priv.h (revision 41c177cf354126a22443b5c80cec9fdd313e67e1)
1 #ifndef __src_common_shared_msgq_inc_msgq_msgq_priv_h__
2 #define __src_common_shared_msgq_inc_msgq_msgq_priv_h__
3 
4 /* Excerpt of RM headers from https://github.com/NVIDIA/open-gpu-kernel-modules/tree/535.113.01 */
5 
6 /*
7  * SPDX-FileCopyrightText: Copyright (c) 2018-2019 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
8  * SPDX-License-Identifier: MIT
9  *
10  * Permission is hereby granted, free of charge, to any person obtaining a
11  * copy of this software and associated documentation files (the "Software"),
12  * to deal in the Software without restriction, including without limitation
13  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
14  * and/or sell copies of the Software, and to permit persons to whom the
15  * Software is furnished to do so, subject to the following conditions:
16  *
17  * The above copyright notice and this permission notice shall be included in
18  * all copies or substantial portions of the Software.
19  *
20  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26  * DEALINGS IN THE SOFTWARE.
27  */
28 
29 /**
30  * msgqTxHeader -- TX queue data structure
31  * @version: the version of this structure, must be 0
32  * @size: the size of the entire queue, including this header
33  * @msgSize: the padded size of queue element, 16 is minimum
34  * @msgCount: the number of elements in this queue
35  * @writePtr: head index of this queue
36  * @flags: 1 = swap the RX pointers
37  * @rxHdrOff: offset of readPtr in this structure
38  * @entryOff: offset of beginning of queue (msgqRxHeader), relative to
39  *          beginning of this structure
40  *
41  * The command queue is a queue of RPCs that are sent from the driver to the
42  * GSP.  The status queue is a queue of messages/responses from GSP-RM to the
43  * driver.  Although the driver allocates memory for both queues, the command
44  * queue is owned by the driver and the status queue is owned by GSP-RM.  In
45  * addition, the headers of the two queues must not share the same 4K page.
46  *
47  * Each queue is prefixed with this data structure.  The idea is that a queue
48  * and its header are written to only by their owner.  That is, only the
49  * driver writes to the command queue and command queue header, and only the
50  * GSP writes to the status (receive) queue and its header.
51  *
52  * This is enforced by the concept of "swapping" the RX pointers.  This is
53  * why the 'flags' field must be set to 1.  'rxHdrOff' is how the GSP knows
54  * where the where the tail pointer of its status queue.
55  *
56  * When the driver writes a new RPC to the command queue, it updates writePtr.
57  * When it reads a new message from the status queue, it updates readPtr.  In
58  * this way, the GSP knows when a new command is in the queue (it polls
59  * writePtr) and it knows how much free space is in the status queue (it
60  * checks readPtr).  The driver never cares about how much free space is in
61  * the status queue.
62  *
63  * As usual, producers write to the head pointer, and consumers read from the
64  * tail pointer.  When head == tail, the queue is empty.
65  *
66  * So to summarize:
67  * command.writePtr = head of command queue
68  * command.readPtr = tail of status queue
69  * status.writePtr = head of status queue
70  * status.readPtr = tail of command queue
71  */
72 typedef struct
73 {
74     NvU32 version;   // queue version
75     NvU32 size;      // bytes, page aligned
76     NvU32 msgSize;   // entry size, bytes, must be power-of-2, 16 is minimum
77     NvU32 msgCount;  // number of entries in queue
78     NvU32 writePtr;  // message id of next slot
79     NvU32 flags;     // if set it means "i want to swap RX"
80     NvU32 rxHdrOff;  // Offset of msgqRxHeader from start of backing store.
81     NvU32 entryOff;  // Offset of entries from start of backing store.
82 } msgqTxHeader;
83 
84 /**
85  * msgqRxHeader - RX queue data structure
86  * @readPtr: tail index of the other queue
87  *
88  * Although this is a separate struct, it could easily be merged into
89  * msgqTxHeader.  msgqTxHeader.rxHdrOff is simply the offset of readPtr
90  * from the beginning of msgqTxHeader.
91  */
92 typedef struct
93 {
94     NvU32 readPtr; // message id of last message read
95 } msgqRxHeader;
96 
97 #endif
98