mcu/interface/protocol/general/psilib_api.h

/******************************************************************************
*  Copyright Statement:
*  --------------------
*  This software is protected by Copyright and the information contained
*  herein is confidential. The software may not be copied and the information
*  contained herein may not be used or disclosed except with the written
*  permission of MediaTek Inc. (C) 2018
*
*  BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
*  THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE")
*  RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON
*  AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES,
*  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
*  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
*  NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
*  SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
*  SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH
*  THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO
*  NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S
*  SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM.
*
*  BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE
*  LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
*  AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE,
*  OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO
*  MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
*
*  THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
*  WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
*  LAWS PRINCIPLES.  ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
*  RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
*  THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
*
*******************************************************************************/
 
#ifndef _PSILIB_API_H
#define _PSILIB_API_H
 
// include dependency headers
 
/********************************************
 *                  MACROS                  *
 ********************************************/
#include "kal_general_types.h" 
#include "ps_public_enum_public.h" 
#include "kal_public_defs.h"
 
/********************************************
 *         TYPE DEFINITIONS & ENUMS         *
 ********************************************/
#define PSILIB_NULL_PSI L4_PS_NULL_PSI
#define PSILIB_INVALID_CID L4_PS_NULL_CID
#define PSILIB_INVALID_APN_IDX -1
#define PSILIB_INVALID_APN_NAME "#do_not_care"

typedef enum {
    PSILIB_PSI_OP_RELEASE,
    PSILIB_PSI_OP_OCCUPY,
    PSILIB_PSI_OP_QUERY,
    PSILIB_PSI_OP_INJECT,
    PSILIB_PSI_OP_REQUIRE,
    PSILIB_PSI_OP_UT = 254,
    PSILIB_PSI_OP_MAX,
} psilib_op_enum;

/********************************************
 *                VARIABLES                 *
 ********************************************/
 
// only extern variables are allowed in header
 
/********************************************
 *           FUNCTION DECLARATIONS          *
 ********************************************/

/**
 * @brief Initialize the PSILIB (to be called by module_init()) 
 * @param[in] null
 * @return 
 *  - KAL_TRUE, always 
 */
kal_bool psilib_init(void);

/**
 * @brief Allocate a psi with the specified apn name, apn_idx and cid
 * @param[in] apn name (to be associated with psi)
 * @param[in] apn index(to be associated with psi)
 * @param[in] cid (to be associated with psi)
 * @return
 *  - KAL_TRUE if successful; 
 *  - KAL_FALSE if failed (ex. all psi are occupied by other cids; the specified cid is used to alloc too many times) 
 */
kal_bool psilib_alloc_psi_by_apn_idx_cid(kal_uint8 sim_interface, kal_char *apn_name,
    kal_int8 apn_idx, kal_uint8 cid);

/**
 * @brief Module IP occupies a psi with the specified apn name, apn_idx and cid. It usually used by EPSI_REQ of ILM
 * @param[in] apn name (to be associated with psi)
 * @param[in] apn index(to be associated with psi)
 * @param[in] module type(to record occupier of associated psi)
 * @return
 *  - KAL_TRUE if successful; 
 *  - KAL_FALSE if failed (ex. all psi are occupied by other cids; the specified cid is used to alloc too many times) 
 */
kal_bool psilib_alloc_psi_by_apn_idx(kal_uint8 sim_interface, kal_char *apn_name,
        kal_int8 apn_idx, module_type mod_id);

/**
 * @brief Allocate a psi with the specified cid 
 * @param[in] cid (to be assoicated with psi) 
 * @return 
 *  - KAL_TRUE if successful; 
 *  - KAL_FALSE if failed (ex. all psi are occupied by other cids; the specified cid is used to alloc too many times) 
 */
kal_bool psilib_alloc_psi_by_cid(kal_uint8 sim_interface, kal_uint8 cid);

