[freertos] /

/*******************************************************************************\r
 * (c) Copyright 2008-2013 Microsemi SoC Products Group.  All rights reserved.\r
 * \r
 *  SmartFusion2 MSS RTC bare metal software driver public API.\r
 *\r
 * SVN $Revision: 5396 $\r
 * SVN $Date: 2013-03-27 21:57:50 +0000 (Wed, 27 Mar 2013) $\r
 */\r
\r
/*=========================================================================*//**\r
  @mainpage SmartFusion2 MSS RTC Bare Metal Driver.\r
\r
  @section intro_sec Introduction\r
  The SmartFusion2 microcontroller subsystem (MSS) includes a real time counter\r
  (RTC) that can generate alarms and wakeup interrupts in real time. This\r
  software driver provides a set of functions for controlling the MSS RTC as\r
  part of a bare metal system where no operating system is available. The driver\r
  can be adapted for use as part of an operating system, but the implementation\r
  of the adaptation layer between the driver and the operating system's driver\r
  model is outside the scope of the driver.\r
  \r
  The MSS RTC driver provides support for the following features:\r
    - Initialization of the RTC\r
    - Configuration of the RTC timebase\r
    - Configuration as a calendar or binary mode counter\r
    - Set the current calendar or binary mode count\r
    - Get the current calendar or binary mode count\r
    - Start and stop the RTC counting\r
    - Set alarm conditions\r
    - Enable, disable and clear the wakeup interrupt\r
    \r
  @section hw_dependencies Hardware Flow Dependencies\r
  The configuration of all features of the MSS RTC is covered by this driver\r
  with the exception of the clock source driving the MSS RTC clock (RTCCLK)\r
  input. The SmartFusion2 MSS clock controller can supply one of three clock\r
  sources to the MSS RTC clock input:\r
    - Crystal Oscillator 32.768 kHz\r
    - 1MHz Oscillator\r
    - 50MHz Oscillator.  (25 MHz in a 1.0v part).\r
  The SmartFusion2 MSS configurator tool in the hardware flow configures one\r
  of these clocks as the RTCCLK input source.\r
  The base address and register addresses and interrupt number assignment for\r
  the MSS RTC block are defined as constants in the SmartFusion2 CMSIS HAL. You\r
  must ensure that the SmartFusion2 CMSIS HAL is either included in the software\r
  tool chain used to build your project or is included in your project.\r
  \r
  @section theory_op Theory of Operation\r
  The MSS RTC driver functions are grouped into the following categories:\r
    - Initialization of the RTC driver and hardware\r
    - Setting and reading the RTC counter current value\r
    - Setting RTC alarm values\r
    - Starting and stopping the RTC\r
    - Interrupt Control\r
    \r
  Initialization\r
  The MSS RTC driver is initialized through a call to the MSS_RTC_init()\r
  function. The MSS_RTC_init() function must be called before any other MSS RTC\r
  driver functions are called.\r
  The MSS_RTC_init() function:\r
    - Stops the RTC counters and disables the RTC alarm\r
    - Disables the RTC wakeup interrupt in the RTC and in the Cortex-M3\r
      interrupt controller (NVIC).\r
    - Clears any pending RTC wakeup interrupt in the RTC and in the Cortex-M3\r
      interrupt controller (NVIC).\r
    - Enables the RTC_WAKEUP_CR[0] mask bit in the MSS System Register to\r
      connect the RTC wakeup interrupt to the Cortex-M3 interrupt controller.\r
    - Resets the RTC counters and the alarm and compare registers\r
    - Sets the RTC's operating mode to binary counter mode or calendar counter\r
      mode, as specified by the mode parameter\r
    - Sets the RTC's prescaler register to the value specified by the prescaler\r
      parameter. The frequency of the clock source driving the MSS RTC clock\r
      (RTCCLK) input is required to calculate the prescaler value.\r
    \r
  Setting and Reading the RTC Counter Value\r
  The MSS RTC supports two mode of operation \96 binary mode and calendar mode.\r
  The following functions are used to set and read the current value of the\r
  counter when the MSS RTC is configured to operate in binary mode:\r
    - MSS_RTC_set_binary_count() \96 This function is used to set the current\r
      value of the RTC binary counter.\r
    - MSS_RTC_get_binary_count() \96 This function is used to read the current\r
      value of the RTC binary counter.\r
  The following functions are used to set and read the current value of the\r
  counter the MSS RTC is configured to operate in calendar mode:\r
    - MSS_RTC_set_calendar_count() \96 This function is used to set the current\r
      value of the RTC calendar counter.\r
    - MSS_RTC_get_calendar_count() \96 This function is used to read the current\r
      value of the RTC calendar counter.\r
 \r
  The following functions resets the RTC counter in either binary and calendar\r
  operating mode:\r
    - MSS_RTC_reset_counter() \96 This function resets the RTC counter.\r
    \r
  Setting RTC Alarms\r
  The MSS RTC can generate alarms when the counter matches a specified count\r
  value in binary mode or a date and time in calendar mode.\r
  The following functions are used to set up alarms:\r
    - MSS_RTC_set_binary_count_alarm() \96 This function sets up one-shot or\r
      periodic alarms when the MSS RTC is configured to operate in binary mode.\r
    - MSS_RTC_set_calendar_count_alarm() \96 This function sets up one-shot or\r
      periodic alarms when the MSS RTC is configured to operate in calendar\r
      mode.\r
  Note: The alarm asserts a wakeup interrupt to the Cortex-M3. This function\r
        enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
        interrupt input to the Cortex-M3 NVIC must be enabled separately by\r
        calling the MSS_RTC_enable_irq() function. The alarm can be disabled at\r
        any time by calling the MSS_RTC_disable_irq() function. activate\r
  \r
  Starting and Stopping the RTC Counter\r
  The following functions start and stop the RTC counter:\r
    - MSS_RTC_start() \96 This function starts the RTC counter.\r
    - MSS_RTC_stop() \96 This function stops the RTC counter.\r
    \r
  Interrupt Control\r
  The MSS_RTC_init() function enables the RTC_WAKEUP_CR[0] mask bit in the MSS\r
  System Register to connect the RTC wakeup interrupt to the Cortex-M3 interrupt\r
  controller.\r
  An RTC_Wakeup_IRQHandler() default implementation is defined, with weak\r
  linkage, in the SmartFusion2 CMSIS HAL. You must provide your own\r
  implementation of the RTC_Wakeup_IRQHandler() function, which will override\r
  the default implementation, to suit your application.\r
  The function prototype for the RTC wakeup interrupt handler is as follows:\r
    void RTC_Wakeup_IRQHandler ( void )\r
  The RTC wakeup interrupt is controlled using the following functions:\r
    - MSS_RTC_enable_irq() \96 The MSS_RTC_enable_irq() function enables the RTC\r
      to interrupt the Cortex-M3 when a wakeup alarm occurs.\r
    - MSS_RTC_disable_irq() \96 The MSS_RTC_disable_irq() function disables the\r
      RTC from interrupting the Cortex-M3 when a wakeup alarm occurs.\r
    - MSS_RTC_clear_irq() \96 The MSS_RTC_clear_irq() function clears a pending\r
      RTC wakeup interrupt at the RTC wakeup output. You must call the\r
      MSS_RTC_clear_irq() function as part of your implementation of the\r
      RTC_Wakeup_IRQHandler() interrupt service routine (ISR) in order to\r
      prevent the same interrupt event retriggering a call to the ISR.\r
\r
 *//*=========================================================================*/\r
