mcu/protocol/interface/el2/emac_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) 2012
*
*  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).
*
*****************************************************************************/

/*******************************************************************************
 * Filename:
 * ---------
 *   emac_api.h
 *
 * Project:
 * --------
 *   UMOLY
 *
 * Description:
 * ------------
 *
 *
 * Author:
 * -------
 *  
 *
 *
 * ==========================================================================
 * $Log$
 *
 * 05 25 2018 jia-shi.lin
 * [MOLY00328472] [EIGER][MT3967][RDIT][FT][CT][Overnight][Auto][CAT][SH][SIM1:CT][SIM2:CU]md1:(MCU_core1.vpe0.tc0(VPE2)) [ASSERT] file:mcu/protocol/el2/ert/emac/src/emac_ert.c line:1383
 * 1. rename emac_txhisr_proc as emac_tti_done_proc
 * 2. emac_tti_done_proc move to txlisr for 95
 *
 * 01 11 2018 jia-shi.lin
 * [MOLY00301451] [SMO release][93/95]EL1 relative interface
 * emac/el1 interface re-arch
 *
 * 07 12 2017 jia-shi.lin
 * [MOLY00263796] [Gen93] EL1C always ticks PCSI during DRX off period which locks sleep mode
 * add emac api emac_slp_cqi_srs_predict_result_rxlisr
 *
 * 07 11 2017 jia-shi.lin
 * [MOLY00263426] [Bianco][N1][SRLTE][CT 6M C][LTE IOT][FT][CD][HW][TC-SMFT-07005]EE md1:(MCU_core0.vpe1.tc1(VPE1)) [ASSERT] file:mcu/pcore/modem/el2/common/el2_utility.c line:509
 * relax the 1ms timing protection for ert sf proc
 *
 * 06 22 2017 nicole.hsu
 * [MOLY00259119] [MT6763][EL2] EMAC/EL2EM/EL2POW maintenance
 * [TRUNK] potential bug fix, RSIM EM, AT&T EM
 *
 * 06 09 2017 jia-shi.lin
 * [MOLY00254140] [MT6293][EL1C] Reduce processing in RRC idle
 * check in emac_txlisr_mt_chk_stage3()
 *
 * 06 09 2017 mf.jhang
 * [MOLY00254140] [MT6293][EL1C] Reduce processing in RRC idle
 * .Provide is emac_txlisr_active for EL1
 *
 * 05 19 2017 jia-shi.lin
 * [MOLY00249306] [SE2 Internal Test][MT6293][UMOLYA][ATE][20170512][1][core0,vpe1,tc2(vpe1)] Assert fail emac_drx.c 811 - (LISR)EL1_C_TX
 * 1. drx bug fix
 * 2. mid ind to ert
 * 3. dl wo pdsch ind
 *
 * 05 19 2017 nicole.hsu
 * [MOLY00250929] [Copy CR][BIANCO][MT6763][RDIT][PHONE][Overnight][HQ][MTBF][Lab][Ericsson][ASSERT] file:mcu/l1core/modem/el1/el1c/phs/src/el1_phs_msg.c line:2429
 * SCell new interface/design
 *
 * 04 18 2017 mf.jhang
 * [MOLY00241929] [BIANCO][MT6763][RDIT][4GPS][RTD][HEAT][LTE_04_13_02_R12_UL64QUAM_2_UL64QAMonBothCCs_Type0]Assert fail: el1_meas_ctrl.c 11916 - EL1_MPC
 * . Add EL1C command queue
 *
 * 04 05 2017 jia-shi.lin
 * [MOLY00237731] [MT6293][L+L] Feature development
 * [EMAC] Update EL1TX EMAC interface (EMAC part).
 *
 * 03 02 2017 jia-shi.lin
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * remove emac_force_phy_config_sch_close
 *
 * 01 19 2017 mf.jhang
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * Split emac txlisr process into 3 stages for load balance
 *
 * 12 21 2016 nicole.hsu
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * [Seamless Meta Mode] EMAC part
 * - provide dummy API to be called in Meta Mode
 * - provide force sch_close API to be called before leaving Meta Mode
 *
 * 10 18 2016 jia-shi.lin
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * add one phich result type
 *
 * 10 05 2016 mf.jhang
 * [MOLY00206476] [MT6293][NWSIM][Regression][TC_7_1_4_16] Failed at step 6
 * add emac_ta_stag_ta_diff_exceeded
 *
 * 10 03 2016 nicole.hsu
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * 1. RAR grant size check and handling
 * 2. fix PHR api for ra group selection
 *
 * 08 11 2016 yu-chun.chen
 * [MOLY00176078] [EL1C] UMOLYA code sync
 * Back out changelist 2711251
 *
 * 08 11 2016 nicole.hsu
 * [MOLY00194987] [MT6293][UMOLYA/PS DEV] EMAC maintenance
 * 1. fix sim api warning
 * 2. fix sim api prototype
 * 3. provide rar_acsi_trigger assert function for el1tx
 *
 * 08 10 2016 shang-lun.chiu
 * [MOLY00196539] [MT6293][EL1TX] Update comments to generate doxygen document
 *
 * 08 02 2016 wen-jiunn.liu
 * [MOLY00194298] [UMOLYA] EL2 + EMAC Code Review
 * Revise EL1-EMAC Interface
 * 	- CRC Handler
 * 	- DL Assignment
 *
 * 08 02 2016 nicole.hsu
 * [MOLY00194987] [MT6293][PS DEV] EMAC maintenance
 * [EMAC] ra api fix
 *
 * 08 01 2016 jeremy.chen
 * [MOLY00190683] [UMOLYA][6293] EL2 merge back to UMOLYA TRUNK & PS DEV
 * 	
 * 	[EL2][RD domain] Sync EL2 interface from Aric CBr
 *
 ****************************************************************************/
