/* 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.
 *
 *****************************************************************************/

/*-----------------------------------------------------------------------------
 * $RCSfile: handle.h,v $
 * $Revision: #1 $
 * $Date: 2015/11/10 $
 * $Author: dtvbm11 $
 *
 * Description:
 *         This header file contains handle specific definitions which are
 *         known to the whole Middleware.
 *---------------------------------------------------------------------------*/

#ifndef _HANDLE_H_
#define _HANDLE_H_


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

#include "x_handle.h"
#include "x_common.h"
#include "x_os.h"


/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/

/* Handle types which are recognized and treated in a special manner by the */
/* handle librray MUST fall between the values '1' and the value specified  */
/* by the macro HT_RES_BY_HANDLE_LIB.                                       */
#define HT_AUX_LINK_HEAD  ((HANDLE_TYPE_T)  1)


/* Return values of (*handle_parse_fct) */
typedef enum
{
    HP_NEXT,
    HP_BREAK,
    HP_RESTART
}   HP_TYPE_T;

/* Handle link structure */
typedef struct _HANDLE_LINK_T
{
    UINT32  ui4_data [2];
}   HANDLE_LINK_T;


/* Callback functions */
typedef BOOL (*handle_free_fct) (HANDLE_T       h_handle,
                                 HANDLE_TYPE_T  e_type,
                                 VOID*          pv_obj,
                                 VOID*          pv_tag,
                                 BOOL           b_req_handle);
typedef VOID (*handle_aux_free_fct) (VOID*  pv_obj);
typedef HP_TYPE_T (*handle_parse_fct) (UINT16         ui2_count,
                                       UINT16         ui2_max_count,
                                       HANDLE_T       h_handle,
                                       HANDLE_TYPE_T  e_type,
                                       VOID*          pv_obj,
                                       VOID*          pv_tag,
                                       VOID*          pv_parse_data);

typedef INT32 (*handle_autofree_fct) (HANDLE_T       h_handle,
                                      HANDLE_TYPE_T  e_type);


/*-----------------------------------------------------------------------------
                    functions declarations
 ----------------------------------------------------------------------------*/

extern INT32 handle_alloc (HANDLE_TYPE_T    e_type,
                           VOID*            pv_obj,
                           VOID*            pv_tag,
                           handle_free_fct  pf_free,
                           HANDLE_T*        ph_handle);
extern INT32 handle_delink (HANDLE_LINK_T*  pt_h_link,
                            HANDLE_T        h_handle);
extern INT32 handle_free (HANDLE_T  h_handle,
                          BOOL      b_req_handle);
extern INT32 handle_free_all (HANDLE_LINK_T*  pt_h_link);
extern INT32 handle_get_obj (HANDLE_T  h_handle,
                             VOID**    ppv_obj);
extern INT32 handle_get_type_obj (HANDLE_T        h_handle,
                                  HANDLE_TYPE_T*  pe_type,
                                  VOID**          ppv_obj);
extern INT32 handle_init (UINT16   ui2_num_handles,
                          VOID**   ppv_mem_addr,
                          SIZE_T*  pz_mem_size);
extern INT32 handle_link (HANDLE_LINK_T*  pt_h_link,
                          HANDLE_T        h_handle);
extern INT32 handle_link_init (HANDLE_LINK_T*  pt_h_link);
extern BOOL handle_link_is_empty (HANDLE_LINK_T*  pt_h_link);
extern UINT16 handle_num_links (HANDLE_LINK_T*  pt_h_link);
extern INT32 handle_parse (HANDLE_LINK_T*    pt_h_link,
                           handle_parse_fct  pf_parse,
                           VOID*             pv_parse_data);
extern INT32 handle_reg_cli (VOID);
extern INT32 handle_set_obj (HANDLE_T  h_handle,
                             VOID*     pv_obj);

/* Bug-14  2004-12-07  ffr. Add API to handle secondary linked handles. */
extern INT32 handle_alloc_aux_link_head (VOID*                pv_obj,
                                         handle_aux_free_fct  pf_aux_free,
                                         HANDLE_T*            ph_aux_head);
extern INT32 handle_link_to_aux (HANDLE_T  h_aux_head,
                                 HANDLE_T  h_handle);
extern INT32 handle_delink_from_aux (HANDLE_T  h_handle);
extern INT32 handle_next_aux_linked (HANDLE_T   h_curr_handle,
                                     HANDLE_T*  ph_next_handle);
extern UINT16 handle_num_aux_links (HANDLE_T  h_aux_head);

extern INT32 handle_set_autofree_tbl (HANDLE_TYPE_T         e_group,
                                      handle_autofree_fct*  pf_autofree_fcts);

extern VOID handle_autofree (HANDLE_T  h_handle);

#endif /* _HANDLE_H_ */
