/*************************************************************************/ /*!
@File
@Title          Transport Layer internals
@Copyright      Copyright (c) Imagination Technologies Ltd. All Rights Reserved
@Description    Transport Layer header used by TL internally
@License        Dual MIT/GPLv2

The contents of this file are subject to the MIT license as set out below.

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.

Alternatively, the contents of this file may be used under the terms of
the GNU General Public License Version 2 ("GPL") in which case the provisions
of GPL are applicable instead of those above.

If you wish to allow use of your version of this file only under the terms of
GPL, and not to allow others to use your version of this file under the terms
of the MIT license, indicate your decision by deleting the provisions above
and replace them with the notice and other provisions required by GPL as set
out in the file called "GPL-COPYING" included in this distribution. If you do
not delete the provisions above, a recipient may use your version of this file
under the terms of either the MIT license or GPL.

This License is also included in this distribution in the file called
"MIT-COPYING".

EXCEPT AS OTHERWISE STATED IN A NEGOTIATED AGREEMENT: (A) 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; AND (B) 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.
*/ /**************************************************************************/
#ifndef TLINTERN_H
#define TLINTERN_H


#include "devicemem_typedefs.h"
#include "pvrsrv_tlcommon.h"
#include "lock.h"
#include "tlstream.h"

/* Forward declarations */
typedef struct _TL_SNODE_* PTL_SNODE;

/* To debug buffer utilisation enable this macro here and define
 * PVRSRV_NEED_PVR_TRACE in the server pvr_debug.c and in tutils.c
 * before the inclusion of pvr_debug.h.
 * Issue pvrtutils 6 on target to see stream buffer utilisation. */
//#define TL_BUFFER_STATS 1

/*! TL stream structure container.
 *    pbyBuffer   holds the circular buffer.
 *    ui32Read    points to the beginning of the buffer, ie to where data to
 *                  Read begin.
 *    ui32Write   points to the end of data that have been committed, ie this is
 *                  where new data will be written.
 *    ui32Pending number of bytes reserved in last reserve call which have not
 *                  yet been submitted. Therefore these data are not ready to
 *                  be transported.
 *    hStreamWLock - provides atomic protection for the ui32Pending & ui32Write
 *                   members of the structure for when they are checked and/or
 *                   updated in the context of a stream writer (producer)
 *                   calling DoTLStreamReserve() & TLStreamCommit().
 *                 - Reader context is not multi-threaded, only one client per
 *                   stream is allowed. Also note the read context may be in an
 *                   ISR which prevents a design where locks can be held in the
 *                   AcquireData/ReleaseData() calls. Thus this lock only
 *                   protects the stream members from simultaneous writers.
 *
 *      ui32Read < ui32Write <= ui32Pending
 *        where < and <= operators are overloaded to make sense in a circular way.
 */