/**
 *  @file   emac_api.h
 *  @brief  EMAC Exported APIs to Other Libraries
 *
 *  @author 
 *  @date   2016/2/22
 *
 **/
 
#ifndef __EMAC_API_H__
#define __EMAC_API_H__

#include "kal_public_api.h"
#include "lte_time_common.h"
#include "abs_time.h"
#include "el1_emac_str.h"

// =========================================
// TTI Execution Process
// =========================================

/***************************************//**
 * @brief       Initialize the EMAC context before each TTI process
 * @note        Get air time from global variables / reset EMAC TTI related context
 * @param       protocol_idx
 * @return      (void)
 ******************************************/
void
emac_txlisr_init_tti_proc(kal_uint32 protocol_idx);

void
emac_txlisr_proc_stage1();

/***************************************//**
 * @brief       Main process for EMAC \n
 *              E.g., SCELL / TA / DL HARQ / UL HARQ / BSR / SR / RA / DRX
 * @note        Execution after all handler inputs are ready
 * @param[in]   p_sf_input      Tx subframe parameter for EMAC, including information of
 *                              - gap 
 *                              - subframe type
 *                              .
 * @return      (void)
 ******************************************/
void
emac_txlisr_proc_stage2(
    emac_el1tx_tti_input_t* p_sf_input
);

void
emac_txlisr_proc_stage3();

kal_bool
emac_txlisr_mt_chk_stage3();

/***************************************//**
 * @brief       Invoke this function \@ g_abs_time to check if any 
 *              EMAC handled TX requirement for tx_abs_time (g_abs_time +2)
 * @note        Called by EL1TX to query EMAC if there is any tx requirement \n
 *              One TXLISR / one TX requirement invoked (1-to-1 mapping) \n
 *              EL1 could NOT modify tx_bmp in the pointer
 * @param       (void)
 * @return      emac_el1tx_tx_req_struct*   Pointer to TX request of this TTI 
 *                                          in EMAC context \n
 *                                          The returned EMAC context will be cleared 
 *                                          \@ emac_txlisr_init_tti_proc()
 ******************************************/
emac_el1tx_tx_req_struct*
emac_txlisr_get_tx_req();

/***************************************//**
 * @brief       Post process for EMAC \n
 *              E.g., MUX Decision / Clear UL HARQ Context / Clear TX Timeline / ...
 * @note        Execution after all handler inputs are ready
 * @param[in]   tx_results      Bitmap of emac_el1tx_tx_bitmap_e
 * @return      (void)
 ******************************************/
