| /*************************************************************************/ /*! |
| @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 "device.h" |
| #include "lock.h" |
| |
| /* Forward declarations */ |
| typedef struct _TL_SNODE_* PTL_SNODE; |
| |
| /*! 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. |
| * hStreamLock - 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 */ |
| IMG_BOOL bDrop; /*!< Flag: When buffer is full drop new data instead of |
| overwriting older data */ |
| IMG_BOOL bBlock; /*!< Flag: When buffer is full reserve will block until there is |
| enough free space in the buffer to fullfil the request. */ |
| 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 */ |
| |
| 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 ui32BufferUt; /*!< Buffer utilisation high watermark, see |
| * TL_BUFFER_UTILIZATION in tlstream.c */ |
| IMG_UINT32 ui32Pending; /*!< Count pending bytes reserved in buffer */ |
| IMG_UINT32 ui32Size; /*!< Buffer 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 */ |
| |
| POS_LOCK hStreamLock; /*!< Writers Lock for ui32Pending & ui32Write*/ |
| } 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; |
| IMG_HANDLE hReadEvent; /*!< For wait call (only used/set in reader descriptors) */ |
| IMG_INT uiRefCount; /*!< Reference count to the SD */ |
| } 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 |
| |
| /* |
| * 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_ |
| { |
| void *psRgxDevNode; /* Device node to use for buffer allocations */ |
| 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(PVRSRV_DEVICE_NODE *psDevNode); |
| void TLDeInit(PVRSRV_DEVICE_NODE *psDevNode); |
| |
| PVRSRV_DEVICE_NODE* TLGetGlobalRgxDevice(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_UINT32 *pui32Streams, |
| 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_UINT32* puiReadOffset); |
| void TLStreamAdvanceReadPos(PTL_STREAM psStream, IMG_UINT32 uiReadLen); |
| |
| DEVMEM_MEMDESC* TLStreamGetBufferPointer(PTL_STREAM psStream); |
| IMG_BOOL TLStreamEOS(PTL_STREAM 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); |
| |
| /* |
| * 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) |
| ******************************************************************************/ |
| |