/**
 * @brief Allocate a psi with the specified psi, apn name and apn_idx
 * @param[in] apn name (to be associated with psi)
 * @param[in] apn index(to be associated with psi)
 * @param[in] psi (a used/existing psi)
 * @param[in] module type(to record occupier of associated psi)
 * @return
 *  - KAL_TRUE if successful; 
 *  - KAL_FALSE if failed (ex. all psi are occupied by other cids; the specified cid is used to alloc too many times) 
 */
kal_bool psilib_require_psi_by_psi_apn_idx(kal_uint8 sim_interface, kal_char *apn_name,
    kal_int8 apn_idx, kal_int8 psi, module_type mod_id);

/**
 * @brief Query the associated psi for the specified cid 
 * @param[in] cid (to know its associated psi)
 * @return 
 *  - [psi_val] if successful; 
 *  - PSILIB_NULL_PSI if failed (ex. the specified cid does not allocate with any psi) 
 */
kal_uint8 psilib_query_psi_by_cid(kal_uint8 sim_interface, kal_uint8 cid);

/**
 * @brief Query the associated psi for the specified apn name and apn index
 * @param[in] apn_name (to know its associated psi)
 * @param[in] apn_idx (to know its associated psi)
 * @param[in] mod_id (to know its occupied psi)
 * @return 
 *  - [psi_val] if successful;
 *  - PSILIB_NULL_PSI if failed (ex. It did not allocate any psi with specified apn name and apn index)
 */
kal_uint8 psilib_query_psi_by_apn_idx(kal_uint8 sim_interface, kal_char *apn_name, kal_int8 apn_idx, module_type mod_id);

/**
 * @brief De-allocate psi with the specified cid 
 * @param[in] cid (it would be de-associated with the psi) 
 * @return 
 *  - KAL_TRUE if successful; 
 *  - KAL_FALSE if failed (ex. the specified cid is not associated with psi before calling dealloc) 
 */
kal_bool psilib_dealloc_psi_by_cid(kal_uint8 sim_interface, kal_uint8 cid);

/**
 * @brief Release psi which occupied by someone module
 * @param[in] psi (to release specified psi)
 * @param[in] mod_id (the module wants to release psi (Occupier))
 * @return
 *  - KAL_TRUE if successful;
 *  - KAL_FALSE if failed (ex. the specified psi's ref_count is already 0)
 */
kal_bool psilib_release_psi_by_psi(kal_uint8 sim_interface, kal_uint8 psi, module_type mod_id);

/**
 * @brief De-allocate psi with the specified apn name and apn index
 * @param[in] apn_name (it would de-associated with psi)
 * @param[in] apn_idx (it would de-associated with psi)
 * @param[in] mod_id (the module wants to release psi (Occupier))
 * @return
 *  - KAL_TRUE if successful;
 *  - KAL_FALSE if failed (ex. the specified apn name and apn index were not associated with psi before calling dealloc)
 */
kal_bool psilib_dealloc_psi_by_apn_idx(kal_uint8 sim_interface, kal_char *apn_name, kal_int8 apn_idx, module_type mod_id);

/**
 * @brief Update apn and apn index to associated psi with the specified cid
 * @param[in] cid (to know its associated psi)
 * @param[in] apn_name (to update apn of associated psi)
 * @param[in] apn_idx (to update apn_idx of associated psi)
 * @return
 *  - KAL_TRUE if successful;
 *  - KAL_FALSE if failed (ex. can not find psi according to cid)
 */
kal_bool psilib_update_apn_idx_by_cid(kal_uint8 sim_interface, kal_uint8 cid, kal_char *apn_name, kal_int8 apn_idx);

/**
 * @brief Inject PSI value for testing purpose
 * @param[in] PSI
 * @return 
 */
void psilib_inject_psi(kal_uint8 sim_interface, kal_uint8 psi);

#ifndef __MTK_TARGET__
/**
 * @brief Unit test of psilib
 * @return
 */
void psilib_ut_handler(void);

/**
 * @brief Reset the PSILIB (to be called by module_reset()) 
 * @param[in] null
 * @return 
 *  - KAL_TRUE, always
 */
kal_bool psilib_reset(void);
#endif // #ifndef __MTK_TARGET__ 
  
#endif /* _PSILIB_API_H */