| /*************************************************************************/ /*! |
| @File |
| @Title Transport Layer kernel side API. |
| @Copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved |
| @Description TL provides driver components with a way to copy data from kernel |
| space to user space (e.g. screen/file). |
| |
| Data can be passed to the Transport Layer through the |
| TL Stream (kernel space) API interface. |
| |
| The buffer provided to every stream is a modified version of a |
| circular buffer. Which CB version is created is specified by |
| relevant flags when creating a stream. Currently two types |
| of buffer are available: |
| - TL_FLAG_RESERVE_DROP_NEWER: |
| When the buffer is full, incoming data are dropped |
| (instead of overwriting older data) and a marker is set |
| to let the user know that data have been lost. |
| - TL_FLAG_RESERVE_BLOCK: |
| When the circular buffer is full, reserve/write calls block |
| until enough space is freed. |
| |
| All size/space requests are in bytes. However, the actual |
| implementation uses native word sizes (i.e. 4 byte aligned). |
| |
| The user does not need to provide space for the stream buffer |
| as the TL handles memory allocations and usage. |
| |
| Inserting data to a stream's buffer can be done either: |
| - by using TLReserve/TLCommit: User is provided with a buffer |
| to write data to. |
| - or by using TLWrite: User provides a buffer with |
| data to be committed. The TL |
| copies the data from the |
| buffer into the stream buffer |
| and returns. |
| Users should be aware that there are implementation overheads |
| associated with every stream buffer. If you find that less |
| data are captured than expected then try increasing the |
| stream buffer size or use TLInfo to obtain buffer parameters |
| and calculate optimum required values at run time. |
| @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 __TLSTREAM_H__ |
| #define __TLSTREAM_H__ |
| |
| |
| #include "img_types.h" |
| #include "pvrsrv_error.h" |
| |
| /*! Flags specifying stream and circular buffer behaviour */ |
| /*! Reject new data if the buffer is full, producer may then decide to |
| * drop the data or retry after some time. */ |
| #define TL_FLAG_RESERVE_DROP_NEWER (1U<<0) |
| /*! Block Reserve (subsequently Write) calls if there is not enough space |
| * until some space is freed via a client read operation. */ |
| #define TL_FLAG_RESERVE_BLOCK (1U<<1) |
| /*! When buffer is full, advance the tail/read position to accept the new |
| * reserve call (size permitting), effectively overwriting the oldest |
| * data in the circular buffer. Not supported yet. */ |
| #define TL_FLAG_RESERVE_DROP_OLDEST (1U<<2) |
| |
| /*! Do not destroy stream if there still are data that have not been |
| * copied in user space. BLock until the stream is emptied. */ |
| #define TL_FLAG_FORCE_FLUSH (1U<<8) |
| /*! Do not signal consumers on commit automatically when the stream buffer |
| * transitions from empty to non-empty. Producer responsible for signal when |
| * it chooses. */ |
| #define TL_FLAG_NO_SIGNAL_ON_COMMIT (1U<<9) |
| |
| /*! Defer allocation of stream's shared memory until first open. */ |
| #define TL_FLAG_ALLOCATE_ON_FIRST_OPEN (1U<<10) |
| |
| /*! Structure used to pass internal TL stream sizes information to users.*/ |
| typedef struct _TL_STREAM_INFO_ |
| { |
| IMG_UINT32 headerSize; /*!< Packet header size in bytes */ |
| IMG_UINT32 minReservationSize; /*!< Minimum data size reserved in bytes */ |
| IMG_UINT32 pageSize; /*!< Page size in bytes */ |
| IMG_UINT32 pageAlign; /*!< Page alignment in bytes */ |
| } TL_STREAM_INFO, *PTL_STREAM_INFO; |
| |
| /*! Callback operations or notifications that a stream producer may handle |
| * when requested by the Transport Layer. |
| */ |
| #define TL_SOURCECB_OP_CLIENT_EOS 0x01 /*!< Client has reached end of stream, |
| * can anymore data be supplied? |
| * ui32Resp ignored in this operation */ |
| |
| /*! Function pointer type for the callback handler into the "producer" code |
| * that writes data to the TL stream. Producer should handle the notification |
| * or operation supplied in ui32ReqOp on stream hStream. The |
| * Operations and notifications are defined above in TL_SOURCECB_OP */ |
| typedef PVRSRV_ERROR (*TL_STREAM_SOURCECB)(IMG_HANDLE hStream, |
| IMG_UINT32 ui32ReqOp, IMG_UINT32* ui32Resp, void* pvUser); |
| |
| typedef void (*TL_STREAM_ONREADEROPENCB)(void *pvArg); |
| |
| /*************************************************************************/ /*! |
| @Function TLAllocSharedMem |
| @Description Allocates shared memory for the stream. |
| @Input phStream Stream handle. |
| @Return eError Internal services call returned eError error |
| number. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLAllocSharedMemIfNull(IMG_HANDLE hStream); |
| |
| /*************************************************************************/ /*! |
| @Function TLFreeSharedMem |
| @Description Frees stream's shared memory. |
| @Input phStream Stream handle. |
| */ /**************************************************************************/ |
| void |
| TLFreeSharedMem(IMG_HANDLE hStream); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamCreate |
| @Description Request the creation of a new stream and open a handle. |
| If creating a stream which should continue to exist after the |
| current context is finished, then TLStreamCreate must be |
| followed by a TLStreamOpen call. On any case, the number of |
| create/open calls must balance with the number of close calls |
| used. This ensures the resources of a stream are released when |
| it is no longer required. |
| @Output phStream Pointer to handle to store the new stream. |
| @Input szStreamName Name of stream, maximum length: |
| PRVSRVTL_MAX_STREAM_NAME_SIZE. |
| If a longer string is provided,creation fails. |
| @Input ui32Size Desired buffer size in bytes. |
| @Input ui32StreamFlags Flags that configure buffer behaviour.See above. |
| @Input pfProducerDB Optional callback, may be null. |
| @Input pvProducerData Optional user data for callback, may be null. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handle or string name |
| exceeded MAX_STREAM_NAME_SIZE |
| @Return PVRSRV_ERROR_OUT_OF_MEMORY Failed to allocate space for stream |
| handle. |
| @Return PVRSRV_ERROR_DUPLICATE_VALUE There already exists a stream with |
| the same stream name string. |
| @Return eError Internal services call returned |
| eError error number. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamCreate(IMG_HANDLE *phStream, |
| IMG_CHAR *szStreamName, |
| IMG_UINT32 ui32Size, |
| IMG_UINT32 ui32StreamFlags, |
| TL_STREAM_ONREADEROPENCB pfOnReaderOpenCB, |
| void *pvOnReaderOpenUD, |
| TL_STREAM_SOURCECB pfProducerCB, |
| void *pvProducerUD); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamOpen |
| @Description Attach to existing stream that has already been created by a |
| TLStreamCreate call. A handle is returned to the stream. |
| @Output phStream Pointer to handle to store the stream. |
| @Input szStreamName Name of stream, should match an already |
| existing stream name |
| @Return PVRSRV_ERROR_NOT_FOUND None of the streams matched the |
| requested stream name. |
| PVRSRV_ERROR_INVALID_PARAMS non NULL pointer to stream |
| handler is required. |
| @Return PVRSRV_OK Success. |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamOpen(IMG_HANDLE *phStream, |
| IMG_CHAR *szStreamName); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamReconfigure |
| @Description Request the stream flags controlling buffer behaviour to |
| be updated. |
| In the case where TL_FLAG_RESERVE_BLOCK is to be used, |
| TLStreamCreate should be called without that flag and this |
| function used to change the stream mode once a consumer process |
| has been started. This avoids a deadlock scenario where the |
| TLStreaWrite/TLStreamReserve call will hold the Bridge Lock |
| while blocking if the TL buffer is full. |
| The TL_FLAG_RESERVE_BLOCK should never drop the Bridge Lock |
| as this leads to another deadlock scenario where the caller to |
| TLStreamWrite/TLStreamReserve has already acquired another lock |
| (eg. gHandleLock) which is not dropped. This then leads to that |
| thead acquiring locks out of order. |
| @Input hStream Handle to stream to update. |
| @Input ui32StreamFlags Flags that configure buffer behaviour. See above. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handle or inconsistent |
| stream flags. |
| @Return PVRSRV_ERROR_NOT_READY Stream is currently being written to |
| try again later. |
| @Return eError Internal services call returned |
| eError error number. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamReconfigure( |
| IMG_HANDLE hStream, |
| IMG_UINT32 ui32StreamFlags); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamClose |
| @Description Detach from the stream associated with the given handle. If |
| the current handle is the last one accessing the stream |
| (i.e. the number of TLStreamCreate+TLStreamOpen calls matches |
| the number of TLStreamClose calls) then the stream is also |
| deleted. |
| On return the handle is no longer valid. |
| @Input hStream Handle to stream that will be closed. |
| @Return None. |
| */ /**************************************************************************/ |
| void |
| TLStreamClose(IMG_HANDLE hStream); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamReserve |
| @Description Reserve space in stream buffer. When successful every |
| TLStreamReserve call must be followed by a matching |
| TLStreamCommit call. While a TLStreamCommit call is pending |
| for a stream, subsequent TLStreamReserve calls for this |
| stream will fail. |
| @Input hStream Stream handle. |
| @Output ppui8Data Pointer to a pointer to a location in the |
| buffer. The caller can then use this address |
| in writing data into the stream. |
| @Input ui32Size Number of bytes to reserve in buffer. |
| @Return PVRSRV_INVALID_PARAMS NULL stream handler. |
| @Return PVRSRV_ERROR_NOT_READY There are data previously reserved |
| that are pending to be committed. |
| @Return PVRSRV_ERROR_STREAM_MISUSE Misusing the stream by trying to |
| reserve more space than the |
| buffer size. |
| @Return PVRSRV_ERROR_STREAM_RESERVE_TOO_BIG The reserve size requested |
| is larger than the free |
| space or maximum supported |
| packet size. |
| @Return PVRSRV_OK Success, output arguments valid. |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamReserve(IMG_HANDLE hStream, |
| IMG_UINT8 **ppui8Data, |
| IMG_UINT32 ui32Size); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamReserve2 |
| @Description Reserve space in stream buffer. When successful every |
| TLStreamReserve call must be followed by a matching |
| TLStreamCommit call. While a TLStreamCommit call is pending |
| for a stream, subsequent TLStreamReserve calls for this |
| stream will fail. |
| @Input hStream Stream handle. |
| @Output ppui8Data Pointer to a pointer to a location in the |
| buffer. The caller can then use this address |
| in writing data into the stream. |
| @Input ui32Size Ideal number of bytes to reserve in buffer. |
| @Input ui32SizeMin Minimum number of bytes to reserve in buffer. |
| @Input pui32Available Optional, but when present and the |
| RESERVE_TOO_BIG error is returned, a size |
| suggestion is returned in this argument which |
| the caller can attempt to reserve again for a |
| successful allocation. |
| @Return PVRSRV_INVALID_PARAMS NULL stream handler. |
| @Return PVRSRV_ERROR_NOT_READY There are data previously reserved |
| that are pending to be committed. |
| @Return PVRSRV_ERROR_STREAM_MISUSE Misusing the stream by trying to |
| reserve more space than the |
| buffer size. |
| @Return PVRSRV_ERROR_STREAM_RESERVE_TOO_BIG The reserve size requested |
| is larger than the free |
| space or maximum supported |
| packet size. |
| Check the pui32Available |
| value for the correct |
| reserve size to use. |
| @Return PVRSRV_OK Success, output arguments valid. |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamReserve2(IMG_HANDLE hStream, |
| IMG_UINT8 **ppui8Data, |
| IMG_UINT32 ui32Size, |
| IMG_UINT32 ui32SizeMin, |
| IMG_UINT32* pui32Available); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamCommit |
| @Description Notify TL that data have been written in the stream buffer. |
| Should always follow and match TLStreamReserve call. |
| @Input hStream Stream handle. |
| @Input ui32Size Number of bytes that have been added to the |
| stream. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handle. |
| @Return PVRSRV_ERROR_STREAM_MISUSE Commit results in more data |
| committed than the buffer size, |
| the stream is misused. |
| @Return eError Commit was successful but |
| internal services call returned |
| eError error number. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamCommit(IMG_HANDLE hStream, |
| IMG_UINT32 ui32Size); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamWrite |
| @Description Combined Reserve/Commit call. This function Reserves space in |
| the specified stream buffer, copies ui32Size bytes of data |
| from the array pui8Src points to and Commits in an "atomic" |
| style operation. |
| @Input hStream Stream handle. |
| @Input pui8Src Source to read data from. |
| @Input ui32Size Number of bytes to copy and commit. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handler. |
| @Return eError Error codes returned by either |
| Reserve or Commit. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamWrite(IMG_HANDLE hStream, |
| IMG_UINT8 *pui8Src, |
| IMG_UINT32 ui32Size); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamSync |
| @Description Signal the consumer to start acquiring data from the stream |
| buffer. Called by producers that use the TL_FLAG_NO_SIGNAL_ON_COMMIT |
| flag to manually control when consumers starting reading the |
| stream. Used when multiple small writes need to be batched. |
| @Input hStream Stream handle. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handle. |
| @Return eError Error codes returned by either |
| Reserve or Commit. |
| @Return PVRSRV_OK |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamSync(IMG_HANDLE hStream); |
| |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamMarkEOS |
| @Description Insert a EOS marker packet in the given stream. |
| @Input hStream Stream handle. |
| @Return PVRSRV_ERROR_INVALID_PARAMS NULL stream handler. |
| @Return eError Error codes returned by either |
| Reserve or Commit. |
| @Return PVRSRV_OK Success. |
| */ /**************************************************************************/ |
| PVRSRV_ERROR |
| TLStreamMarkEOS(IMG_HANDLE hStream); |
| |
| /*************************************************************************/ /*! |
| @Function TLStreamInfo |
| @Description Run time information about buffer elemental sizes. |
| It sets psInfo members accordingly. Users can use those values |
| to calculate the parameters they use in TLStreamCreate and |
| TLStreamReserve. |
| @Output psInfo pointer to stream info structure. |
| @Return None. |
| */ /**************************************************************************/ |
| void |
| TLStreamInfo(PTL_STREAM_INFO psInfo); |
| |
| |
| #endif /* __TLSTREAM_H__ */ |
| /***************************************************************************** |
| End of file (tlstream.h) |
| *****************************************************************************/ |
| |
