xref: /utopia/UTPA2-700.0.x/mxlib/include/drvRTC.h (revision 53ee8cc121a030b8d368113ac3e966b4705770ef)

//<MStar Software>
//******************************************************************************
// MStar Software
// Copyright (c) 2010 - 2012 MStar Semiconductor, Inc. All rights reserved.
// All software, firmware and related documentation herein ("MStar Software") are
// intellectual property of MStar Semiconductor, Inc. ("MStar") and protected by
// law, including, but not limited to, copyright law and international treaties.
// Any use, modification, reproduction, retransmission, or republication of all
// or part of MStar Software is expressly prohibited, unless prior written
// permission has been granted by MStar.
//
// By accessing, browsing and/or using MStar Software, you acknowledge that you
// have read, understood, and agree, to be bound by below terms ("Terms") and to
// comply with all applicable laws and regulations:
//
// 1. MStar shall retain any and all right, ownership and interest to MStar
//    Software and any modification/derivatives thereof.
//    No right, ownership, or interest to MStar Software and any
//    modification/derivatives thereof is transferred to you under Terms.
//
// 2. You understand that MStar Software might include, incorporate or be
//    supplied together with third party`s software and the use of MStar
//    Software may require additional licenses from third parties.
//    Therefore, you hereby agree it is your sole responsibility to separately
//    obtain any and all third party right and license necessary for your use of
//    such third party`s software.
//
// 3. MStar Software and any modification/derivatives thereof shall be deemed as
//    MStar`s confidential information and you agree to keep MStar`s
//    confidential information in strictest confidence and not disclose to any
//    third party.
//
// 4. MStar Software is provided on an "AS IS" basis without warranties of any
//    kind. Any warranties are hereby expressly disclaimed by MStar, including
//    without limitation, any warranties of merchantability, non-infringement of
//    intellectual property rights, fitness for a particular purpose, error free
//    and in conformity with any international standard.  You agree to waive any
//    claim against MStar for any loss, damage, cost or expense that you may
//    incur related to your use of MStar Software.
//    In no event shall MStar be liable for any direct, indirect, incidental or
//    consequential damages, including without limitation, lost of profit or
//    revenues, lost or damage of data, and unauthorized system use.
//    You agree that this Section 4 shall still apply without being affected
//    even if MStar Software has been modified by MStar in accordance with your
//    request or instruction for your use, except otherwise agreed by both
//    parties in writing.
//
// 5. If requested, MStar may from time to time provide technical supports or
//    services in relation with MStar Software to you for your use of
//    MStar Software in conjunction with your or your customer`s product
//    ("Services").
//    You understand and agree that, except otherwise agreed by both parties in
//    writing, Services are provided on an "AS IS" basis and the warranty
//    disclaimer set forth in Section 4 above shall apply.
//
// 6. Nothing contained herein shall be construed as by implication, estoppels
//    or otherwise:
//    (a) conferring any license or right to use MStar name, trademark, service
//        mark, symbol or any other identification;
//    (b) obligating MStar or any of its affiliates to furnish any person,
//        including without limitation, you and your customers, any assistance
//        of any kind whatsoever, or any information; or
//    (c) conferring any license or right under any intellectual property right.
//
// 7. These terms shall be governed by and construed in accordance with the laws
//    of Taiwan, R.O.C., excluding its conflict of law rules.
//    Any and all dispute arising out hereof or related hereto shall be finally
//    settled by arbitration referred to the Chinese Arbitration Association,
//    Taipei in accordance with the ROC Arbitration Law and the Arbitration
//    Rules of the Association by three (3) arbitrators appointed in accordance
//    with the said Rules.
//    The place of arbitration shall be in Taipei, Taiwan and the language shall
//    be English.
//    The arbitration award shall be final and binding to both parties.
//
//******************************************************************************
//<MStar Software>
////////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2008-2009 MStar Semiconductor, Inc.
// All rights reserved.
//
// Unless otherwise stipulated in writing, any and all information contained
// herein regardless in any format shall remain the sole proprietary of
// MStar Semiconductor Inc. and be kept in strict confidence
// ("MStar Confidential Information") by the recipient.
// Any unauthorized act including without limitation unauthorized disclosure,
// copying, use, reproduction, sale, distribution, modification, disassembling,
// reverse engineering and compiling of the contents of MStar Confidential
// Information is unlawful and strictly prohibited. MStar hereby reserves the
// rights to any and all damages, losses, costs and expenses resulting therefrom.
//
////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////////////////////////
///
/// @file   drvRTC.h
/// @brief  Piu Watch Dog Timer Driver Interface
/// @author MStar Semiconductor Inc.
///////////////////////////////////////////////////////////////////////////////////////////////////

/*!
	\defgroup G_RTC RTC interface
    \ingroup  G_PERIPHERAL

	\brief
	A real-time clock (RTC) is a computer clock (most often in the form of an integrated circuit)
	that keeps track of the current time. Although the term often refers to the devices in personal computers,
	servers and embedded systems, RTCs are present in almost any electronic device which needs to keep accurate time.

	<b> Operation Flow </b>
	-# Initialize RTC
	-# Set RTC counter
	-# Get RTC counter
	-# Set RTC match counter
	-# Get RTC match counter
	-# Enable PM IRQ for the event to wake up
	-# Disable PM IRQ for the event to wake up

	<b> Architecture </b>
	\image html RTC.png


    \defgroup G_RTC_INIT Initialization Task relative
    \ingroup  G_RTC
    \defgroup G_RTC_COMMON Common Task relative
    \ingroup  G_RTC
    \defgroup G_RTC_CONTROL Control relative
    \ingroup  G_RTC
    \defgroup G_RTC_OTHER  other relative
    \ingroup  G_RTC
    \defgroup G_RTC_ToBeModified RTC api to be modified
    \ingroup  G_RTC
    \defgroup G_RTC_ToBeRemove RTC api to be removed
    \ingroup  G_RTC
*/