void
emac_txlisr_post_proc(
    kal_uint32 tx_results                   
);

/***************************************//**
 * @brief       EMAC process in TXHISR for 93 (e.g., send ERT polling ILM)
 *              EMAC process in TXLISR for 95 (e.g., send ERT polling ILM)
 * @note        Called only in TXHISR for 93, called only in TXLISR for 95
 * @param       (void)
 * @return      (void)
 ******************************************/
void
emac_tti_done_proc();

// =========================================
// TTI Input Handler Related APIs
// =========================================

/***************************************//**
 * @brief       Report n-2 or n-1 (i.e., g_abs_time -2 or -1) DCI result for DL HARQ \n
 *              Support only 
 *              - C-RNTI
 *              - TC-RNTI
 *              - RA-RNTI
 *              - SPS-CRNTI (Act/Retx/Rel)
 *              .
 * @note        This function is used to update EMAC DL HARQ status \n
 *              DL unsolicited is NOT included (EMAC will calculate DL SPS) \n
 *              Indicate TB "new transmission" or not (instead of raw NDI value)
 * @param[in]   rcv_abs_time    g_abs_time -1 or -2
 * @param[in]   p_pdcch_dl_info DL information carried in PDCCH
 * @return      (void)
 ******************************************/
void
emac_pdcch_dl_assign_handler(
    ABS_TICK_TIME rcv_abs_time,
    el1tx_pdcch_dl_info_struct* p_pdcch_dl_info
);

/***************************************//**
 * @brief       Report n-2 or n-1 (i.e., g_abs_time -2 or -1) DCI result for UL HARQ \n
 *              Support only 
 *              - C-RNTI
 *              - TC-RNTI
 *              - RA-RNTI
 *              - SPS-CRNTI (Act/Retx/Rel)
 *              .
 * @note        This function is used to update EMAC UL HARQ status \n
 *              UL unsolicited is NOT included (EMAC will calculate UL SPS)
 * @param[in]   ul_cc_idx       UL CC index
 * @param[in]   rcv_abs_time    g_abs_time -1 or -2
 * @param[in]   p_pdcch_ul_info UL information carried in PDCCH
 * @return      (void)
 ******************************************/
void
emac_pdcch_ul_info_handler(
    kal_uint8 ul_cc_idx,
    ABS_TICK_TIME rcv_abs_time,
    el1tx_pdcch_ul_info_struct* p_pdcch_ul_info
);

/***************************************//**
 * @brief       Report n-2 or n-1 (i.e., g_abs_time -2 or -1) PHICH result for UL HARQ
 * @note        This function is used to update EMAC UL HARQ status
 * @param[in]   ul_cc_idx       UL CC index
 * @param[in]   harq_id         HARQ ID
 * @param[in]   el1tx_phich_rlt_enum    PHICH result
 * @return      (void)
 ******************************************/
void
emac_pdcch_set_phich_result_handler(
    kal_uint8 ul_cc_idx,
    ABS_TICK_TIME rcv_abs_time,
    kal_uint8 harq_id,
    el1tx_phich_rlt_enum phich_result
);

/***************************************//**
 * @brief       - [TBC] Report n-3 or n-2 (i.e., g_abs_time -3 or -2)
 *                      with each TB CRC decoding result
 *              - [TBC] Invoked after DL Assignment Handler\n
 *                      With assumption of ignorance DCI for same TB within 4 subframes
 *              - [TBC] DCI v.s. CRC report is 1-to-1 mapping
 *              - Report only
 *              -- C-RNTI
 *              -- TC-RNTI
 *              -- SPS-CRNTI (Act/Retx/Config)
 *               .
 *              .
 * @note        TB information is with bitwise operation (BIT0 for TB0 : BIT1 for TB1)
 * @param[in]   p_crc_result    CRC result information
 * @return      (void)
 ******************************************/
void
emac_pdcch_set_crc_result_handler(
    el1tx_pdcch_crc_result_struct* p_crc_result
);

