clBufferApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : buffer
 * File        : clBufferApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 * This file contains essential definitions for the buffer management
 * library.
 *
 *
 *****************************************************************************/

#ifndef _CL_BUFFER_API_H_
#define _CL_BUFFER_API_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <clCommon.h>
#include <clRuleApi.h>
#include <clMemStats.h>
#include <clPoolIpi.h>

/*****************************************************************************/

typedef enum {
    CL_BUFFER_SEEK_SET = 0,
    CL_BUFFER_SEEK_CUR,
    CL_BUFFER_SEEK_END,
 /* Add any new seek types before this.*/
    CL_BUFFER_SEEK_MAX
} ClBufferSeekTypeT;


typedef ClPtrT ClBufferHandleT;

struct iovec;

typedef enum ClBufferMode
{
    CL_BUFFER_NATIVE_MODE,
  
    CL_BUFFER_PREALLOCATED_MODE,


    CL_BUFFER_MAX_MODE,
}ClBufferModeT;

typedef struct {
    ClUint32T numPools;
    ClPoolConfigT *pPoolConfig;
    ClBoolT lazy;
    ClBufferModeT mode;

} ClBufferPoolConfigT;


/*****************************************************************************/



/************************* BUFF MGMT APIs ************************************/


ClRcT clBufferInitialize(const ClBufferPoolConfigT *pConfig);
/*****************************************************************************/


ClRcT clBufferFinalize (void);
/*****************************************************************************/


ClRcT clBufferCreate (ClBufferHandleT *pMessageHandle);

/*****************************************************************************/

ClRcT clBufferCreateAndAllocate (ClUint32T size, ClBufferHandleT *pMessageHandle);

/*****************************************************************************/


ClRcT clBufferDelete (ClBufferHandleT *pMessageHandle);

/*****************************************************************************/

ClRcT clBufferClear (ClBufferHandleT messageHandle);

/*****************************************************************************/

ClRcT clBufferLengthGet (ClBufferHandleT messageHandle, ClUint32T *pMessageLength);

/*****************************************************************************/

ClRcT clBufferLengthCalc (ClBufferHandleT bufferHandle);


ClRcT clBufferNBytesRead (ClBufferHandleT messageHandle, ClUint8T *pByteBuffer, ClUint32T* pNumberOfBytesToRead);

/*****************************************************************************/


ClRcT clBufferNBytesWrite (ClBufferHandleT messageHandle, ClUint8T *pByteBuffer, ClUint32T numberOfBytesToWrite);

/*****************************************************************************/


ClRcT clBufferChecksum16Compute(ClBufferHandleT messageHandle,ClUint32T startOffset,ClUint32T length, ClUint16T* pChecksum);
/****************************************************************************/


ClRcT
clBufferChecksum32Compute(ClBufferHandleT messageHandle, ClUint32T startOffset, ClUint32T length, ClUint32T* pChecksum);

/*****************************************************************************/


ClRcT
clBufferDataPrepend (ClBufferHandleT messageHandle, ClUint8T *pByteBuffer, ClUint32T numberOfBytesToWrite);

/*****************************************************************************/



ClRcT
clBufferConcatenate (ClBufferHandleT destination, ClBufferHandleT *pSource);

/*****************************************************************************/


ClRcT
clBufferReadOffsetGet (ClBufferHandleT messageHandle, ClUint32T *pReadOffset);

/*****************************************************************************/


ClRcT
clBufferWriteOffsetGet (ClBufferHandleT messageHandle, ClUint32T *pWriteOffset);

/*****************************************************************************/


ClRcT
clBufferReadOffsetSet (ClBufferHandleT messageHandle, ClInt32T newReadOffset, ClBufferSeekTypeT seekType);

/*****************************************************************************/


ClRcT
clBufferWriteOffsetSet (ClBufferHandleT messageHandle, ClInt32T newWriteOffset, ClBufferSeekTypeT seekType);

/*****************************************************************************/

ClRcT
clBufferHeaderTrim (ClBufferHandleT messageHandle, ClUint32T numberOfBytes);

/*****************************************************************************/


ClRcT
clBufferTrailerTrim (ClBufferHandleT messageHandle, ClUint32T numberOfBytes);

/*****************************************************************************/



ClRcT
clBufferToBufferCopy(ClBufferHandleT sourceMessage, ClUint32T sourceMessageOffset,
                      ClBufferHandleT destinationMessage, ClUint32T numberOfBytes);

/*****************************************************************************/


ClRcT
clBufferDuplicate (ClBufferHandleT messageHandle, ClBufferHandleT *pDuplicatedMessage);

/*
 * Same as duplicate but just shares the chain with the source and copies only the first chain,
 * so any metadata prepended would be local. However a write to the cloned buffer would result in a COW
 * or copy on write of the cloned destination buffer from the parent.
*/
ClRcT
clBufferClone (ClBufferHandleT source, ClBufferHandleT *pClone);