typedef struct _TL_STREAM_
{
	IMG_CHAR                szName[PRVSRVTL_MAX_STREAM_NAME_SIZE];  /*!< String name identifier */
	PVRSRV_DEVICE_NODE      *psDevNode;                             /*!< Underlying device on which the stream's buffer is allocated */
	TL_OPMODE               eOpMode;                                /*!< Mode of Operation of TL Buffer */

	IMG_BOOL                bWaitForEmptyOnDestroy;                 /*!< Flag: On destroying a non-empty stream block until
                                                                         *         stream is drained. */
	IMG_BOOL                bNoSignalOnCommit;                      /*!< Flag: Used to avoid the TL signalling waiting consumers
                                                                         *         that new data is available on every commit. Producers
                                                                         *         using this flag will need to manually signal when
                                                                         *         appropriate using the TLStreamSync() API */

	void                    (*pfOnReaderOpenCallback)(void *);      /*!< Optional on reader connect callback */
	void                    *pvOnReaderOpenUserData;                /*!< On reader connect user data */
	void                    (*pfProducerCallback)(void);            /*!< Optional producer callback of type TL_STREAM_SOURCECB */
	void                    *pvProducerUserData;                    /*!< Producer callback user data */

	struct _TL_STREAM_      *psNotifStream;                         /*!< Pointer to the stream to which notification will be sent */

	volatile IMG_UINT32     ui32Read;                               /*!< Pointer to the beginning of available data */
	volatile IMG_UINT32     ui32Write;                              /*!< Pointer to already committed data which are ready to be
                                                                         *   copied to user space */
	IMG_UINT32              ui32Pending;                            /*!< Count pending bytes reserved in buffer */
	IMG_UINT32              ui32Size;                               /*!< Buffer size */
	IMG_UINT32              ui32ThresholdUsageForSignal;            /*!< Buffer usage threshold at which a TL writer signals a blocked/
	                                                                     *    waiting reader when transitioning from empty->non-empty */
	IMG_UINT32              ui32MaxPacketSize;                      /*! Max TL packet size */
	IMG_BYTE                *pbyBuffer;                             /*!< Actual data buffer */

	PTL_SNODE               psNode;                                 /*!< Ptr to parent stream node */
	DEVMEM_MEMDESC          *psStreamMemDesc;                       /*!< MemDescriptor used to allocate buffer space through PMR */

	IMG_HANDLE              hProducerEvent;	                        /*!< Handle to wait on if there is not enough space */
	IMG_HANDLE              hProducerEventObj;                      /*!< Handle to signal blocked reserve calls */
	IMG_BOOL                bSignalPending;                         /*!< Tracks if a "signal" is pending to be sent to a blocked/
	                                                                     *    waiting reader */

	POS_LOCK                hStreamWLock;                           /*!< Writers Lock for ui32Pending & ui32Write*/
	POS_LOCK                hReadLock;                              /*!< Readers Lock for bReadPending & ui32Read*/
	IMG_BOOL                bReadPending;                           /*!< Tracks if a read operation is pending or not*/
	IMG_BOOL                bNoWrapPermanent;                       /*!< Flag: Prevents buffer wrap and subsequent data loss
	                                                                     *    as well as resetting the read position on close. */

#if defined(TL_BUFFER_STATS)
	IMG_UINT32              ui32CntReadFails;                       /*!< Tracks how many times reader failed to acquire read lock */
	IMG_UINT32              ui32CntReadSuccesses;                   /*!< Tracks how many times reader acquires read lock successfully */
	IMG_UINT32              ui32CntWriteSuccesses;                  /*!< Tracks how many times writer acquires read lock successfully */
	IMG_UINT32              ui32CntWriteWaits;                      /*!< Tracks how many times writer had to wait to acquire read lock */
	IMG_UINT32              ui32CntNumWriteSuccess;	                /*!< Tracks how many write operations were successful*/
	IMG_UINT32              ui32BufferUt;                           /*!< Buffer utilisation high watermark, see TL_BUFFER_STATS above */
	IMG_UINT32              ui32MaxReserveWatermark;                /*!< Max stream reserve size that was ever requested by a writer */
	IMG_UINT32              ui32SignalsSent;                        /*!< Number of signals that were actually sent by the write API */
	ATOMIC_T                bNoReaderSinceFirstReserve;             /*!< Tracks if a read has been done since the buffer was last found empty */
	IMG_UINT32              ui32TimeStart;                          /*!< Time at which a write (Reserve call) was done into an empty buffer.
	                                                                     *    Guarded by hStreamWLock. */
	IMG_UINT32              ui32MinTimeToFullInUs;                  /*!< Minimum time taken to (nearly) fully fill an empty buffer. Guarded
	                                                                     *    by hStreamWLock. */
	/* Behaviour counters, protected by hStreamLock in case of
	 * multi-threaded access */
	IMG_UINT32              ui32NumCommits;     /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32              ui32SignalNotSent;  /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32              ui32ManSyncs;       /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32              ui32ProducerByteCount; /*!< Counters used to analysing stream performance, see ++ loc */

	/* Not protected by the lock, inc in the reader thread which is currently singular */
	IMG_UINT32              ui32AcquireRead1;   /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32              ui32AcquireRead2;   /*!< Counters used to analysing stream performance, see ++ loc */
#endif

} TL_STREAM, *PTL_STREAM;

/* there need to be enough space reserved in the buffer for 2 minimal packets
 * and it needs to be aligned the same way the buffer is or there will be a
 * compile error.*/
#define BUFFER_RESERVED_SPACE (2 * PVRSRVTL_PACKET_ALIGNMENT)

/* ensure the space reserved follows the buffer's alignment */
static_assert(!(BUFFER_RESERVED_SPACE&(PVRSRVTL_PACKET_ALIGNMENT-1)),
			  "BUFFER_RESERVED_SPACE must be a multiple of PVRSRVTL_PACKET_ALIGNMENT");