/***************************************//**
 * @brief       Report n-2 or n-1 (i.e., g_abs_time -2 or -1) PDCCH order for RA
 * @note        If PDCCH order is received, call function to trigger PDCCH order RA process 
 * @param[in]   rcv_abs_time    g_abs_time -1 or -2
 * @param[in]   ul_cc_idx       UL CC index
 * @param[in]   rapid           RA preamble ID
 * @param[in]   mask            RA mask index
 * @return      (void)
 ******************************************/
void 
emac_ra_pdcch_order_rcv(
    ABS_TICK_TIME rcv_time, 
    kal_uint8 ul_cc_idx, 
    kal_uint8 rapid, 
    kal_uint8 mask
);


// =========================================
// SPS Related APIs
// =========================================

/***************************************//**
 * @brief       Get UL SPS Active State in EMAC context
 * @note        This function is used to check current UL SPS state in 
 *              EMAC context \@ TXLISR \n
 *              May be called in different threads, not TXLISR \n
 *              Caller should take care of multi-thread effects 
 * @param       (void)
 * @return      KAL_TRUE:   UL SPS is active \n
 *              KAL_FALSE:  UL SPS is not active
 ******************************************/
kal_bool
emac_sps_ul_get_active_state();


// =========================================
// UL HARQ Related APIs
// =========================================

/***************************************//**
 * @brief       Check if any UL HARQ for an UL CC is on-going
 * @note        This function is used to check PUSCH UL HARQ status \n
 *              Caller should take care of multi-thread effects \n
 * @param[in]   ul_cc_idx       UL CC index
 * @return      KAL_TRUE:       one or more UL HARQ are on-going \n
 *              KAL_FALSE:      no UL HARQ is on-going 
 ******************************************/
kal_bool
emac_ul_harq_is_any_on_going(kal_uint8 ul_cc_idx);

/***************************************//**
 * @brief       Predict if the grant is applied for TX based on 
 *              the current UL HARQ view (Best Effort)
 * @note        This function is used to predict if the grant can be applied for TX 
 *              based on the current EMAC UL HARQ view (Best Effort) \n
 *              Caller should take care of multi-thread effects \n
 *              May be called in TXLISR and RXLISR,
 *              EL1 should guarantees no simultaneous execution (no lock needed) for
 *              the same tx_abs_time
 * @param[in]   ul_cc_idx       UL CC index
 * @param[in]   p_predict_req   Grant to be predicted
 * @return      KAL_TRUE:       grant is predicted as applied for TX in the 
 *                              current EMAC UL HARQ view \n
 *              KAL_FALSE:      grant is predicted as NOT applied for TX in the
 *                              current EMAC UL HARQ view
 ******************************************/
kal_bool
emac_ul_harq_predict_grant_apply(
    kal_uint8 ul_cc_idx,
    el1tx_grant_apply_predict_req_struct* p_predict_req
);

/***************************************//**
 * @brief       emac_el1_txtimeline_extension_t should be defined by EL1 \n
 *              Return the EL1 extension memory (e.g., for implementing CQI only)
 * @note        Caller should take care of multi-thread effects \n
 *              EL1 extension will be cleared when TX timeline entry is cleared
 *              (\@ EMAC TXLISR post process) 
 * @param[in]   ul_cc_idx       UL CC index
 * @param[in]   tx_abs_time     The time to refer to the timeline enrty
 * @return      Start address of EL1 extension
 ******************************************/
emac_el1_txtimeline_extension_t*
emac_ul_harq_get_timeline_el1_extension(
    kal_uint8 ul_cc_idx,
    ABS_TICK_TIME tx_abs_time
);


// =========================================
// DRX Related APIs
// =========================================

/***************************************//**
 * @brief       When EL1TX has a periodic CQI transmission on PUCCH, 
 *              EL1TX needs to 
 *              call this function no later than <b>cqi_tx_time - 5</b>
 *              (EL1TX does NOT support now). 
 *              The reason is that EMAC needs to calculate the admission for
 *              this CQI TX
 * @note        Caller should take care of multi-thread effects \n
 *              Currently, EL1TX need not call this API since EMAC will 
 *              calculate the admission for CQI TX for every TTI \n
 *              When EL1TX can support the call of this function no later
 *              than <b>cqi_tx_time -5</b>, EMAC will only calculate the admission  
 *              for CQI TX in <b>cqi_tx_time</b> to save the MIPS
 * @param[in]   cqi_tx_time     CQI TX time
 * @return      (void)
 ******************************************/