#ifndef MSS_RTC_H_\r
#define MSS_RTC_H_\r
\r
#ifdef __cplusplus\r
extern "C" {\r
#endif \r
\r
#include "../../CMSIS/m2sxxx.h"\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_BINARY_MODE constant is used to specify the mode parameter to the\r
  MSS_RTC_init() function. The RTC will run in binary mode if this constant is\r
  used. In binary mode, the calendar counter counts consecutively from 0 all the\r
  way to 2^43.\r
 */\r
#define MSS_RTC_BINARY_MODE               0u\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_CALENDAR_MODE constant is used to specify the mode parameter to\r
  the MSS_RTC_init() function. The RTC will run in calendar mode if this\r
  constant is used. In calendar mode, the calendar counter counts seconds,\r
  minutes, hours, days, months, years, weekdays and weeks.\r
 */\r
#define MSS_RTC_CALENDAR_MODE             1u\r
\r
/*-------------------------------------------------------------------------*//**\r
  The alarm_value parameter of the MSS_RTC_set_calendar_count_alarm() function\r
  is a pointer to an mss_rtc_calendar_t data structure specifying the date and\r
  time at which the alarm is to occur. You must assign the required date and\r
  time values to the mss_rtc_calendar_t structure before calling the function.\r
  Any of the fields of the mss_rtc_calendar_t structure can be set to\r
  MSS_RTC_CALENDAR_DONT_CARE, to indicate that they are not to be considered in\r
  deciding when the alarm will occur; this is necessary when setting periodic\r
  alarms. \r
 */\r
#define MSS_RTC_CALENDAR_DONT_CARE      0xFFu\r
\r
/*-------------------------------------------------------------------------*//**\r
  Days of the week.\r
 */\r
#define MSS_RTC_SUNDAY      1u\r
#define MSS_RTC_MONDAY      2u\r
#define MSS_RTC_TUESDAY     3u\r
#define MSS_RTC_WEDNESDAY   4u\r
#define MSS_RTC_THRUSDAY    5u\r
#define MSS_RTC_FRIDAY      6u\r
#define MSS_RTC_SATURDAY    7u\r
\r
/*-------------------------------------------------------------------------*//**\r
  The mss_rtc_alarm_type_t enumeration is used as the alarm_type parameter for\r
  the MSS_RTC_set_calendar_count_alarm() and MSS_RTC_set_binary_count_alarm()\r
  functions to specify whether the requested alarm should occur only one time or\r
  periodically.\r
 */\r
typedef enum {\r
    MSS_RTC_SINGLE_SHOT_ALARM,\r
    MSS_RTC_PERIODIC_ALARM\r
} mss_rtc_alarm_type_t;\r
\r
/*-------------------------------------------------------------------------*//**\r
  A pointer to an instance of the mss_rtc_calender_t data structure is used to\r
  write new date and time values to the RTC using the\r
  MSS_RTC_set_rtc_calendar_count() and MSS_RTC_set_calendar_count_alarm()\r
  functions. The MSS_RTC_get_calendar_count() function also uses a pointer to an\r
  instance of the mss_rtc_calender_t data structure to read the current date and\r
  time value from the RTC.\r
 */\r
typedef struct mss_rtc_calendar\r
{\r
     uint8_t second;\r
     uint8_t minute;\r
     uint8_t hour;\r
     uint8_t day;\r
     uint8_t month;\r
     uint8_t year;\r
     uint8_t weekday;\r
     uint8_t week;\r
} mss_rtc_calendar_t ;\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_init() function initializes the RTC driver and hardware to a known\r
  state. \r
  To initialize the RTC hardware, this function:\r
    - Stops the RTC counters and disables the RTC alarm\r
    - Disables the RTC wakeup interrupt in the RTC and in the Cortex-M3\r
      interrupt controller (NVIC).\r
    - Clears any pending RTC wakeup interrupt in the RTC and in the Cortex-M3\r
      interrupt controller (NVIC).\r
    - Resets the RTC counters and the alarm and compare registers\r
    - Sets the RTC's operating mode to binary counter mode or calendar counter\r
      mode, as specified by the mode parameter\r
    - Sets the RTC's prescaler register to the value specified by the prescaler\r
      parameter\r
  The MSS clock controller can supply one of three clock sources to the RTC\r
  clock input (RTCCLK):\r
    - Crystal Oscillator 32.768 kHz\r
    - 1MHz Oscillator\r
    - 50MHz Oscillator.  (25 MHz in a 1.0v part).\r
  For calendar mode, program the prescaler register to generate a 1Hz signal\r
  from the active RTCCLK according to the following equation:\r
    prescaler = RTCCLK \96 1 (where RTCCLK unit is Hz)\r
  For a 32.768 kHz clock, set the prescaler to 32768 - 1 = 32767. The prescaler\r
  register is 26 bits wide, allowing clock sources of up to 67 MHz to generate\r
  the 1Hz time base.\r
  For binary mode, the prescaler register can be programmed to generate a 1Hz\r
  time base or a different time base, as required.\r
  \r
  @param mode\r
    The mode parameter is used to specify the operating mode of the RTC. The\r
    allowed values for mode are:\r
      - MSS_RTC_BINARY_MODE\r
      - MSS_RTC_CALENDAR_MODE\r
    \r
  @param prescaler\r
    The prescaler parameter specifies the value to divide the incoming RTC clock\r
    by, to generate the RTC time base signal. For calendar mode, set the\r
    prescaler value to generate a 1Hz time base from the incoming RTC clock\r
    according to the following equation:\r
        prescaler = RTCCLK \96 1    (where the RTCCLK unit is Hz)\r
    For binary mode, set the prescaler value to generate a 1Hz time base or a\r
    different time base, as required.\r
    The prescaler parameter can be any integer value in the range 2 to 2^26.\r
    \r
  @return\r
    This function does not return a value.\r
    \r
  The example code below shows how the RTC can be initialized only after a power-on\r
  reset.\r
  @code\r
    #define PO_RESET_DETECT_MASK    0x00000001u\r
    \r
    void init_application(void)\r
    {\r
        uint32_t power_on_reset;\r
        power_on_reset = SYSREG->RESET_SOURCE_CR & PO_RESET_DETECT_MASK;\r
        if(power_on_reset)\r
        {\r
            MSS_RTC_init(MSS_RTC_CALENDAR_MODE, 32767);\r
            SYSREG->RESET_SOURCE_CR = PO_RESET_DETECT_MASK;\r
        }\r
    }\r
  @endcode\r
 */\r
void\r
MSS_RTC_init\r
(\r
    uint8_t mode,\r
    uint32_t prescaler\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_set_rtc_calendar_count() function sets the current value of the\r
  RTC calendar counter.\r
  Note: This function must only be used when the RTC is configured to operate in\r
        calendar counter mode.\r
        \r
  @param new_rtc_value\r
    The new_rtc_value parameter is a pointer to an mss_rtc_calendar_t data\r
    structure specifying the new date and time value from which the RTC will\r
    increment. You must populate the mss_rtc_calendar_t structure with the\r
    required date and time values before calling this function.\r
    \r
  @return\r
    This function does not return a value.\r
 */\r
\r
void\r
MSS_RTC_set_calendar_count\r
(\r
    const mss_rtc_calendar_t *new_rtc_value\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_set_binary_count() function sets the current value of the RTC\r
  binary counter.\r
  Note: This function must only be used when the RTC is configured to operate in\r
        binary counter mode.\r
        \r
  @param new_rtc_value\r
    The new_rtc_value parameter specifies the new count value from which the RTC\r
    will increment. The binary counter is 43 bits wide, so the maximum allowed\r
    binary value is 2^43.\r
\r
  @return\r
    This function does not return a value.\r
 */\r
\r
void\r
MSS_RTC_set_binary_count\r
(\r
    uint64_t new_rtc_value\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_get_calendar_count() function returns the current value of the RTC\r
  calendar counter via the data structure pointed to by the p_rtc_calendar\r
  parameter.\r
  Note: This function must only be used when the RTC is configured to operate in\r
        calendar counter mode.\r
        \r
  @param p_rtc_calendar\r
    The p_rtc_calendar parameter is a pointer to an mss_rtc_calendar_t data\r
    structure where the current value of the calendar counter will be written by\r
    the MSS_RTC_get_calendar_count() function\r
    \r
  @return\r
    This function does not return a value.\r
 */\r
void\r
MSS_RTC_get_calendar_count\r
(\r
    mss_rtc_calendar_t *p_rtc_calendar\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_get_binary_count() function returns the current value of the RTC\r
  binary counter. \r
  Note: This function must only be used when the RTC is configured to operate in\r
        binary counter mode.\r
        \r
  @param\r
    This function takes no parameters.\r
\r
  @return\r
    This function returns the current value of the RTC binary counter as an\r
    unsigned 64-bit integer.\r
 */\r
uint64_t\r
MSS_RTC_get_binary_count(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_start() function starts the RTC incrementing.\r
\r
  @param\r
    This function takes no parameters.\r
\r
  @return\r
    This function does not return a value.\r
 */\r
void MSS_RTC_start(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_stop() function stops the RTC from incrementing.\r
\r
  @param\r
    This function takes no parameters.\r
\r
  @return\r
    This function does not return a value.\r
 */\r
void MSS_RTC_stop(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_reset_counter() function resets the RTC counters. If the counter\r
  was running before calling this function, then it continues incrementing from\r
  the counter\92s reset value.\r
  \r
  @param\r
    This function takes no parameters.\r
\r
  @return\r
    This function does not return a value.\r
 */\r
void MSS_RTC_reset_counter(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_enable_irq() function enables the RTC wakeup output to interrupt\r
  the Cortex-M3 when an alarm occurs. It enables the RTC wakeup interrupt\r
  (RTC_Wakeup_IRQn) in the Cortex-M3 interrupt controller (NVIC). The\r
  RTC_Wakeup_IRQHandler() function will be called when an RTC wakeup interrupt\r
  occurs.\r
  Note: An RTC_Wakeup_IRQHandler() default implementation is defined, with weak\r
        linkage, in the SmartFusion2 CMSIS HAL. You must provide your own\r
        implementation of the RTC_Wakeup_IRQHandler() function, which will\r
        override the default implementation, to suit your application.\r
  Note: This function only enables the RTC wakeup interrupt at the Cortex-M3\r
        NVIC level. The alarm setting functions enable the wakeup interrupt\r
        output from the RTC.\r
 */\r
void MSS_RTC_enable_irq(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_disable_irq() function disables the RTC wakeup interrupt\r
  (RTC_Wakeup_IRQn) in the Cortex-M3 interrupt controller (NVIC).\r
  Note: This function only disables the RTC wakeup interrupt at the Cortex-M3\r
        NVIC level. It does not disable the wakeup interrupt output from the\r
        RTC.\r
        \r
   @param\r
     This function takes no parameters.\r
\r
   @return\r
     This function does not return a value.\r
 */\r
void MSS_RTC_disable_irq(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_clear_irq() function clears a pending wakeup interrupt from the\r
  RTC. This function does not clear the interrupt in the Cortex-M3 interrupt\r
  controller (NVIC); it only clears the wakeup output from the RTC.\r
  Note: You must call the MSS_RTC_clear_irq() function as part of your\r
        implementation of the RTC_Wakeup_IRQHandler() RTC wakeup interrupt\r
        service routine (ISR) in order to prevent the same interrupt event\r
        retriggering a call to the ISR.\r
        \r
  @param\r
    This function takes no parameters.\r
\r
  @return\r
    This function does not return a value.\r
  \r
  Example:\r
  The example code below demoinstrates how the MSS_RTC_clear_irq() function is\r
  intended to be used as part of the RTC wakeup interrupt servicer routine used\r
  by an application to handle RTC alarms.\r
  @code\r
    #if defined(__GNUC__)\r
    __attribute__((__interrupt__)) void RTC_Wakeup_IRQHandler( void )\r
    #else\r
    void RTC_Wakeup_IRQHandler( void )\r
    #endif\r
    {\r
        process_alarm();\r
        MSS_RTC_clear_irq();\r
    }\r
  @endcode\r
*/\r
void MSS_RTC_clear_irq(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_set_calendar_count_alarm() function sets up the RTC to generate an\r
  alarm when the RTC count reaches the time/date specified by the alarm_value\r
  parameter. The alarm asserts a wakeup interrupt to the Cortex-M3. This\r
  function enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
  interrupt input to the Cortex-M3 NVIC must be enabled separately by calling\r
  the MSS_RTC_enable_irq() function. The alarm can be disabled at any time by\r
  calling the MSS_RTC_disable_irq() function.\r
  \r
  Single-shot alarm\r
  The alarm can be a single-shot alarm, which will generate a single wakeup\r
  interrupt the first time the RTC count reaches the time/date specified by\r
  alarm_value. A single shot alarm is achieved by specifying a value for every\r
  field of the mss_rtc_calendar_t data structure pointed to by the alarm_value\r
  parameter. The RTC counter will keep incrementing after a single shot alarm\r
  occurs.\r
  \r
  Periodic alarm\r
  The alarm can also be a periodic alarm, which will generate a wakeup interrupt\r
  every time the RTC count reaches the time/date specified by alarm_value, with\r
  the counter running in a continuous loop. The periodic alarm can be set to\r
  occur every minute, hour, day, month, year, week, day of the week, or any\r
  valid combination of these. This is achieved by setting some of the fields of\r
  the mss_rtc_calendar_t data structure pointed to by the alarm_value parameter,\r
  to MSS_RTC_CALENDAR_DONT_CARE. For example, setting the weekday field to\r
  MSS_RTC_MONDAY and all other fields to MSS_RTC_CALENDAR_DONT_CARE will result\r
  in an alarm occurring every Monday. You can refine the time at which the alarm\r
  will occur by specifying values for the hour, minute and second fields.\r
  Note: This function must only be used when the RTC is configured to operate in\r
        calendar counter mode.\r
  \r
  @param alarm_value\r
    The alarm_value parameter is a pointer to an mss_rtc_calendar_t data\r
    structure specifying the date and time at which the alarm is to occur. You\r
    must assign the required date and time values to the mss_rtc_calendar_t\r
    structure before calling this function. Some of the fields within the\r
    mss_rtc_calendar_t structure can be set to MSS_RTC_CALENDAR_DONT_CARE, to\r
    indicate that they are not to be considered in deciding when the alarm will\r
    occur; this is necessary when setting periodic alarms.\r
  \r
  @return\r
    This function does not return a value.\r
     \r
  Examples:\r
  \r
  The following example code demonstrates how to configure the RTC to generate a\r
  single calendar alarm at a specific date and time. The alarm will only occur\r
  once and the RTC will keep incrementing regardless of the alarm taking place.\r
  \r
  @code\r
    const mss_rtc_calendar_t initial_calendar_count =\r
    {\r
        15u,     second\r
        30u,     minute\r
        6u,      hour\r
        6u,      day\r
        9u,      month\r
        12u,     year\r
        5u,      weekday\r
        37u      week\r
    };\r
    \r
    mss_rtc_calendar_t alarm_calendar_count =\r
    {\r
        17u,     second\r
        30u,     minute\r
        6u,      hour\r
        6u,      day\r
        9u,      month\r
        12u,     year\r
        5u,      weekday\r
        37u      week\r
    };\r
    \r
    MSS_RTC_init(MSS_RTC_CALENDAR_MODE, RTC_PRESCALER);\r
    MSS_RTC_clear_irq();\r
    MSS_RTC_set_calendar_count(&initial_calendar_count);\r
    MSS_RTC_enable_irq();\r
    MSS_RTC_start();\r
    \r
    MSS_RTC_set_calendar_count_alarm(&alarm_calendar_count);\r
  @endcode\r
  \r
  The following example code demonstrates how to configure the RTC to generate a\r
  periodic calendar alarm. The RTC is configured to generate an alarm every\r
  Tuesday at 16:45:00. The alarm will reoccur every week until the RTC wakeup\r
  interrupt is disabled using a call to MSS_RTC_disable_irq().\r
  \r
  @code\r
    mss_rtc_calendar_t initial_calendar_count =\r
    {\r
        58u,                            <--second\r
        59u,                            <--minute\r
        23u,                            <--hour\r
        10u,                            <--day\r
        9u,                             <--month\r
        12u,                            <--year\r
        MSS_RTC_MONDAY,                 <--weekday\r
        37u                             <--week\r
    };\r
    \r
    mss_rtc_calendar_t alarm_calendar_count =\r
    {\r
        MSS_RTC_CALENDAR_DONT_CARE,     <--second\r
        45u,                            <--minute\r
        16u,                            <--hour\r
        MSS_RTC_CALENDAR_DONT_CARE,     <--day\r
        MSS_RTC_CALENDAR_DONT_CARE,     <--month\r
        MSS_RTC_CALENDAR_DONT_CARE,     <--year\r
        MSS_RTC_TUESDAY,                <--weekday\r
        MSS_RTC_CALENDAR_DONT_CARE      <--week\r
    };\r
    \r
    MSS_RTC_init(MSS_RTC_CALENDAR_MODE, RTC_PRESCALER);\r
    MSS_RTC_set_calendar_count(&initial_calendar_count);\r
    MSS_RTC_enable_irq();\r
    MSS_RTC_start();\r
    \r
    MSS_RTC_set_calendar_count_alarm(&alarm_calendar_count);\r
  @endcode\r
  \r
  The following example code demonstrates the code that you need to include in\r
  your application to handle alarms. It is the interrupt service routine for the\r
  RTC wakeup interrupt input to the Cortex-M3 NVIC. You need to add your\r
  application code in this function in place of the process_alarm() function but\r
  you must retain the call to MSS_RTC_clear_irq() to ensure that the same alarm\r
  does not retrigger the interrupt.\r
  \r
  @code\r
    #if defined(__GNUC__)\r
    __attribute__((__interrupt__)) void RTC_Wakeup_IRQHandler( void )\r
    #else\r
    void RTC_Wakeup_IRQHandler( void )\r
    #endif\r
    {\r
        process_alarm();\r
        MSS_RTC_clear_irq();\r
    }\r
  @endcode\r
 */\r
void MSS_RTC_set_calendar_count_alarm\r
(\r
    const mss_rtc_calendar_t * alarm_value\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_set_binary_count_alarm() function sets up the RTC to generate an\r
  alarm when the RTC count reaches the value specified by the alarm_value\r
  parameter. The alarm asserts a wakeup interrupt to the Cortex-M3. This\r
  function enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
  interrupt input to the Cortex-M3 NVIC must be enabled separately by calling\r
  the MSS_RTC_enable_irq() function. The alarm can be disabled at any time by\r
  calling the MSS_RTC_disable_irq() function.\r
\r
  Single-shot alarm\r
  The alarm can be a single-shot alarm, which will generate a single wakeup\r
  interrupt the first time the RTC count reaches the value specified by the\r
  alarm_value parameter. Setting the alarm_value parameter to\r
  MSS_RTC_PERIODIC_ALARM produces a single-shot alarm. The RTC counter continues\r
  incrementing when a single shot alarm occurs.\r
\r
  Periodic alarm\r
  The alarm can also be a periodic alarm, which will generate a wakeup interrupt\r
  every time the RTC count reaches the value specified by the alarm_value\r
  parameter. Setting the alarm_value parameter to MSS_RTC_SINGLE_SHOT_ALARM\r
  produces a periodic alarm. The RTC counter automatically wraps around to zero\r
  and continues incrementing when a periodic alarm occurs.\r
  Note: This function must only be used when the RTC is configured to operate in\r
        binary counter mode\r
  \r
  @param alarm_value\r
    The alarm_value parameter is a 64-bit unsigned value specifying the RTC\r
    counter value that must be reached for the requested alarm to occur.\r
  \r
  @param alarm_type\r
    The alarm_type parameter specifies whether the requested alarm is a single\r
    shot or periodic alarm. It can only take one of these two values:\r
     - MSS_RTC_SINGLE_SHOT_ALARM,\r
     - MSS_RTC_PERIODIC_ALARM\r
  \r
  @return\r
    This function does not return a value.\r
 */\r
void MSS_RTC_set_binary_count_alarm\r
(\r
    uint64_t alarm_value,\r
    mss_rtc_alarm_type_t alarm_type\r
);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_get_update_flag() function indicates if the RTC counter has\r
  incremented since the last call to MSS_RTC_clear_update_flag(). It returns\r
  zero if no RTC counter increment has occurred. It returns a non-zero value if\r
  the RTC counter has incremented. This function can be used whether the RTC is\r
  configured to operate in calendar or binary counter mode.\r
  \r
  @return\r
   This function returns, \r
   zero:     if the RTC has not incremented since the last call to\r
             MSS_RTC_clear_update_flag(), \r
   non-zero: if the RTC has incremented since the last call to\r
             MSS_RTC_clear_update_flag().\r
\r
   \r
  Example\r
  This example waits for the RTC timer to increment by one second.\r
  @code\r
    void wait_start_of_second(void)\r
    {\r
        uint32_t rtc_count_updated;\r
        MSS_RTC_clear_update_flag();\r
        do {\r
            rtc_count_updated = MSS_RTC_get_update_flag();\r
        } while(!rtc_count_updated)\r
    }\r
  @endcode\r
 */\r
uint32_t MSS_RTC_get_update_flag(void);\r
\r
/*-------------------------------------------------------------------------*//**\r
  The MSS_RTC_clear_update_flag() function clears the CONTROL register flag that\r
  is set when the RTC counter increments. It is used alongside function\r
  MSS_RTC_get_update_flag() to detect RTC counter increments.\r
  \r
  @return\r
    This function does not return a value.\r
    \r
  Example\r
  The example below will wait for the RTC timer to increment by one second.\r
  @code\r
  void wait_start_of_second(void)\r
  {\r
      uint32_t rtc_count_updated;\r
      MSS_RTC_clear_update_flag();\r
      do {\r
          rtc_count_updated = MSS_RTC_get_update_flag();\r
      } while(!rtc_count_updated)\r
  }\r
  @endcode\r
 */\r
void MSS_RTC_clear_update_flag(void);\r
\r
#ifdef __cplusplus\r
}\r
#endif\r
\r
#endif /* MSS_RTC_H_ */\r