/* 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_iom.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains IO Manager related definitions, which
 *         are exported to applications.
 */
/*----------------------------------------------------------------------------*/

#ifndef _C_IOM_H_
#define _C_IOM_H_

/*-----------------------------------------------------------------------------
                    include files
 ----------------------------------------------------------------------------*/
#include "u_iom.h"
#include "u_handle.h"

/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_IO_MNGR
 *  @{ 
 */
/*----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------
                    functions declarations
 ----------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief This API opens a device whose attribute can be input, output,  or both. 
  *              An application is allowed to do multiple opens to a   device simultaneously.
 *
 *  @param [in] e_dev_type  - The device type.
 *  @param [in] ui2_id          - The device id.
 *  @param [in] ps_name      - The device name.
 *  @param [in] pv_setting    - The setting to the device if required.
 *  @param [in] pv_tag         - Private tag value which must be returned in the  notify
 *                                          function. It can be set to NULL.
 *  @param [in] pf_nfy          - References the caller's notify function.
 *
 *  @param [out] ph_dev       - A handle referencing the opened device.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK            - Routine successful.
 *  @retval  IOMR_NOT_INIT  - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG   - One or more of the arguments contain  invalid data. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_open(IOM_DEV_TYPE_T e_dev_type,
                        UINT16         ui2_id,
                        const CHAR*    ps_name,
                        VOID*          pv_setting,
                        VOID*          pv_tag,
                        x_iom_nfy_fct  pf_nfy,
                        HANDLE_T*      ph_dev);

/*------------------------------------------------------------------*/
/*! @brief  This API closes an opened device referenced by h_dev.
 *
 *  @param [in]  h_dev  - A handle referencing the device.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK                 -  Routine successful.
 *  @retval  IOMR_NOT_INIT       - The IO Manager is not initialized.
 *  @retval  IOMR_INV_HANDLE  - The handle is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_close(HANDLE_T h_dev);

/*------------------------------------------------------------------*/
/*! @brief  This API gets some info from a device referenced by h_dev.
 *
 *  @param [in]  h_dev              - A handle referencing the device.
 *  @param [in]  e_get_type       - Specifies the type of information which shall
 *                                                be returned in the buffer, referenced by
 *                                                argument pv_get_info.
 *  @param [in] pz_get_info_len  - Contains the length of the buffer which is
 *                                                 referenced by argument pv_get_info.
 *
 *
 *  @param [out] pv_get_info    - Contains the retrieved information.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK                -  Routine successful.
 *  @retval  IOMR_NOT_INIT      - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG       - One or more of the arguments contain  invalid data.
 *  @retval  IOMR_INV_HANDLE  - The handle is invalid. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_get(HANDLE_T  h_dev,
                       IOM_GET_T e_get_type,
                       VOID*     pv_get_info,
                       SIZE_T*   pz_get_info_len);

/*------------------------------------------------------------------*/
/*! @brief This API sets some info to a device referenced by h_dev.
 *
 *  @param [in] h_dev             - A handle referencing the device.
 *  @param [in] e_set_type      - Specifies the type of information which is referenced
 *                                             by argument pv_set_info.
 *  @param [in]  pv_set_info     - Contains the set information.
 *  @param [in] z_set_info_len  - Indicates the length of the data in the buffer
 *                                               referenced by argument pv_set_info.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK                - Routine successful.
 *  @retval  IOMR_NOT_INIT      - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG       - One or more of the arguments contain invalid data.
 *  @retval  IOMR_INV_HANDLE  - The handle is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_set(HANDLE_T    h_dev,
                       IOM_SET_T   e_set_type,
                       const VOID* pv_set_info,
                       SIZE_T      z_set_info_len);

/*------------------------------------------------------------------*/
/*! @brief  This API sends an event to an output or IO driver.
 *
 *  @param [in]  h_dev         - A handle referencing the device.
 *  @param [in] pv_otp_info  - The output event information.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK               -  Routine successful.
 *  @retval  IOMR_NOT_INIT     - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG      - One or more of the arguments contain  invalid data.
 *  @retval  IOMR_DEV_BUSY    - Device is busy.
 *  @retval  IOMR_INV_HANDLE - The handle is invalid.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_output(HANDLE_T h_dev,
                          VOID*    pv_otp_info);

/*------------------------------------------------------------------*/
/*! @brief This API is called in order to generate a pair of button-down
 *              and button-up events.
 *
 *  @param [in] ui4_evt_code  - Contains the event code.
 *  @param [in] ui4_itvl           - Contains the interval between button-down and
 *                                             button-up events in ms.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK             - Routine successful.
 *  @retval IOMR_MSGQ_FULL - Message Queue is full.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_send_evt(UINT32 ui4_evt_code,
                            UINT32 ui4_itvl);

/*------------------------------------------------------------------*/
/*! @brief This API is called to generate either a button-down or a  button-up event.
 *
 *  @param [in] ui4_evt_code  - Contains the event code.
 *  @param [in] b_btn_down    - Contains the interval between button-down and 
 *                                              button-up events in ms.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK               - Routine successful.
 *  @retval  IOMR_NOT_INIT     - The IO Manager is not initialized. 
 *  @retval  IOMR_MSGQ_FULL  - Message Queue is full.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_send_evt_single(UINT32 ui4_evt_code,
                                   BOOL   b_btn_down);
                                   
/*------------------------------------------------------------------*/
/*! @brief This API sends a raw data event to IO Manager.
 *
 *  @param [in] ui4_raw_data  - Contains the raw data.
 *  @param [in] ui4_itvl           - Contains the interval between button-down and 
 *                                              button-up events in ms.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK               - Routine successful.
 *  @retval  IOMR_NOT_INIT     - The IO Manager is not initialized. 
 *  @retval  IOMR_MSGQ_FULL  - Message Queue is full.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_send_raw_data(UINT32 ui4_raw_data,
                                 UINT32 ui4_itvl);
                          
/*------------------------------------------------------------------*/
/*! @brief This API converted IRRC raw data to an event code.
 *
 *  @param [in] h_dev       - A handle referencing the device.
 *  @param [in] pt_data     - Contains the raw date to be converted.
 *
 *  @param [out] pt_data   - Contains the event code after conversion.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK                       - Routine successful.
 *  @retval  IOMR_NOT_INIT             - The IO Manager is not initialized. 
 *  @retval  IOMR_INV_HANDLE        - The handle is invalid.
 *  @retval  IOMR_DEV_SET_FAILED - Device get operation is failed. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_convert_raw_data_to_evt_code(HANDLE_T                    h_dev,
                                                IOM_RAW_DATA_TO_EVT_CODE_T* pt_data);

/*------------------------------------------------------------------*/
/*! @brief This API converted IRRC raw bits to an event code.
 *
 *  @param [in]  h_dev     - A handle referencing the device.
 *  @param [in]  pt_data   - Contains the raw bits to be converted.
 *
 *  @param [out] pt_data  - Contains the event code after conversion.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval IOMR_OK                        - Routine successful.
 *  @retval IOMR_NOT_INIT              - The IO Manager is not initialized. 
 *  @retval IOMR_INV_HANDLE         - The handle is invalid.
 *  @retval IOMR_DEV_SET_FAILED  - Device get operation is failed. 
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_convert_raw_bits_to_evt_code(HANDLE_T                    h_dev,
                                                IOM_RAW_BITS_TO_EVT_CODE_T* pt_data);
                                                
#if !IOM_REMOVE_APDEMON_IRRC                     
/*------------------------------------------------------------------*/
/*! @brief  This API is called by Apdemon in response to received IRRC
 *               events from ATV Manager.
 *
 *  @param [in] ui4_evt_code  - The event code.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval  IOMR_OK           -  Routine successful.
 *  @retval  IOMR_NOT_INIT - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG  - One or more of the arguments contain invalid data.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_apdemon_send_evt(UINT32 ui4_evt_code);
#endif

/*------------------------------------------------------------------*/
/*! @brief  This API configures the auto sleep timer that will trigger the
 *               system into standby mode if no IRRC key is received during 
 *               that period. Otherwise, the timer will be reset upon an IRRC
 *               key reception.
 *
 *  @param [in] ui4_sleep_time  - Contains auto sleep time in seconds.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the error code.
 *  @retval IOMR_OK                   - Routine successful.
 *  @retval IOMR_NOT_INIT         - The IO Manager is not initialized.
 *  @retval IOMR_INV_ARG          - One or more of the arguments contain invalid data.
 *  @retval IOMR_TIMER_ERROR   - A timer error occurred.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_set_auto_sleep_timer(UINT32 ui4_sleep_time);

/*------------------------------------------------------------------*/
/*! @brief  This API configures the auto sleep timer which will set the
 *               system into standby mode when none of IRRC key is received  
 *               during specific period of time. The timer will be restarted if 
 *               any IRRC key is received before expiration. Note auto sleep 
 *               timer contains two types, prompt and sleep timers.
 *
 *  @param [in] pt_auto_sleep_timer  - References the auto sleep timer data
 *                                                       structure.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return
 *  @retval  IOMR_OK                   -  Routine successful.
 *  @retval  IOMR_NOT_INIT         - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG          - One or more of the arguments contain  invalid data.
 *  @retval  IOMR_TIMER_ERROR  - A timer error occurred.
 */
/*------------------------------------------------------------------*/
extern INT32 c_iom_set_auto_sleep_timer_ex(AUTO_SLEEP_TIMER_T* pt_auto_sleep_timer);

#if IOM_SUPPORT_IRRC_DISABLE_KEYS
/*------------------------------------------------------------------*/
/*! @brief  This API set the disable event code info 
 *
 *  @param [in] pt_disable_evtcode  - References the disable event code info
 *
 *  @param [out]
 *
 *  @note
 *  @see
 *
 *  @return  Return the error code.
 *  @retval  IOMR_OK           -  Routine successful.
 *  @retval  IOMR_NOT_INIT  - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG   - One or more of the arguments contain invalid data.
 */
/*------------------------------------------------------------------*/
extern INT32   c_iom_set_global_disable_evtcode(DISABLE_EVTCODE_T* pt_disable_evtcode);
/*------------------------------------------------------------------*/
/*! @brief  This API get  the disable event code count
 *
 *  @param [in] None.
 *
 *  @param [out] None.
 *
 *  @note
 *  @see
 *
 *  @return Return the count of the global disable event code.
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern UINT32  c_iom_get_global_disable_evtcode_cnt(VOID);
/*------------------------------------------------------------------*/
/*! @brief  This API get  the disable event code information.
 *
 *  @param [in] None.
 *
 *  @param [out] pt_disable_evtcode  - References the disable event code info,Please note 
 *                                                       the z_evtcode_cnt must be gotten by 
 *                                                       c_iom_get_global_disable_evtcode_cnt
 *
 *  @note
 *  @see
 *
 *  @return  Return the error code.
 *  @retval  IOMR_OK            - Routine successful.
 *  @retval  IOMR_NOT_INIT  - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG   - One or more of the arguments contain  invalid data.
 */
/*------------------------------------------------------------------*/
extern INT32   c_iom_get_global_disable_evtcode(DISABLE_EVTCODE_T* pt_disable_evtcode);
#endif


/*------------------------------------------------------------------*/
/*! @brief  This API sets the custom key repeat interval configuration.
 *  @param [in] ui4_interval_unit  - Unit of first/other interval in pt_setting
 *                                   in milliseconds. Should be multiple of 10.
 *  @param [in] ui4_custom_key_num - Number of custom key settings in pt_setting
 *  @param [in] pt_setting         - Array of custom key settings. Each item
 *                                   contains (event code, first interval units,
 *                                   other interval units).
 *  @return  Return the error code.
 *  @retval  IOMR_OK            - Routine successful.
 *  @retval  IOMR_NOT_INIT  - The IO Manager is not initialized.
 *  @retval  IOMR_INV_ARG   - One or more of the arguments contain  invalid data.
 */
/*------------------------------------------------------------------*/
extern INT32   c_iom_set_custom_key_repeat_interval(
        UINT32                          ui4_interval_unit,
        UINT32                          ui4_custom_key_num,
        IOM_CUST_KEY_REP_ITVL_ITEM_T*   pt_setting);


#endif /* _C_IOM_H_ */
/*----------------------------------------------------------------------------*/
/*! @} */                                           /* end of groupMW_IO_MNGR */
/*----------------------------------------------------------------------------*/
