source: svn/newcon3bcm2_21bu/dst/dlib/src/si/DLIB_BitOp.h

/**
        @file
                DLIB_BitOp.h

        @brief
                PHOENIX HAL library

                bitbuf, memchain, huffman

        Copyright 2006~2010 Digital STREAM Technology, Inc.
        All Rights Reserved
*/


#ifndef __DLIB_BITOP_H__
#define __DLIB_BITOP_H__


#include "DHL_OSAL.h"



#ifdef __cplusplus
extern "C" {
#endif



#if COMMENT
____Overview____(){}
#endif

/**
        @file DLIB_BitOp.h
        
        ÀÌ°÷¿¡ ÀÌ ¸ðµâ¿¡ ´ëÇØ ¼³¸íÀÌ ÇÊ¿äÇÑ °¢Á¾ ³»¿ë ±â¼ú..
        
        module overview
                - bitbuf
                - memchain
                - huffman

        APIs
        
*/


#if COMMENT
____Config____(){}
#endif

/*
        ÀÌ ºÎºÐÀº º°µµÀÇ DHL_XXX_Config configuration file À» 
        È°¿ëÇÏ´Â °ÍÀÌ ÁÁÀ» °Í °°À½.
*/


#if COMMENT
____Types____(){}
#endif

/*
        ´Ù¸¥ ¸ðµâµé°ú °øÀ¯ µÇ´Â structure ¹× enumerations.
*/


#if COMMENT
____Defines____(){}
#endif





#if COMMENT
____BitBuf____(){}
#endif


struct bitBuffer {
        UINT8*  buffer;
        UINT32  bufSize;
        UINT32  bitOffset;
        BOOLEAN overrunError;
};

typedef struct bitBuffer bitBuffer_t, *bitBufferPtr_t;

/** @brief 
                Creates a bitBuffer object from the specified byte buffer.
                After creation, the bitBufferGetBits() function can be called to extract bits.

        @param[out] instance bitBuffer instance passed back to caller.
        @param[in] buffer pointer to a byte buffer.
        @param[in] bufSize size of the buffer (in bytes).

        @return
                - DHL_FAIL_OUT_OF_MEMOERY: out of memory.
                - DHL_OK: success.
*/
DHL_RESULT bitBufferCreate (bitBufferPtr_t *instance, UINT8 *buffer, UINT32 bufSize);


/** @brief 
                Destroys the bitBuffer. DOES NOT free the buffer passed by the user in the 
                function bitBufferCreate()!!

        @param[in] instance bitBuffer instance.

        @return
                - DHL_FAIL_NULL_POINTER: the instance is NULL.
                - DHL_OK: success.
*/
DHL_RESULT bitBufferDestroy (bitBufferPtr_t instance);


/** @brief              
                Extracts the specified number of bits from the bitBuffer.  The number of
                bits must be less than or equal to 32.  If more bits are requested than
                are present in the bitBuffer, the overrunError flag is set.
                
        @param[in] instance bitBuffer instance.
        @param[in] numberOfBits the number of bits to be read from bitBuffer.

        @return
                Extracted the specified number of bits.
*/
UINT32 bitBufferGetBits (bitBufferPtr_t instance, UINT8 numberOfBits);


/** @brief 
                Skips the specified number of bits in the bitBuffer.  This operation is
                faster than extracting bits and can be used when a bit field is ignored.

        @param[in] instance bitBuffer instance.
        @param[in] numberOfBits the number of bits to be skipped.
*/
void bitBufferSkipBits (bitBufferPtr_t instance, UINT16 numberOfBits);


/** @brief 
                Returns a pointer to the current byte offset.

        @param[in] instance bitBuffer instance.

        @return
                a pointer to the current byte offset.
*/
UINT8* bitBufferGetBytePointer (bitBufferPtr_t instance);


/** @brief 
                Returns 'TRUE' if the bitBuffer is in an overrun error state.

        @param[in]  instance bitBuffer instance.

        @return
                an overrun error state of the bitBuffer.
*/
BOOLEAN bitBufferCheckError (bitBufferPtr_t instance);


/** @brief 
                Initializes the bitBuffer.      After initialization, the bitBufferGetBits() function can
                be called to extract bits.

        @param[in] instance bitBuffer instance.
        @param[in] buffer pointer to a byte buffer.
        @param[in] bufSize size of the buffer (in bytes).
*/
void bitBufferInitialize(bitBufferPtr_t instance, UINT8 *buffer, UINT32 bufSize);



#if COMMENT
____Memchain____(){}
#endif

/**     user-defined malloc */
typedef void* (*myMalloc_f) (unsigned size, const char *_file, unsigned _line);
/**     user-defined free */
typedef void (*myFree_f) (void *ppblock, const char *_file, unsigned _line);

/** memChain Setup Info */
typedef struct memChainSetup {
        UINT32          memLimit;
        myMalloc_f              Malloc;
        myFree_f                Free;
} memChainSetup_t, *memChainSetupPtr_t;

typedef struct memChainHead* memId_t;

/** memChain Status Info */
typedef struct memChainStatus {
        UINT32          memLimit;
        UINT32          totalElements;
        UINT32          totalBytes;
        UINT32          totalUserBytes; 
} memChainStatus_t, *memChainStatusPtr_t;


#if DHL_OS_USE_HEAP_DEBUG

/**
        @brief
                Creates a memChain object which links related memory into a 'chain'.  
                All     memory associated with this chain can then be easily freed.             

        @param[out] memId memId of the newly created memchain.
        @param[in] setupPtr Pointer to the memChainSetup information.

        @return
                - DHL_FAIL_INVALID_PARAM: memId or setupPtr is NULL.
                - DHL_FAIL_OUT_OF_MEMORY: out of memory.
                - DHL_OK: success.
*/
DHL_RESULT memChainCreateDbg (memId_t *memId, memChainSetupPtr_t setupPtr, const char *_file, unsigned _line);


/**
        @brief
                Destroys the memChain, freeing all associated memory.

        @param[in] memId memId of the memchain.

        @return
                -DHL_OK: success
*/
DHL_RESULT memChainDestroyDbg (memId_t memId, const char *_file, unsigned _line);


/**
        @brief
                Allocates a memory block of the requested size and associates it with the
                specified memChain.  Returns NULL if the OS_Calloc() fails or if memLimit
                will be exceeded.

        @param[in] memId Memory ID of the memchain.
        @param[in] size The size of the requested memory chunk.

        @return
                Pointer to the allocated memory block.
*/
void *memChainAllocDbg (memId_t memId, UINT32 size, const char *_file, unsigned _line);

#define memChainCreate(memId, setupPtr) memChainCreateDbg(memId, setupPtr, __FILE__, __LINE__)
#define memChainDestroy(memId) memChainDestroyDbg(memId, __FILE__, __LINE__)
#define memChainAlloc(memId, size) memChainAllocDbg(memId, size, __FILE__, __LINE__)

#else


/**
        @brief
                Creates a memChain object which links related memory into a 'chain'.  
                All     memory associated with this chain can then be easily freed.             

        @param[out] memId memId of the newly created memchain.
        @param[in] setupPtr Pointer to the memChainSetup information.

        @return
                - DHL_FAIL_INVALID_PARAM: memId or setupPtr is NULL.
                - DHL_FAIL_OUT_OF_MEMORY: out of memory.
                - DHL_OK: success.
*/
DHL_RESULT memChainCreate (memId_t *memId, memChainSetupPtr_t setupPtr);


/**
        @brief
                Destroys the memChain, freeing all associated memory.

        @param[in] memId memId of the memchain.

        @return
                -DHL_OK: success
*/
DHL_RESULT memChainDestroy (memId_t memId);


/**
        @brief
                Allocates a memory block of the requested size and associates it with the
                specified memChain.  Returns NULL if the OS_Calloc() fails or if memLimit
                will be exceeded.

        @param[in] memId memId of the memchain.
        @param[in] size The size of the requested memory chunk.

        @return
                Pointer to the allocated memory block.
*/
void* memChainAlloc (memId_t memId, UINT32 size);

#endif

/**
        @brief
                Returns memChainStatus..
                
        @param[in] memId memId of the memchain.
        @param[out] pStatus Pointer to the memChainStatus

        @return
                - DHL_FAIL_INVALID_HANDLE: memId is invalid.
                - DHL_FAIL_INVALID_PARAM: pStatus is NULL.
                - DHL_OK: success.
*/
DHL_RESULT memChainStatus (memId_t memId, memChainStatus_t *pStatus);



#if COMMENT
____Huffman____(){}
#endif

/** Multiple String Structure */
typedef enum {
        cm_None                 = 0x00,
        cm_Huffman_C4C5         = 0x01,
        cm_Huffman_C6C7         = 0x02
} compress_type_k;

/**
        @brief
                The DecodeHuffmanString() function is used to decode a Huffman-compressed string
                found in the Multiple String Structure.  The Huffman coding supports both types
                as defined in the PSIP A/65 document (Title and Description type strings).  The
                compression type using to encode the string (as specified in the Multiple String
                Structure) should be passed to this function.

                The text buffer is supplied by the caller of this function.  The length of the
                buffer is specified by the 'textlen' parameter.  A decompressed string that is
                shorter than 'textlen' is terminated with a null character.  A decompressed
                string that is longer than 'textlen' is truncated to 'textlen-1' and terminated
                with a null character.  
                
        @param[in] compressedStr Huffman-compressed string.     
        @param[in] length The length of the compressed string.
        @param[in] type compress_type.
        @param[out] text Decompressed string.
        @param[in] textlen The length of the decompressed string.

        @return 
                -DHL_OK: success.
*/
DHL_RESULT DecodeHuffmanString (UINT8 *compressedStr, UINT32 length, compress_type_k type,
                                                        char *text, UINT32 textlen);


#ifdef __cplusplus
} /* extern "C" */
#endif



#endif  /* __DLIB_BITOP_H__ */