/* SPDX-License-Identifier: LGPL-2.1-only OR BSD-3-Clause */
/******************************************************************************
 *
 * This file is provided under a dual license.  When you use or
 * distribute this software, you may choose to be licensed under
 * version 2.1 of the GNU Lesser General Public License
 * ("LGPLv2.1 License") or BSD License.
 *
 * LGPLv2.1 License
 *
 * Copyright(C) 2019 MediaTek Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2.1 of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * 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 https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html for more
 * details.
 *
 * BSD LICENSE
 *
 * Copyright(C) 2019 MediaTek Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *****************************************************************************/

/*! @file u_mem_buf.h
 * $Revision: #1 $
 * $Date: 2015/05/29 $
 * $Author: brianpc.huang $
 *
 * @par Description: 
 *   This header file contains exported API for to
 *   store and retrive object (e.g., an array of bytes)
 *   to/from the mini-buffer.
 *
 *   The mini-buffer provides API to store generic object (a byte array)
 *   in the buffer (x_mem_buf_write_object()).  On success,
 *   this API returns object ID (integer value) which application can
 *   use to retrive the object (get a copy) or to delete this object from
 *   the mini-buffer.
 *
 *   
 *---------------------------------------------------------------------------*/

/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_UTIL
  *  @{  
  */
/*----------------------------------------------------------------------------*/ 

#ifndef _U_MEM_BUF_H_
#define _U_MEM_BUF_H_

/*---------------------------------------------------------------------------
                    include files
----------------------------------------------------------------------------*/

#include "u_common.h"
#include "u_handle.h"
#include "x_handle.h"


/*--------------------------------------------------------------------------
 Constants, enumerations, and macros
---------------------------------------------------------------------------*/
    
#define MEMBUFR_OK                  ((INT32)   0)   /**<Routine successful*/
#define MEMBUFR_INV_ARG             ((INT32)  -1)   /**<One or more of the arguments contain invalid data.*/
#define MEMBUFR_OUT_OF_MEM          ((INT32)  -2)   /**<There is no enough memory*/
#define MEMBUFR_INV_STR_LEN         ((INT32)  -3)   /**<The string length is invalid*/
#define MEMBUFR_INV_OBJ_ID          ((INT32)  -4)   /**<The object id is invalid*/
#define MEMBUFR_INPUT_BUF_TOO_SMALL ((INT32)  -5)   /**<The input buffer is too small*/
#define MEMBUFR_FAIL                ((INT32)  -6)   /**<Routine fail*/
#define MEMBUFR_EMPTY               ((INT32)  -7)   /**<The memory buffer is empty*/


#define MEM_BUF_MIN_BUF_SZ          (8)             /**<Definition of minimize buffer size*/
#define MEM_BUF_MIN_ARY_LEN         (1)             /**<Definition of minimize array length*/
#define MEM_BUF_MAX_OBJ_LEN         (65535)         /**<Definition of maxmium object length*/
#define MEM_BUF_NULL_OBJ_ID         (0)             /**<Definition the ID of null object*/
#define MEM_BUF_MEM_GROW_INC        (512)           /**<Definition the memory grow increase step*/
#define MEM_BUF_ARY_GROW_INC        (16)            /**<Definition the array grow increase step*/
#define MEM_BUF_MAX_SZ              (655360)        /**<Definition the buffer's maxnium size*/
#define MEM_BUF_MAX_NB_STR_OBJ      ((65536)>>2)    /**<Definition the maxmium number of string object*/

/* ------------------------------------------------------------------------
                   ABORT code
 -------------------------------------------------------------------------*/

/* Error code. */
#define DBG_ABRT_MEM_BUF_CORRUPTED         ((UINT32) 0x00000012)
/**<The error code of memory buffer corrupted*/

/*---------------------------------------------------------------------------
 Type definition
----------------------------------------------------------------------------*/

/* 
  Typedef for the memory-buffer control structure       
*/
/*------------------------------------------------------------------*/
/*! @brief the typedef for the memory-buffer control structure  
*  @code 
*  typedef struct _MEM_BUF_T_ 
*  { 
*      UINT8*        pui1_mem_buf;
*      UINT32*       pui4_ary; 
*      UINT32        ui4_obj_buf_sz;
*      UINT32        ui4_mem_used; 
*      UINT16        ui2_ary_len; 
*      UINT16        ui2_nb_obj;   
*  } MEM_BUF_T; 
*  @endcode 
*  @li@c  pui1_mem_buf      -address of memory buffer. 
*  @li@c  pui4_ary               -array containing object's location (offset) in the buffer 'pui1_mem_buf'. 
*  @li@c  ui4_obj_buf_sz      -size of 'pui1_mem_buf'
*  @li@c  ui4_mem_used      -total memory used by objects. 
*  @li@c  ui2_ary_len           -nb of entries in 'pui4_ary'.
*  @li@c  ui2_nb_obj            -number of objects. 
*/
 /*------------------------------------------------------------------*/
typedef struct _MEM_BUF_T_
{
                             
    UINT8*        pui1_mem_buf;     /* address of memory buffer.  */
    UINT32*       pui4_ary;         /* array containing object's
                                       location (offset) in the buffer
                                       'pui1_mem_buf'. */
    UINT32        ui4_obj_buf_sz;   /* size of 'pui1_mem_buf'. */
    UINT32        ui4_mem_used;     /* total memory used by objects. */
    
    UINT16        ui2_ary_len;      /* nb of entries in 'pui4_ary'.*/
    UINT16        ui2_nb_obj;       /* number of objects. */
	HANDLE_T	  h_hash;			/* point to hash table filled with offset */
    
    
} MEM_BUF_T ;


typedef  UINT16    OBJECT_ID_T;     /**<The typedef definition of OBJECT_ID_T*/

#endif   /*  _U_MEM_BUF_H_ */

/*----------------------------------------------------------------------------*/
/*! @} */                                               /* end of groupMW_UTIL*/
/*----------------------------------------------------------------------------*/



