|
Packit |
857059 |
/* BEGIN_ICS_COPYRIGHT3 ****************************************
|
|
Packit |
857059 |
|
|
Packit |
857059 |
Copyright (c) 2015, Intel Corporation
|
|
Packit |
857059 |
|
|
Packit |
857059 |
Redistribution and use in source and binary forms, with or without
|
|
Packit |
857059 |
modification, are permitted provided that the following conditions are met:
|
|
Packit |
857059 |
|
|
Packit |
857059 |
* Redistributions of source code must retain the above copyright notice,
|
|
Packit |
857059 |
this list of conditions and the following disclaimer.
|
|
Packit |
857059 |
* Redistributions in binary form must reproduce the above copyright
|
|
Packit |
857059 |
notice, this list of conditions and the following disclaimer in the
|
|
Packit |
857059 |
documentation and/or other materials provided with the distribution.
|
|
Packit |
857059 |
* Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
857059 |
may be used to endorse or promote products derived from this software
|
|
Packit |
857059 |
without specific prior written permission.
|
|
Packit |
857059 |
|
|
Packit |
857059 |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
857059 |
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
857059 |
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
Packit |
857059 |
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
|
|
Packit |
857059 |
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
Packit |
857059 |
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
Packit |
857059 |
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
Packit |
857059 |
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
Packit |
857059 |
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
Packit |
857059 |
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
857059 |
|
|
Packit |
857059 |
** END_ICS_COPYRIGHT3 ****************************************/
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/* [ICS VERSION STRING: unknown] */
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
#ifndef _IBA_PUBLIC_IHANDLETRANS_H_
|
|
Packit |
857059 |
#define _IBA_PUBLIC_IHANDLETRANS_H_
|
|
Packit |
857059 |
|
|
Packit |
857059 |
#include "iba/public/datatypes.h"
|
|
Packit |
857059 |
#include "iba/public/iarray.h"
|
|
Packit |
857059 |
#include "iba/public/iresmap.h"
|
|
Packit |
857059 |
#include "iba/public/ispinlock.h"
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
#ifdef __cplusplus
|
|
Packit |
857059 |
extern "C"
|
|
Packit |
857059 |
{
|
|
Packit |
857059 |
#endif
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Handle Translator definition.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* A Handle Translator facilitates translation from 32 bit handles to
|
|
Packit |
857059 |
* pointers to the corresponding resource. This can provide 2
|
|
Packit |
857059 |
* benefits:
|
|
Packit |
857059 |
* - a handle validation function
|
|
Packit |
857059 |
* - support for APIs (such as VAPI) with 32 bit handles
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Internally a Handle Translator uses a vector and a resource map which
|
|
Packit |
857059 |
* can be dynamically resized as more handles are created.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* The handle 0 is reserved such that 0 can be treated as a invalid handle
|
|
Packit |
857059 |
* Similarly, an unitialized/freed/deleted handle returns NULL for its pointer
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* The Locked Handle Translator has its own spinlock and is thread safe
|
|
Packit |
857059 |
*/
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/* handle translator structure is allocated by the user and is opaque to them */
|
|
Packit |
857059 |
typedef struct _LOCKED_HANDLE_TRANS
|
|
Packit |
857059 |
{
|
|
Packit |
857059 |
SPIN_LOCK m_Lock; /* protects structure */
|
|
Packit |
857059 |
ARRAY m_List; /* index is handle, contained object is ptr */
|
|
Packit |
857059 |
RESOURCE_MAP m_Map; /* efficiently track available entries in Array */
|
|
Packit |
857059 |
} LOCKED_HANDLE_TRANS;
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransInitState
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function performs basic initialization. This function cannot
|
|
Packit |
857059 |
* fail.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans - Pointer to handle translator
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
* None.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* None.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
void
|
|
Packit |
857059 |
LHandleTransInitState(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* const pLHandleTrans );
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransInit
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function initializes the handle translator.
|
|
Packit |
857059 |
* New entries in the translator are
|
|
Packit |
857059 |
* initialized to NULL.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans - Pointer to handle translator
|
|
Packit |
857059 |
* InitialSize - initial number of elements
|
|
Packit |
857059 |
* GrowSize - number of elements to allocate when incrementally growing
|
|
Packit |
857059 |
* the handle translator
|
|
Packit |
857059 |
* MaxHandles - maximum handles allowed, 0 if no limit
|
|
Packit |
857059 |
* MemFlags - memory allocate flags (IBA_MEM_FLAG_*)
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
* None.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* FSUCCESS
|
|
Packit |
857059 |
* FINSUFFICIENT_MEMORY - failed to initialize translator
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
FSTATUS
|
|
Packit |
857059 |
LHandleTransInit(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* const pLHandleTrans,
|
|
Packit |
857059 |
IN const uint32 InitialSize,
|
|
Packit |
857059 |
IN const uint32 GrowSize,
|
|
Packit |
857059 |
IN const uint32 MaxHandles,
|
|
Packit |
857059 |
IN const uint32 MemFlags );
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransDestroy
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function deallocates all allocated memory associated with the
|
|
Packit |
857059 |
* handle translator.
|
|
Packit |
857059 |
* If any operations did premptable memory allocate (via MemFlags), this
|
|
Packit |
857059 |
* may prempt.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans - Pointer to handle translator
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
* None.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* None.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
void
|
|
Packit |
857059 |
LHandleTransDestroy(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* const pLHandleTrans );
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransCreateHandle
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function creates a new 32 bit handle to the given pointer
|
|
Packit |
857059 |
* As necessary the internal vector may grow.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans- Pointer to handle translator.
|
|
Packit |
857059 |
* Ptr - Pointer of object handle is for
|
|
Packit |
857059 |
* MemFlags - memory allocate flags (IBA_MEM_FLAG_*)
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
* pHandle - Handle created
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* FSUCCESS
|
|
Packit |
857059 |
* FINSUFFICIENT_MEMORY unable to grows translator
|
|
Packit |
857059 |
* FINSUFFICIENT_RESOURCES would exceed MaxHandles specified in Init
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
FSTATUS
|
|
Packit |
857059 |
LHandleTransCreateHandle(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* pLHandleTrans,
|
|
Packit |
857059 |
IN const void* Ptr,
|
|
Packit |
857059 |
IN const uint32 MemFlags,
|
|
Packit |
857059 |
OUT uint32* pHandle );
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransReplaceHandle
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function replaces the pointer which an existing handle points to
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans- Pointer to handle translator.
|
|
Packit |
857059 |
* Handle - previously created handle
|
|
Packit |
857059 |
* Ptr - Pointer of object handle is for
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* FSUCCESS
|
|
Packit |
857059 |
* FINSUFFICIENT_MEMORY The array could not be resized to accomodate the
|
|
Packit |
857059 |
* specified element.
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
FSTATUS
|
|
Packit |
857059 |
LHandleTransReplaceHandle(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* pLHandleTrans,
|
|
Packit |
857059 |
IN uint32 Handle,
|
|
Packit |
857059 |
IN const void* Ptr);
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransDestroyHandle
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function destroys a handle, by replacing its pointer with NULL
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans- Pointer to handle translator.
|
|
Packit |
857059 |
* Handle - previously created handle
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* FSUCCESS - successfully destroyed handle
|
|
Packit |
857059 |
* FINVALID_STATE - handle was not valid
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
FSTATUS
|
|
Packit |
857059 |
LHandleTransDestroyHandle(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* pLHandleTrans,
|
|
Packit |
857059 |
IN uint32 Handle );
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
/****************************************************************************
|
|
Packit |
857059 |
* LHandleTransGetPtr
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Description:
|
|
Packit |
857059 |
* This function translates from a handle to its corresponding pointer
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Inputs:
|
|
Packit |
857059 |
* pLHandleTrans- Pointer to handle translator.
|
|
Packit |
857059 |
* Handle - previously created handle
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Outputs:
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
* Returns:
|
|
Packit |
857059 |
* pointer assigned to handle (will be NULL if invalid handle)
|
|
Packit |
857059 |
*
|
|
Packit |
857059 |
****************************************************************************/
|
|
Packit |
857059 |
void*
|
|
Packit |
857059 |
LHandleTransGetPtr(
|
|
Packit |
857059 |
IN LOCKED_HANDLE_TRANS* pLHandleTrans,
|
|
Packit |
857059 |
IN uint32 Handle);
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
#ifdef __cplusplus
|
|
Packit |
857059 |
} /* extern "C" */
|
|
Packit |
857059 |
#endif
|
|
Packit |
857059 |
|
|
Packit |
857059 |
|
|
Packit |
857059 |
#endif /* _IBA_PUBLIC_IHANDLETRANS_H_ */
|