/* Define the largest value that a uint that matches the
 * PVRSRVTL_PACKET_ALIGNMENT size can hold */
#define MAX_UINT 0xffffFFFF

/*! Defines the value used for TL_STREAM.ui32Pending when no reserve is
 * outstanding on the stream. */
#define NOTHING_PENDING IMG_UINT32_MAX


/*
 * Transport Layer Stream Descriptor types/defs
 */
typedef struct _TL_STREAM_DESC_
{
	PTL_SNODE   psNode;         /*!< Ptr to parent stream node */
	IMG_UINT32  ui32Flags;      /*!< Flags supplied by client on stream open */
	IMG_HANDLE  hReadEvent;     /*!< For wait call (only used/set in reader descriptors) */
	IMG_INT     uiRefCount;     /*!< Reference count to the SD */

#if defined(TL_BUFFER_STATS)
	/* Behaviour counters, no multi-threading protection need as they are
	 * incremented in a single thread due to only supporting one reader
	 * at present */
	IMG_UINT32  ui32AcquireCount;  /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32  ui32NoData;        /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32  ui32NoDataSleep;   /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32  ui32Signalled;     /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32  ui32TimeoutEmpty;  /*!< Counters used to analysing stream performance, see ++ loc */
	IMG_UINT32  ui32TimeoutData;   /*!< Counters used to analysing stream performance, see ++ loc */
#endif
	IMG_UINT32  ui32ReadLimit;     /*!< Limit buffer reads to data present in the
                                        buffer at the time of stream open. */
	IMG_UINT32  ui32ReadLen;       /*!< Size of data returned by initial Acquire */
} TL_STREAM_DESC, *PTL_STREAM_DESC;

PTL_STREAM_DESC TLMakeStreamDesc(PTL_SNODE f1, IMG_UINT32 f2, IMG_HANDLE f3);

#define TL_STREAM_KM_FLAG_MASK	0xFFFF0000
#define TL_STREAM_FLAG_TEST		0x10000000
#define TL_STREAM_FLAG_WRAPREAD	0x00010000

#define TL_STREAM_UM_FLAG_MASK	0x0000FFFF

#if defined(TL_BUFFER_STATS)
#	define TL_COUNTER_INC(a)    ((a)++)
#	define TL_COUNTER_ADD(a,b)  ((a) += (b))
#else
#	define TL_COUNTER_INC(a)    (void)(0)
#	define TL_COUNTER_ADD(a,b)  (void)(0)
#endif
/*
 * Transport Layer stream list node
 */
typedef struct _TL_SNODE_
{
	struct _TL_SNODE_*	psNext;				/*!< Linked list next element */
	IMG_HANDLE			hReadEventObj;		/*!< Readers 'wait for data' event */
	PTL_STREAM			psStream;			/*!< TL Stream object */
	IMG_INT				uiWRefCount;		/*!< Stream writer reference count */
	PTL_STREAM_DESC		psRDesc;			/*!< Stream reader 0 or ptr only */
	PTL_STREAM_DESC		psWDesc;			/*!< Stream writer 0 or ptr only */
} TL_SNODE;

PTL_SNODE TLMakeSNode(IMG_HANDLE f2, TL_STREAM *f3, TL_STREAM_DESC *f4);

/*
 * Transport Layer global top types and variables
 * Use access function to obtain pointer.
 *
 * hTLGDLock - provides atomicity over read/check/write operations and
 *             sequence of operations on uiClientCnt, psHead list of SNODEs and
 *             the immediate members in a list element SNODE structure.
 *           - This larger scope of responsibility for this lock helps avoid
 *             the need for a lock in the SNODE structure.
 *           - Lock held in the client (reader) context when streams are
 *             opened/closed and in the server (writer) context when streams
 *             are created/open/closed.
 */
typedef struct _TL_GDATA_
{
	IMG_HANDLE hTLEventObj;        /* Global TL signal object, new streams, etc */

	IMG_UINT   uiClientCnt;        /* Counter to track the number of client stream connections. */
	PTL_SNODE  psHead;             /* List of TL streams and associated client handle */

	POS_LOCK   hTLGDLock;          /* Lock for structure AND psHead SNODE list */
} TL_GLOBAL_DATA, *PTL_GLOBAL_DATA;

