/** @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__ */