void emac_drx_set_cqi_tx_time(ABS_TICK_TIME cqi_tx_time); 

/***************************************//**
 * @brief       When EL1TX has a type0 SRS transmission, EL1TX needs to
 *              call this function no later than <b>type0_srs_tx_time - 5</b>.  
 *              The reason is that EMAC needs to calculate the admission for this SRS TX
 * @note        Caller should take care of multi-thread effects \n
 *              Currently, EL1TX need not call this API since EMAC will 
 *              calculate the admission for type0 SRS TX for every TTI \n
 *              When EL1TX can support the call of this function no later
 *              than <b>type0_srs_tx_time -5</b>, EMAC will only calculate the admission  
 *              for type0 SRS TX in <b>type0_srs_tx_time</b> to save the MIPS
 * @param[in]   type0_srs_tx_time   type0 SRS TX time
 * @return      (void)
 ******************************************/
void emac_drx_set_type0_srs_tx_time(ABS_TICK_TIME type0_srs_tx_time); 

/***************************************//**
 * @brief       EMAC will return the TX admission of cqi and type0 srs
 *              for tx_abs_time
 * @note        emac_drx_set_cqi_tx_time or emac_drx_set_type0_srs_tx_time should be called
 *              before emac_drx_cqi_srs_admin is called \n
 *              Caller should take care of multi-thread effects \n
 *              The timing for calling this API is expected to be after the EMAC TTI
 *              process of <b>tx_abs_time -2</b>
 * @param[in]   tx_abs_time             periodic CQI and type0 SRS time
 * @param[out]  p_cqi_srs_admin_info    admission information of periodic CQI and type0 SRS
 * @return      (void)
 ******************************************/
void emac_drx_cqi_srs_admin(ABS_TICK_TIME tx_abs_time, 
   emac_el1tx_drx_cqi_srs_admin_info_struct * p_cqi_srs_admin_info); 


/***************************************//**
 * @brief       DL without PDSCH occurs
 * @note        when DL without PDSCH occurs, call this api
 * @param[in]   rcv_abs_time             the rcv_abs_time for this DL
 * @return      (void)
 ******************************************/
void emac_drx_dl_wo_pdsch_handler(ABS_TICK_TIME rcv_abs_time);



// =========================================
// SLEEP Related APIs
// =========================================

kal_bool emac_slp_is_prev1_dci_info_required(void);
kal_bool emac_slp_cqi_srs_predict_result_rxlisr(ABS_TICK_TIME tx_abs_time);

// =========================================
// RA Related APIs
// =========================================

kal_bool emac_ra_is_rar_grant_valid(el1tx_pdcch_ul_info_struct* p_grant);
void emac_ra_set_max_txpower_reached();
void emac_ra_rar_acsi_trigger_fail();
void emac_ra_tcrnti_ack_add_fail();
void emac_ra_set_last_prach_tx_power(kal_uint16 prach_tx_power);

// =========================================
// PHR Related APIs
// =========================================

kal_bool emac_el1_phr_res_handler(emac_el1tx_phr_res_struct phr_content);

// =========================================
// TA Related APIs
// =========================================
void emac_ta_stag_ta_diff_exceeded(kal_uint32 stag_id);

// =========================================
// SCELL Related APIs
// =========================================
void emac_scell_el1c_cnf();
void emac_scell_rel(kal_uint32 cc_idx);

kal_bool emac_txlisr_active(ABS_TICK_TIME cur_abs_time);
kal_bool emac_txlisr_tx_checksum_error_bypass_check(ABS_TICK_TIME tx_abs_time);

// =========================================
// META_MODE Related APIs
// =========================================
void emac_dummy_txlisr_init_tti_proc(kal_uint32 protocol_idx);
void emac_dummy_txlisr_post_proc(kal_uint32 tx_results);
void emac_dummy_txlisr_proc(emac_el1tx_tti_input_t* p_sf_input);
void emac_dummy_tti_done_proc();
void emac_dummy_txlisr_proc_stage1();
void emac_dummy_txlisr_proc_stage3();


#endif