#ifndef __src_common_shared_msgq_inc_msgq_msgq_priv_h__
#define __src_common_shared_msgq_inc_msgq_msgq_priv_h__

/* Excerpt of RM headers from https://github.com/NVIDIA/open-gpu-kernel-modules/tree/535.113.01 */

/*
 * SPDX-FileCopyrightText: Copyright (c) 2018-2019 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: MIT
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/**
 * msgqTxHeader -- TX queue data structure
 * @version: the version of this structure, must be 0
 * @size: the size of the entire queue, including this header
 * @msgSize: the padded size of queue element, 16 is minimum
 * @msgCount: the number of elements in this queue
 * @writePtr: head index of this queue
 * @flags: 1 = swap the RX pointers
 * @rxHdrOff: offset of readPtr in this structure
 * @entryOff: offset of beginning of queue (msgqRxHeader), relative to
 *          beginning of this structure
 *
 * The command queue is a queue of RPCs that are sent from the driver to the
 * GSP.  The status queue is a queue of messages/responses from GSP-RM to the
 * driver.  Although the driver allocates memory for both queues, the command
 * queue is owned by the driver and the status queue is owned by GSP-RM.  In
 * addition, the headers of the two queues must not share the same 4K page.
 *
 * Each queue is prefixed with this data structure.  The idea is that a queue
 * and its header are written to only by their owner.  That is, only the
 * driver writes to the command queue and command queue header, and only the
 * GSP writes to the status (receive) queue and its header.
 *
 * This is enforced by the concept of "swapping" the RX pointers.  This is
 * why the 'flags' field must be set to 1.  'rxHdrOff' is how the GSP knows
 * where the where the tail pointer of its status queue.
 *
 * When the driver writes a new RPC to the command queue, it updates writePtr.
 * When it reads a new message from the status queue, it updates readPtr.  In
 * this way, the GSP knows when a new command is in the queue (it polls
 * writePtr) and it knows how much free space is in the status queue (it
 * checks readPtr).  The driver never cares about how much free space is in
 * the status queue.
 *
 * As usual, producers write to the head pointer, and consumers read from the
 * tail pointer.  When head == tail, the queue is empty.
 *
 * So to summarize:
 * command.writePtr = head of command queue
 * command.readPtr = tail of status queue
 * status.writePtr = head of status queue
 * status.readPtr = tail of command queue
 */
typedef struct
{
    NvU32 version;   // queue version
    NvU32 size;      // bytes, page aligned
    NvU32 msgSize;   // entry size, bytes, must be power-of-2, 16 is minimum
    NvU32 msgCount;  // number of entries in queue
    NvU32 writePtr;  // message id of next slot
    NvU32 flags;     // if set it means "i want to swap RX"
    NvU32 rxHdrOff;  // Offset of msgqRxHeader from start of backing store.
    NvU32 entryOff;  // Offset of entries from start of backing store.
} msgqTxHeader;

/**
 * msgqRxHeader - RX queue data structure
 * @readPtr: tail index of the other queue
 *
 * Although this is a separate struct, it could easily be merged into
 * msgqTxHeader.  msgqTxHeader.rxHdrOff is simply the offset of readPtr
 * from the beginning of msgqTxHeader.
 */
typedef struct
{
    NvU32 readPtr; // message id of last message read
} msgqRxHeader;

#endif