/*
 * Stich a heap allocated chunk to the buffer chain without duplication.
 */
ClRcT
clBufferAppendHeap (ClBufferHandleT source, ClUint8T *buffer, ClUint32T size);

/*****************************************************************************/

ClRcT
clBufferFlatten(ClBufferHandleT messageHandle,
                   ClUint8T** ppFlattenBuffer);

/*****************************************************************************/


ClRcT
clBufferUserToKernelCopy(ClBufferHandleT userMessageHandle,
                      ClBufferHandleT* pKernelMessageHandle);


/*****************************************************************************/



ClRcT
clBufferKernelToUserCopy(ClBufferHandleT kernelMessageHandle,
                    ClBufferHandleT userMessageHandle);
/*****************************************************************************/

ClRcT
clBufferShrink(ClPoolShrinkOptionsT *pShrinkOptions);
/*****************************************************************************/


    ClRcT clDbgBufferPrint(ClBufferHandleT buffer);
    
    
ClRcT clBufferStatsGet(ClMemStatsT *pBufferStats);

/*****************************************************************************/

ClRcT clBufferPoolStatsGet(ClUint32T numPools,ClUint32T *pPoolSize,ClPoolStatsT *pBufferPoolStats);

/*****************************************************************************/

ClRcT clBufferVectorize(ClBufferHandleT buffer,struct iovec **ppIOVector,ClInt32T *pNumVectors);

/*****************************************************************************/
    /*The below definitions are deprecated and should no longer be used*/
    
typedef ClBufferHandleT ClBufferMessageHandleT CL_DEPRECATED;

ClRcT 
clBufferMessageCreate(ClBufferHandleT *pMessageHandle) CL_DEPRECATED;

ClRcT
clBufferMessageCreateAndAllocate(ClUint32T size, ClBufferHandleT *pMessageHandle) CL_DEPRECATED;


ClRcT
clBufferMessageDelete(ClBufferHandleT *pMessageHandle) CL_DEPRECATED;

ClRcT
clBufferMessageClear(ClBufferHandleT messageHandle) CL_DEPRECATED;

ClRcT
clBufferMessageLengthGet(ClBufferHandleT messageHandle, ClUint32T *pMessageLength) CL_DEPRECATED;

ClRcT
clBufferMessageNBytesRead(ClBufferHandleT messageHandle, 
                          ClUint8T *pByteBuffer, 
                          ClUint32T* pNumberOfBytesToRead) CL_DEPRECATED;

ClRcT
clBufferMessageNBytesWrite(ClBufferHandleT messageHandle, 
                           ClUint8T *pByteBuffer, 
                           ClUint32T numberOfBytesToWrite) CL_DEPRECATED;

ClRcT
clBufferMessageDataPrepend(ClBufferHandleT messageHandle, 
                           ClUint8T *pByteBuffer, 
                           ClUint32T numberOfBytesToWrite) CL_DEPRECATED;

ClRcT
clBufferMessageConcatenate(ClBufferHandleT destination, ClBufferHandleT *pSource) CL_DEPRECATED;

ClRcT
clBufferMessageReadOffsetGet(ClBufferHandleT messageHandle,
                             ClUint32T *pReadOffset) CL_DEPRECATED;

ClRcT
clBufferMessageWriteOffsetGet(ClBufferHandleT messageHandle,
                              ClUint32T *pWriteOffset) CL_DEPRECATED;

ClRcT
clBufferMessageReadOffsetSet(ClBufferHandleT messageHandle,
                             ClInt32T newReadOffset,
                             ClBufferSeekTypeT seekType) CL_DEPRECATED;

ClRcT
clBufferMessageWriteOffsetSet(ClBufferHandleT messageHandle,
                              ClInt32T newWriteOffset,
                              ClBufferSeekTypeT seekType) CL_DEPRECATED;

ClRcT
clBufferMessageHeaderTrim(ClBufferHandleT messageHandle,
                          ClUint32T numberOfBytes) CL_DEPRECATED;

ClRcT
clBufferMessageTrailerTrim(ClBufferHandleT messageHandle,
                           ClUint32T numberOfBytes) CL_DEPRECATED;

ClRcT
clBufferMessageToMessageCopy(ClBufferHandleT source,
                             ClUint32T sourceOffset,
                             ClBufferHandleT destination,
                             ClUint32T numberOfBytes) CL_DEPRECATED;

ClRcT
clBufferMessageDuplicate(ClBufferHandleT source,
                         ClBufferHandleT *pDuplicate) CL_DEPRECATED;
#ifdef __cplusplus
}
#endif

#endif /* _CL_BUFFER_API_H_ */