/*************************************************************************/ /*!
|
@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)
|
*****************************************************************************/
|
