/* 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 c_aee.h 
 *  $RCSfile: c_aee.h,v$
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains AEE specific definitions, which are
 *         exported.
 */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @defgroup groupMW_AEE Application Execution Environment
 *  @ingroup groupMW
 *  @brief Provides a unified interface for AEE
 *  %This module manages the resources an application or component can use and control
 *  the basic lifecycle of applications.
 *   - including these sub modules:
 *  @see groupMW
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_AEE_H_
#define _C_AEE_H_


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

#include "u_aee.h"
#include "u_handle.h"
#include "u_common.h"
#include "u_os.h"


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

/*------------------------------------------------------------------*/
/*! @brief              This API creates a new application handle and spawn a thread
 *                           to run the application's main function.
 *  @param [in]       pt_desc       References the application's description (resources, etc).
 *  @param [in]       ps_name     References the application's name.
 *  @param [out]     ph_app       Contains the application handle.
 *  @note
 *  @see
 *  @return      the error code
 *  @retval      AEER_OK                           Routine successful.
 *  @retval      AEER_FAIL                         The AEE cannot be created (undefined reason).
 *  @retval      AEER_OUT_OF_HANDLES    Out of handles.
 *  @retval      AEER_OUT_OF_MEMORY     Out of memory.
 *  @retval      AEER_INV_ARG                  Invalid argument.
 *  @retval      AEER_INV_NAME                Invalid name.
 *  @retval      AEER_AEE_NO_RIGHTS       Permission denied.
 */
/*------------------------------------------------------------------*/
extern INT32 c_aee_create (const AEE_APP_DESC_T*  pt_desc,
                           const CHAR*            ps_name,
                           HANDLE_T*              ph_app);

/*------------------------------------------------------------------*/
/*! @brief              This API calls the application's receive_data function.
 *  @param [in]       h_app       Contains the application handle.
 *  @param [in]       ui4_type    Contains the type of data.
 *  @param [in]       pv_data     References the data to send.
 *  @param [in]       z_data_len  Contains the size (in bytes) of the pv_data buffer.
 *  @param [out]     -
 *  @note
 *  @see
 *  @return      the error code
 *  @retval      AEER_OK          Routine successful.
 *  @retval      AEER_INV_HANDLE  Invalid handle.
 */
/*------------------------------------------------------------------*/
extern INT32 c_aee_send_data (HANDLE_T  h_app,
                              UINT32    ui4_type,
                              VOID*     pv_data,
                              SIZE_T    z_data_len);

/*------------------------------------------------------------------*/
/*! @brief              This API returns a handle to an application (different from the
 *                          handle created when the AEE was created).
 *  @param [in]      ps_name  References the name of the AEE.
 *  @param [out]    ph_app  Contains the application handle.
 *  @note
 *  @see
 *  @return     the error code
 *  @retval      AEER_OK              Routine successful.
 *  @retval      AEER_FAIL            No application with such name exists.
 *  @retval      AEER_OUT_OF_HANDLES  Out of handles.
 *  @retval      AEER_AEE_NO_RIGHTS   Permission denied.
 */
/*------------------------------------------------------------------*/
extern INT32 c_aee_get_handle (const CHAR*  ps_name,
                               HANDLE_T*    ph_app);

/*------------------------------------------------------------------*/
/*! @brief          This API returns information about the AEE (e.g. maximum number
 *                      of handles the application can allocate, etc)
 *  @param [in]     h_app     Contains the application handle.
 *  @param [in]     e_res_id  Contains the id of the resource information to get.
 *  @param [out]    pv_res    Contains the value of the resource information.
 *  @note
 *  @see
 *  @return     the error code
 *  @retval      AEER_OK       Routine successful.
 *  @retval      AEER_INV_ARG  Invalid argument.
 */
/*------------------------------------------------------------------*/
extern INT32 c_aee_get_resource_info (HANDLE_T           h_app,
                                      AEE_RESOURCE_ID_T  e_res_id,
                                      VOID*              pv_res);

/*------------------------------------------------------------------*/
/*! @brief              This API creates a new thread that belongs to the AEE.
 *  @param [in]         ps_name      References the thread name.
 *  @param [in]        z_stacksize  Specifies the thread's stack size.
 *  @param [in]        ui1_pri      Contains the thread priority.
 *  @param [in]        pf_main      Contains the thread's entry point.
 *  @param [in]        z_arg_size   Contains the size in bytes of what pv_arg points to.
 *  @param [in]        pv_arg       References the argument of pf_main.
 *  @param [out]    ph_th_hdl    Contains thread handle.
 *  @note
 *  @see
 *  @return     the error code
 *  @retval      AEER_OK       Routine successful.
 *  @retval      AEER_INV_ARG  Invalid argument.
 */
/*------------------------------------------------------------------*/
extern INT32 c_aee_thread_create (HANDLE_T*             ph_th_hdl,
                                  CHAR*                 ps_name,
                                  SIZE_T                z_stacksize,
                                  UINT8                 ui1_pri,
                                  x_os_thread_main_fct  pf_main,
                                  SIZE_T                z_arg_size,
                                  VOID*                 pv_arg);

#endif /* _C_AEE_H_ */

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