/*
 * Transport Layer Internal Kernel-Mode Server API
 */
TL_GLOBAL_DATA* TLGGD(void);		/* TLGetGlobalData() */

PVRSRV_ERROR TLInit(void);
void TLDeInit(void);

void TLAddStreamNode(PTL_SNODE psAdd);
PTL_SNODE TLFindStreamNodeByName(const IMG_CHAR *pszName);
PTL_SNODE TLFindStreamNodeByDesc(PTL_STREAM_DESC psDesc);
IMG_UINT32 TLDiscoverStreamNodes(const IMG_CHAR *pszNamePattern,
                          IMG_CHAR aaszStreams[][PRVSRVTL_MAX_STREAM_NAME_SIZE],
                          IMG_UINT32 ui32Max);
PTL_SNODE TLFindAndGetStreamNodeByDesc(PTL_STREAM_DESC psDesc);
void TLReturnStreamNode(PTL_SNODE psNode);

/****************************************************************************************
 Function Name	: TLTryRemoveStreamAndFreeStreamNode

 Inputs		: PTL_SNODE	Pointer to the TL_SNODE whose stream is requested
			to be removed from TL_GLOBAL_DATA's list

 Return Value	: IMG_TRUE	-	If the stream was made NULL and this
					TL_SNODE was removed from the
					TL_GLOBAL_DATA's list

		  IMG_FALSE	-	If the stream wasn't made NULL as there
					is a client connected to this stream

 Description	: If there is no client currently connected to this stream then,
			This function removes this TL_SNODE from the
			TL_GLOBAL_DATA's list. The caller is responsible for the
			cleanup of the TL_STREAM whose TL_SNODE may be removed

		  Otherwise, this function does nothing
*****************************************************************************************/
IMG_BOOL  TLTryRemoveStreamAndFreeStreamNode(PTL_SNODE psRemove);

/*****************************************************************************************
 Function Name	: TLUnrefDescAndTryFreeStreamNode

 Inputs		: PTL_SNODE	Pointer to the TL_SNODE whose descriptor is
			requested to be removed
			: PTL_STREAM_DESC	Pointer to the STREAM_DESC

 Return Value	: IMG_TRUE	-	If this	TL_SNODE was removed from the
					TL_GLOBAL_DATA's list

		  IMG_FALSE	-	Otherwise

 Description	: This function removes the stream descriptor from this TL_SNODE
			and, if there is no writer (producer context) currently bound to this
			stream, this function removes this TL_SNODE from the TL_GLOBAL_DATA's
			list. The caller is responsible for the cleanup of the TL_STREAM
			whose TL_SNODE may be removed
******************************************************************************************/
IMG_BOOL TLUnrefDescAndTryFreeStreamNode(PTL_SNODE psRemove, PTL_STREAM_DESC psSD);

/*
 * Transport Layer stream interface to server part declared here to avoid
 * circular dependency.
 */
IMG_UINT32 TLStreamAcquireReadPos(PTL_STREAM psStream,
                                  IMG_BOOL bDisableCallback,
                                  IMG_UINT32* puiReadOffset);
PVRSRV_ERROR TLStreamAdvanceReadPos(PTL_STREAM psStream,
                                    IMG_UINT32 uiReadLen,
                                    IMG_UINT32 uiOrigReadLen);
void TLStreamResetReadPos(PTL_STREAM psStream);

DEVMEM_MEMDESC* TLStreamGetBufferPointer(PTL_STREAM psStream);
IMG_BOOL TLStreamOutOfData(IMG_HANDLE psStream);

/****************************************************************************************
 Function Name	: TLStreamDestroy

 Inputs		: PTL_STREAM	Pointer to the TL_STREAM to be destroyed

 Description	: This function performs all the clean-up operations required for
			destruction of this stream
*****************************************************************************************/
void TLStreamDestroy(PTL_STREAM psStream);

/*
 * Test related functions
 */
PVRSRV_ERROR TUtilsInit(PVRSRV_DEVICE_NODE *psDeviceNode);
PVRSRV_ERROR TUtilsDeinit(PVRSRV_DEVICE_NODE *psDeviceNode);


#endif /* TLINTERN_H */
/******************************************************************************
 End of file (tlintern.h)
******************************************************************************/