#ifndef _DRV_RTC_H_
#define _DRV_RTC_H_



#ifdef __cplusplus
extern "C"
{
#endif

#include "MsTypes.h"

////////////////////////////////////////////////////////////////////////////////
//  Type and Structure
////////////////////////////////////////////////////////////////////////////////
#define RTC_DRV_VERSION                 /* Character String for DRV/API version  */  \
    MSIF_TAG,                           /* 'MSIF'                                           */  \
    MSIF_CLASS,                         /* '00'                                              */  \
    MSIF_CUS,                           /* 0x0000                                         */  \
    MSIF_MOD,                           /* 0x0000                                         */  \
    MSIF_CHIP,                                                                                  \
    MSIF_CPU,                                                                                   \
    {'R','T','C',},                     /* IP__                                             */  \
    {'0','0'},                          /* 0.0 ~ Z.Z                                      */  \
    {'0','0'},                          /* 00 ~ 99                                         */  \
    {'0','0','0','0','0','0','0','0'},  /* CL#                                              */  \
    MSIF_OS

#define RTC_VERSION            0x00000001

typedef enum _RTC_DbgLv
{
    E_RTC_DBGLV_NONE,          /* no debug message */
    E_RTC_DBGLV_ERR_ONLY,      /* show error only */
    E_RTC_DBGLV_INFO,          /* show error & informaiton */
    E_RTC_DBGLV_ALL            /* show error, information & funciton name */
}RTC_DbgLv;


typedef enum
{
    E_MS_DRV_RTC_0,
    E_MS_DRV_RTC_2,
    E_MS_DRV_RTC_MAX,
}E_MS_DRV_RTC;

typedef enum
{
    E_MS_DRV_RTC_TIME_UNIT_SEC,
    E_MS_DRV_RTC_TIME_UNIT_MS,
    E_MS_DRV_RTC_TIME_UNIT_US,
}E_MS_DRV_RTC_TIME_UNIT;

typedef enum
{
    E_MS_DRV_RTC_STATUS_OK,
    E_MS_DRV_RTC_STATUS_NOT_INIT,
    E_MS_DRV_RTC_STATUS_IN_USE,
    E_MS_DRV_RTC_STATUS_INVALID_ARGUMENT,
}E_MS_DRV_RTC_STATUS;

E_MS_DRV_RTC_STATUS MDrv_RTC_ResetRTC(E_MS_DRV_RTC eRtc);
E_MS_DRV_RTC_STATUS MDrv_RTC_SetCount(E_MS_DRV_RTC eRtc, MS_U32 u32Value);
E_MS_DRV_RTC_STATUS MDrv_RTC_SetMatchCount(E_MS_DRV_RTC eRtc, MS_U32 u32Value);
MS_U32 MDrv_RTC_GetMatchCount(E_MS_DRV_RTC eRtc);
E_MS_DRV_RTC_STATUS MDrv_RTC_IntClear(E_MS_DRV_RTC eRtc);
E_MS_DRV_RTC_STATUS MDrv_RTC_SetPeriod(E_MS_DRV_RTC eRtc, MS_U32 u32Amount, E_MS_DRV_RTC_TIME_UNIT eUnit);
E_MS_DRV_RTC_STATUS MDrv_RTC_StartCounter(E_MS_DRV_RTC eRtc);

//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_INIT
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
MS_BOOL MDrv_RTC_Init(E_MS_DRV_RTC eRtc, MS_U32 u32Freq, MS_U32 u32Xtal, MS_U32 u32Sec,InterruptCb pIntCb);
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_CONTROL
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
MS_U32 MDrv_RTC_GetCount(E_MS_DRV_RTC eRtc);
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_INIT
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
void MDrv_RTC_DeInit(E_MS_DRV_RTC eRtc);

//--------------------------------------------------------------------------------------------------
// Utopia2.0 will call this function to register SAR module
//--------------------------------------------------------------------------------------------------
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_ToBeRemove
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
void RTCRegisterToUtopia(FUtopiaOpen ModuleType);
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_ToBeRemove
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
MS_U32 RTCOpen(void** pInstance, MS_U32 u32ModuleVersion, void* pAttribute);
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_ToBeRemove
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
MS_U32 RTCClose(void* pInstance);
//-------------------------------------------------------------------------------------------------
/// MOBF Encrypt
/// @ingroup G_RTC_ToBeRemove
/// @param u32Key \b IN: Key
/// @param bEnable \b IN: TRUE/FLASE
/// @return DRVAESDMA_OK : Success
/// @return Others : Fail
//-------------------------------------------------------------------------------------------------
MS_U32 RTCIoctl(void* pInstance, MS_U32 u32Cmd, void *pArgs);

//RTC_Private
typedef struct _RTC_RESOURCE_PRIVATE
{
    MS_U32 Dummy;
}RTC_RESOURCE_PRIVATE;

typedef struct _RTC_INSTANT_PRIVATE
{

}RTC_INSTANT_PRIVATE;

typedef struct _RTC_INIT_PARAM
{
    E_MS_DRV_RTC eRtc;
    MS_U32 u32Freq;
    MS_U32 u32Xtal;
    MS_U32 u32Sec;
    InterruptCb pIntCb;

} RTC_INIT_PARAM;

MS_U16 MDrv_RTC_SetPowerState(EN_POWER_MODE u16PowerState);

#ifdef __cplusplus
}
#endif

#endif // _DRV_WDT_H_