git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_SmartFusion2_M2S050_SoftConsole/RTOSDemo_Hardware_Platform/drivers/mss_rtc/mss_rtc.h

   1 /*******************************************************************************\r
   2  * (c) Copyright 2008-2013 Microsemi SoC Products Group.  All rights reserved.\r
   3  * \r
   4  *  SmartFusion2 MSS RTC bare metal software driver public API.\r
   5  *\r
   6  * SVN $Revision: 5396 $\r
   7  * SVN $Date: 2013-03-27 21:57:50 +0000 (Wed, 27 Mar 2013) $\r
   8  */\r
   9 \r
  10 /*=========================================================================*//**\r
  11   @mainpage SmartFusion2 MSS RTC Bare Metal Driver.\r
  12 \r
  13   @section intro_sec Introduction\r
  14   The SmartFusion2 microcontroller subsystem (MSS) includes a real time counter\r
  15   (RTC) that can generate alarms and wakeup interrupts in real time. This\r
  16   software driver provides a set of functions for controlling the MSS RTC as\r
  17   part of a bare metal system where no operating system is available. The driver\r
  18   can be adapted for use as part of an operating system, but the implementation\r
  19   of the adaptation layer between the driver and the operating system's driver\r
  20   model is outside the scope of the driver.\r
  21   \r
  22   The MSS RTC driver provides support for the following features:\r
  23     - Initialization of the RTC\r
  24     - Configuration of the RTC timebase\r
  25     - Configuration as a calendar or binary mode counter\r
  26     - Set the current calendar or binary mode count\r
  27     - Get the current calendar or binary mode count\r
  28     - Start and stop the RTC counting\r
  29     - Set alarm conditions\r
  30     - Enable, disable and clear the wakeup interrupt\r
  31     \r
  32   @section hw_dependencies Hardware Flow Dependencies\r
  33   The configuration of all features of the MSS RTC is covered by this driver\r
  34   with the exception of the clock source driving the MSS RTC clock (RTCCLK)\r
  35   input. The SmartFusion2 MSS clock controller can supply one of three clock\r
  36   sources to the MSS RTC clock input:\r
  37     - Crystal Oscillator 32.768 kHz\r
  38     - 1MHz Oscillator\r
  39     - 50MHz Oscillator.  (25 MHz in a 1.0v part).\r
  40   The SmartFusion2 MSS configurator tool in the hardware flow configures one\r
  41   of these clocks as the RTCCLK input source.\r
  42   The base address and register addresses and interrupt number assignment for\r
  43   the MSS RTC block are defined as constants in the SmartFusion2 CMSIS HAL. You\r
  44   must ensure that the SmartFusion2 CMSIS HAL is either included in the software\r
  45   tool chain used to build your project or is included in your project.\r
  46   \r
  47   @section theory_op Theory of Operation\r
  48   The MSS RTC driver functions are grouped into the following categories:\r
  49     - Initialization of the RTC driver and hardware\r
  50     - Setting and reading the RTC counter current value\r
  51     - Setting RTC alarm values\r
  52     - Starting and stopping the RTC\r
  53     - Interrupt Control\r
  54     \r
  55   Initialization\r
  56   The MSS RTC driver is initialized through a call to the MSS_RTC_init()\r
  57   function. The MSS_RTC_init() function must be called before any other MSS RTC\r
  58   driver functions are called.\r
  59   The MSS_RTC_init() function:\r
  60     - Stops the RTC counters and disables the RTC alarm\r
  61     - Disables the RTC wakeup interrupt in the RTC and in the Cortex-M3\r
  62       interrupt controller (NVIC).\r
  63     - Clears any pending RTC wakeup interrupt in the RTC and in the Cortex-M3\r
  64       interrupt controller (NVIC).\r
  65     - Enables the RTC_WAKEUP_CR[0] mask bit in the MSS System Register to\r
  66       connect the RTC wakeup interrupt to the Cortex-M3 interrupt controller.\r
  67     - Resets the RTC counters and the alarm and compare registers\r
  68     - Sets the RTC's operating mode to binary counter mode or calendar counter\r
  69       mode, as specified by the mode parameter\r
  70     - Sets the RTC's prescaler register to the value specified by the prescaler\r
  71       parameter. The frequency of the clock source driving the MSS RTC clock\r
  72       (RTCCLK) input is required to calculate the prescaler value.\r
  73     \r
  74   Setting and Reading the RTC Counter Value\r
  75   The MSS RTC supports two mode of operation \96 binary mode and calendar mode.\r
  76   The following functions are used to set and read the current value of the\r
  77   counter when the MSS RTC is configured to operate in binary mode:\r
  78     - MSS_RTC_set_binary_count() \96 This function is used to set the current\r
  79       value of the RTC binary counter.\r
  80     - MSS_RTC_get_binary_count() \96 This function is used to read the current\r
  81       value of the RTC binary counter.\r
  82   The following functions are used to set and read the current value of the\r
  83   counter the MSS RTC is configured to operate in calendar mode:\r
  84     - MSS_RTC_set_calendar_count() \96 This function is used to set the current\r
  85       value of the RTC calendar counter.\r
  86     - MSS_RTC_get_calendar_count() \96 This function is used to read the current\r
  87       value of the RTC calendar counter.\r
  88  \r
  89   The following functions resets the RTC counter in either binary and calendar\r
  90   operating mode:\r
  91     - MSS_RTC_reset_counter() \96 This function resets the RTC counter.\r
  92     \r
  93   Setting RTC Alarms\r
  94   The MSS RTC can generate alarms when the counter matches a specified count\r
  95   value in binary mode or a date and time in calendar mode.\r
  96   The following functions are used to set up alarms:\r
  97     - MSS_RTC_set_binary_count_alarm() \96 This function sets up one-shot or\r
  98       periodic alarms when the MSS RTC is configured to operate in binary mode.\r
  99     - MSS_RTC_set_calendar_count_alarm() \96 This function sets up one-shot or\r
 100       periodic alarms when the MSS RTC is configured to operate in calendar\r
 101       mode.\r
 102   Note: The alarm asserts a wakeup interrupt to the Cortex-M3. This function\r
 103         enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
 104         interrupt input to the Cortex-M3 NVIC must be enabled separately by\r
 105         calling the MSS_RTC_enable_irq() function. The alarm can be disabled at\r
 106         any time by calling the MSS_RTC_disable_irq() function. activate\r
 107   \r
 108   Starting and Stopping the RTC Counter\r
 109   The following functions start and stop the RTC counter:\r
 110     - MSS_RTC_start() \96 This function starts the RTC counter.\r
 111     - MSS_RTC_stop() \96 This function stops the RTC counter.\r
 112     \r
 113   Interrupt Control\r
 114   The MSS_RTC_init() function enables the RTC_WAKEUP_CR[0] mask bit in the MSS\r
 115   System Register to connect the RTC wakeup interrupt to the Cortex-M3 interrupt\r
 116   controller.\r
 117   An RTC_Wakeup_IRQHandler() default implementation is defined, with weak\r
 118   linkage, in the SmartFusion2 CMSIS HAL. You must provide your own\r
 119   implementation of the RTC_Wakeup_IRQHandler() function, which will override\r
 120   the default implementation, to suit your application.\r
 121   The function prototype for the RTC wakeup interrupt handler is as follows:\r
 122     void RTC_Wakeup_IRQHandler ( void )\r
 123   The RTC wakeup interrupt is controlled using the following functions:\r
 124     - MSS_RTC_enable_irq() \96 The MSS_RTC_enable_irq() function enables the RTC\r
 125       to interrupt the Cortex-M3 when a wakeup alarm occurs.\r
 126     - MSS_RTC_disable_irq() \96 The MSS_RTC_disable_irq() function disables the\r
 127       RTC from interrupting the Cortex-M3 when a wakeup alarm occurs.\r
 128     - MSS_RTC_clear_irq() \96 The MSS_RTC_clear_irq() function clears a pending\r
 129       RTC wakeup interrupt at the RTC wakeup output. You must call the\r
 130       MSS_RTC_clear_irq() function as part of your implementation of the\r
 131       RTC_Wakeup_IRQHandler() interrupt service routine (ISR) in order to\r
 132       prevent the same interrupt event retriggering a call to the ISR.\r
 133 \r
 134  *//*=========================================================================*/\r
 135 #ifndef MSS_RTC_H_\r
 136 #define MSS_RTC_H_\r
 137 \r
 138 #ifdef __cplusplus\r
 139 extern "C" {\r
 140 #endif \r
 141 \r
 142 #include "../../CMSIS/m2sxxx.h"\r
 143 \r
 144 /*-------------------------------------------------------------------------*//**\r
 145   The MSS_RTC_BINARY_MODE constant is used to specify the mode parameter to the\r
 146   MSS_RTC_init() function. The RTC will run in binary mode if this constant is\r
 147   used. In binary mode, the calendar counter counts consecutively from 0 all the\r
 148   way to 2^43.\r
 149  */\r
 150 #define MSS_RTC_BINARY_MODE               0u\r
 151 \r
 152 /*-------------------------------------------------------------------------*//**\r
 153   The MSS_RTC_CALENDAR_MODE constant is used to specify the mode parameter to\r
 154   the MSS_RTC_init() function. The RTC will run in calendar mode if this\r
 155   constant is used. In calendar mode, the calendar counter counts seconds,\r
 156   minutes, hours, days, months, years, weekdays and weeks.\r
 157  */\r
 158 #define MSS_RTC_CALENDAR_MODE             1u\r
 159 \r
 160 /*-------------------------------------------------------------------------*//**\r
 161   The alarm_value parameter of the MSS_RTC_set_calendar_count_alarm() function\r
 162   is a pointer to an mss_rtc_calendar_t data structure specifying the date and\r
 163   time at which the alarm is to occur. You must assign the required date and\r
 164   time values to the mss_rtc_calendar_t structure before calling the function.\r
 165   Any of the fields of the mss_rtc_calendar_t structure can be set to\r
 166   MSS_RTC_CALENDAR_DONT_CARE, to indicate that they are not to be considered in\r
 167   deciding when the alarm will occur; this is necessary when setting periodic\r
 168   alarms. \r
 169  */\r
 170 #define MSS_RTC_CALENDAR_DONT_CARE      0xFFu\r
 171 \r
 172 /*-------------------------------------------------------------------------*//**\r
 173   Days of the week.\r
 174  */\r
 175 #define MSS_RTC_SUNDAY      1u\r
 176 #define MSS_RTC_MONDAY      2u\r
 177 #define MSS_RTC_TUESDAY     3u\r
 178 #define MSS_RTC_WEDNESDAY   4u\r
 179 #define MSS_RTC_THRUSDAY    5u\r
 180 #define MSS_RTC_FRIDAY      6u\r
 181 #define MSS_RTC_SATURDAY    7u\r
 182 \r
 183 /*-------------------------------------------------------------------------*//**\r
 184   The mss_rtc_alarm_type_t enumeration is used as the alarm_type parameter for\r
 185   the MSS_RTC_set_calendar_count_alarm() and MSS_RTC_set_binary_count_alarm()\r
 186   functions to specify whether the requested alarm should occur only one time or\r
 187   periodically.\r
 188  */\r
 189 typedef enum {\r
 190     MSS_RTC_SINGLE_SHOT_ALARM,\r
 191     MSS_RTC_PERIODIC_ALARM\r
 192 } mss_rtc_alarm_type_t;\r
 193 \r
 194 /*-------------------------------------------------------------------------*//**\r
 195   A pointer to an instance of the mss_rtc_calender_t data structure is used to\r
 196   write new date and time values to the RTC using the\r
 197   MSS_RTC_set_rtc_calendar_count() and MSS_RTC_set_calendar_count_alarm()\r
 198   functions. The MSS_RTC_get_calendar_count() function also uses a pointer to an\r
 199   instance of the mss_rtc_calender_t data structure to read the current date and\r
 200   time value from the RTC.\r
 201  */\r
 202 typedef struct mss_rtc_calendar\r
 203 {\r
 204      uint8_t second;\r
 205      uint8_t minute;\r
 206      uint8_t hour;\r
 207      uint8_t day;\r
 208      uint8_t month;\r
 209      uint8_t year;\r
 210      uint8_t weekday;\r
 211      uint8_t week;\r
 212 } mss_rtc_calendar_t ;\r
 213 \r
 214 /*-------------------------------------------------------------------------*//**\r
 215   The MSS_RTC_init() function initializes the RTC driver and hardware to a known\r
 216   state. \r
 217   To initialize the RTC hardware, this function:\r
 218     - Stops the RTC counters and disables the RTC alarm\r
 219     - Disables the RTC wakeup interrupt in the RTC and in the Cortex-M3\r
 220       interrupt controller (NVIC).\r
 221     - Clears any pending RTC wakeup interrupt in the RTC and in the Cortex-M3\r
 222       interrupt controller (NVIC).\r
 223     - Resets the RTC counters and the alarm and compare registers\r
 224     - Sets the RTC's operating mode to binary counter mode or calendar counter\r
 225       mode, as specified by the mode parameter\r
 226     - Sets the RTC's prescaler register to the value specified by the prescaler\r
 227       parameter\r
 228   The MSS clock controller can supply one of three clock sources to the RTC\r
 229   clock input (RTCCLK):\r
 230     - Crystal Oscillator 32.768 kHz\r
 231     - 1MHz Oscillator\r
 232     - 50MHz Oscillator.  (25 MHz in a 1.0v part).\r
 233   For calendar mode, program the prescaler register to generate a 1Hz signal\r
 234   from the active RTCCLK according to the following equation:\r
 235     prescaler = RTCCLK \96 1 (where RTCCLK unit is Hz)\r
 236   For a 32.768 kHz clock, set the prescaler to 32768 - 1 = 32767. The prescaler\r
 237   register is 26 bits wide, allowing clock sources of up to 67 MHz to generate\r
 238   the 1Hz time base.\r
 239   For binary mode, the prescaler register can be programmed to generate a 1Hz\r
 240   time base or a different time base, as required.\r
 241   \r
 242   @param mode\r
 243     The mode parameter is used to specify the operating mode of the RTC. The\r
 244     allowed values for mode are:\r
 245       - MSS_RTC_BINARY_MODE\r
 246       - MSS_RTC_CALENDAR_MODE\r
 247     \r
 248   @param prescaler\r
 249     The prescaler parameter specifies the value to divide the incoming RTC clock\r
 250     by, to generate the RTC time base signal. For calendar mode, set the\r
 251     prescaler value to generate a 1Hz time base from the incoming RTC clock\r
 252     according to the following equation:\r
 253         prescaler = RTCCLK \96 1    (where the RTCCLK unit is Hz)\r
 254     For binary mode, set the prescaler value to generate a 1Hz time base or a\r
 255     different time base, as required.\r
 256     The prescaler parameter can be any integer value in the range 2 to 2^26.\r
 257     \r
 258   @return\r
 259     This function does not return a value.\r
 260     \r
 261   The example code below shows how the RTC can be initialized only after a power-on\r
 262   reset.\r
 263   @code\r
 264     #define PO_RESET_DETECT_MASK    0x00000001u\r
 265     \r
 266     void init_application(void)\r
 267     {\r
 268         uint32_t power_on_reset;\r
 269         power_on_reset = SYSREG->RESET_SOURCE_CR & PO_RESET_DETECT_MASK;\r
 270         if(power_on_reset)\r
 271         {\r
 272             MSS_RTC_init(MSS_RTC_CALENDAR_MODE, 32767);\r
 273             SYSREG->RESET_SOURCE_CR = PO_RESET_DETECT_MASK;\r
 274         }\r
 275     }\r
 276   @endcode\r
 277  */\r
 278 void\r
 279 MSS_RTC_init\r
 280 (\r
 281     uint8_t mode,\r
 282     uint32_t prescaler\r
 283 );\r
 284 \r
 285 /*-------------------------------------------------------------------------*//**\r
 286   The MSS_RTC_set_rtc_calendar_count() function sets the current value of the\r
 287   RTC calendar counter.\r
 288   Note: This function must only be used when the RTC is configured to operate in\r
 289         calendar counter mode.\r
 290         \r
 291   @param new_rtc_value\r
 292     The new_rtc_value parameter is a pointer to an mss_rtc_calendar_t data\r
 293     structure specifying the new date and time value from which the RTC will\r
 294     increment. You must populate the mss_rtc_calendar_t structure with the\r
 295     required date and time values before calling this function.\r
 296     \r
 297   @return\r
 298     This function does not return a value.\r
 299  */\r
 300 \r
 301 void\r
 302 MSS_RTC_set_calendar_count\r
 303 (\r
 304     const mss_rtc_calendar_t *new_rtc_value\r
 305 );\r
 306 \r
 307 /*-------------------------------------------------------------------------*//**\r
 308   The MSS_RTC_set_binary_count() function sets the current value of the RTC\r
 309   binary counter.\r
 310   Note: This function must only be used when the RTC is configured to operate in\r
 311         binary counter mode.\r
 312         \r
 313   @param new_rtc_value\r
 314     The new_rtc_value parameter specifies the new count value from which the RTC\r
 315     will increment. The binary counter is 43 bits wide, so the maximum allowed\r
 316     binary value is 2^43.\r
 317 \r
 318   @return\r
 319     This function does not return a value.\r
 320  */\r
 321 \r
 322 void\r
 323 MSS_RTC_set_binary_count\r
 324 (\r
 325     uint64_t new_rtc_value\r
 326 );\r
 327 \r
 328 /*-------------------------------------------------------------------------*//**\r
 329   The MSS_RTC_get_calendar_count() function returns the current value of the RTC\r
 330   calendar counter via the data structure pointed to by the p_rtc_calendar\r
 331   parameter.\r
 332   Note: This function must only be used when the RTC is configured to operate in\r
 333         calendar counter mode.\r
 334         \r
 335   @param p_rtc_calendar\r
 336     The p_rtc_calendar parameter is a pointer to an mss_rtc_calendar_t data\r
 337     structure where the current value of the calendar counter will be written by\r
 338     the MSS_RTC_get_calendar_count() function\r
 339     \r
 340   @return\r
 341     This function does not return a value.\r
 342  */\r
 343 void\r
 344 MSS_RTC_get_calendar_count\r
 345 (\r
 346     mss_rtc_calendar_t *p_rtc_calendar\r
 347 );\r
 348 \r
 349 /*-------------------------------------------------------------------------*//**\r
 350   The MSS_RTC_get_binary_count() function returns the current value of the RTC\r
 351   binary counter. \r
 352   Note: This function must only be used when the RTC is configured to operate in\r
 353         binary counter mode.\r
 354         \r
 355   @param\r
 356     This function takes no parameters.\r
 357 \r
 358   @return\r
 359     This function returns the current value of the RTC binary counter as an\r
 360     unsigned 64-bit integer.\r
 361  */\r
 362 uint64_t\r
 363 MSS_RTC_get_binary_count(void);\r
 364 \r
 365 /*-------------------------------------------------------------------------*//**\r
 366   The MSS_RTC_start() function starts the RTC incrementing.\r
 367 \r
 368   @param\r
 369     This function takes no parameters.\r
 370 \r
 371   @return\r
 372     This function does not return a value.\r
 373  */\r
 374 void MSS_RTC_start(void);\r
 375 \r
 376 /*-------------------------------------------------------------------------*//**\r
 377   The MSS_RTC_stop() function stops the RTC from incrementing.\r
 378 \r
 379   @param\r
 380     This function takes no parameters.\r
 381 \r
 382   @return\r
 383     This function does not return a value.\r
 384  */\r
 385 void MSS_RTC_stop(void);\r
 386 \r
 387 /*-------------------------------------------------------------------------*//**\r
 388   The MSS_RTC_reset_counter() function resets the RTC counters. If the counter\r
 389   was running before calling this function, then it continues incrementing from\r
 390   the counter\92s reset value.\r
 391   \r
 392   @param\r
 393     This function takes no parameters.\r
 394 \r
 395   @return\r
 396     This function does not return a value.\r
 397  */\r
 398 void MSS_RTC_reset_counter(void);\r
 399 \r
 400 /*-------------------------------------------------------------------------*//**\r
 401   The MSS_RTC_enable_irq() function enables the RTC wakeup output to interrupt\r
 402   the Cortex-M3 when an alarm occurs. It enables the RTC wakeup interrupt\r
 403   (RTC_Wakeup_IRQn) in the Cortex-M3 interrupt controller (NVIC). The\r
 404   RTC_Wakeup_IRQHandler() function will be called when an RTC wakeup interrupt\r
 405   occurs.\r
 406   Note: An RTC_Wakeup_IRQHandler() default implementation is defined, with weak\r
 407         linkage, in the SmartFusion2 CMSIS HAL. You must provide your own\r
 408         implementation of the RTC_Wakeup_IRQHandler() function, which will\r
 409         override the default implementation, to suit your application.\r
 410   Note: This function only enables the RTC wakeup interrupt at the Cortex-M3\r
 411         NVIC level. The alarm setting functions enable the wakeup interrupt\r
 412         output from the RTC.\r
 413  */\r
 414 void MSS_RTC_enable_irq(void);\r
 415 \r
 416 /*-------------------------------------------------------------------------*//**\r
 417   The MSS_RTC_disable_irq() function disables the RTC wakeup interrupt\r
 418   (RTC_Wakeup_IRQn) in the Cortex-M3 interrupt controller (NVIC).\r
 419   Note: This function only disables the RTC wakeup interrupt at the Cortex-M3\r
 420         NVIC level. It does not disable the wakeup interrupt output from the\r
 421         RTC.\r
 422         \r
 423    @param\r
 424      This function takes no parameters.\r
 425 \r
 426    @return\r
 427      This function does not return a value.\r
 428  */\r
 429 void MSS_RTC_disable_irq(void);\r
 430 \r
 431 /*-------------------------------------------------------------------------*//**\r
 432   The MSS_RTC_clear_irq() function clears a pending wakeup interrupt from the\r
 433   RTC. This function does not clear the interrupt in the Cortex-M3 interrupt\r
 434   controller (NVIC); it only clears the wakeup output from the RTC.\r
 435   Note: You must call the MSS_RTC_clear_irq() function as part of your\r
 436         implementation of the RTC_Wakeup_IRQHandler() RTC wakeup interrupt\r
 437         service routine (ISR) in order to prevent the same interrupt event\r
 438         retriggering a call to the ISR.\r
 439         \r
 440   @param\r
 441     This function takes no parameters.\r
 442 \r
 443   @return\r
 444     This function does not return a value.\r
 445   \r
 446   Example:\r
 447   The example code below demoinstrates how the MSS_RTC_clear_irq() function is\r
 448   intended to be used as part of the RTC wakeup interrupt servicer routine used\r
 449   by an application to handle RTC alarms.\r
 450   @code\r
 451     #if defined(__GNUC__)\r
 452     __attribute__((__interrupt__)) void RTC_Wakeup_IRQHandler( void )\r
 453     #else\r
 454     void RTC_Wakeup_IRQHandler( void )\r
 455     #endif\r
 456     {\r
 457         process_alarm();\r
 458         MSS_RTC_clear_irq();\r
 459     }\r
 460   @endcode\r
 461 */\r
 462 void MSS_RTC_clear_irq(void);\r
 463 \r
 464 /*-------------------------------------------------------------------------*//**\r
 465   The MSS_RTC_set_calendar_count_alarm() function sets up the RTC to generate an\r
 466   alarm when the RTC count reaches the time/date specified by the alarm_value\r
 467   parameter. The alarm asserts a wakeup interrupt to the Cortex-M3. This\r
 468   function enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
 469   interrupt input to the Cortex-M3 NVIC must be enabled separately by calling\r
 470   the MSS_RTC_enable_irq() function. The alarm can be disabled at any time by\r
 471   calling the MSS_RTC_disable_irq() function.\r
 472   \r
 473   Single-shot alarm\r
 474   The alarm can be a single-shot alarm, which will generate a single wakeup\r
 475   interrupt the first time the RTC count reaches the time/date specified by\r
 476   alarm_value. A single shot alarm is achieved by specifying a value for every\r
 477   field of the mss_rtc_calendar_t data structure pointed to by the alarm_value\r
 478   parameter. The RTC counter will keep incrementing after a single shot alarm\r
 479   occurs.\r
 480   \r
 481   Periodic alarm\r
 482   The alarm can also be a periodic alarm, which will generate a wakeup interrupt\r
 483   every time the RTC count reaches the time/date specified by alarm_value, with\r
 484   the counter running in a continuous loop. The periodic alarm can be set to\r
 485   occur every minute, hour, day, month, year, week, day of the week, or any\r
 486   valid combination of these. This is achieved by setting some of the fields of\r
 487   the mss_rtc_calendar_t data structure pointed to by the alarm_value parameter,\r
 488   to MSS_RTC_CALENDAR_DONT_CARE. For example, setting the weekday field to\r
 489   MSS_RTC_MONDAY and all other fields to MSS_RTC_CALENDAR_DONT_CARE will result\r
 490   in an alarm occurring every Monday. You can refine the time at which the alarm\r
 491   will occur by specifying values for the hour, minute and second fields.\r
 492   Note: This function must only be used when the RTC is configured to operate in\r
 493         calendar counter mode.\r
 494   \r
 495   @param alarm_value\r
 496     The alarm_value parameter is a pointer to an mss_rtc_calendar_t data\r
 497     structure specifying the date and time at which the alarm is to occur. You\r
 498     must assign the required date and time values to the mss_rtc_calendar_t\r
 499     structure before calling this function. Some of the fields within the\r
 500     mss_rtc_calendar_t structure can be set to MSS_RTC_CALENDAR_DONT_CARE, to\r
 501     indicate that they are not to be considered in deciding when the alarm will\r
 502     occur; this is necessary when setting periodic alarms.\r
 503   \r
 504   @return\r
 505     This function does not return a value.\r
 506      \r
 507   Examples:\r
 508   \r
 509   The following example code demonstrates how to configure the RTC to generate a\r
 510   single calendar alarm at a specific date and time. The alarm will only occur\r
 511   once and the RTC will keep incrementing regardless of the alarm taking place.\r
 512   \r
 513   @code\r
 514     const mss_rtc_calendar_t initial_calendar_count =\r
 515     {\r
 516         15u,     second\r
 517         30u,     minute\r
 518         6u,      hour\r
 519         6u,      day\r
 520         9u,      month\r
 521         12u,     year\r
 522         5u,      weekday\r
 523         37u      week\r
 524     };\r
 525     \r
 526     mss_rtc_calendar_t alarm_calendar_count =\r
 527     {\r
 528         17u,     second\r
 529         30u,     minute\r
 530         6u,      hour\r
 531         6u,      day\r
 532         9u,      month\r
 533         12u,     year\r
 534         5u,      weekday\r
 535         37u      week\r
 536     };\r
 537     \r
 538     MSS_RTC_init(MSS_RTC_CALENDAR_MODE, RTC_PRESCALER);\r
 539     MSS_RTC_clear_irq();\r
 540     MSS_RTC_set_calendar_count(&initial_calendar_count);\r
 541     MSS_RTC_enable_irq();\r
 542     MSS_RTC_start();\r
 543     \r
 544     MSS_RTC_set_calendar_count_alarm(&alarm_calendar_count);\r
 545   @endcode\r
 546   \r
 547   The following example code demonstrates how to configure the RTC to generate a\r
 548   periodic calendar alarm. The RTC is configured to generate an alarm every\r
 549   Tuesday at 16:45:00. The alarm will reoccur every week until the RTC wakeup\r
 550   interrupt is disabled using a call to MSS_RTC_disable_irq().\r
 551   \r
 552   @code\r
 553     mss_rtc_calendar_t initial_calendar_count =\r
 554     {\r
 555         58u,                            <--second\r
 556         59u,                            <--minute\r
 557         23u,                            <--hour\r
 558         10u,                            <--day\r
 559         9u,                             <--month\r
 560         12u,                            <--year\r
 561         MSS_RTC_MONDAY,                 <--weekday\r
 562         37u                             <--week\r
 563     };\r
 564     \r
 565     mss_rtc_calendar_t alarm_calendar_count =\r
 566     {\r
 567         MSS_RTC_CALENDAR_DONT_CARE,     <--second\r
 568         45u,                            <--minute\r
 569         16u,                            <--hour\r
 570         MSS_RTC_CALENDAR_DONT_CARE,     <--day\r
 571         MSS_RTC_CALENDAR_DONT_CARE,     <--month\r
 572         MSS_RTC_CALENDAR_DONT_CARE,     <--year\r
 573         MSS_RTC_TUESDAY,                <--weekday\r
 574         MSS_RTC_CALENDAR_DONT_CARE      <--week\r
 575     };\r
 576     \r
 577     MSS_RTC_init(MSS_RTC_CALENDAR_MODE, RTC_PRESCALER);\r
 578     MSS_RTC_set_calendar_count(&initial_calendar_count);\r
 579     MSS_RTC_enable_irq();\r
 580     MSS_RTC_start();\r
 581     \r
 582     MSS_RTC_set_calendar_count_alarm(&alarm_calendar_count);\r
 583   @endcode\r
 584   \r
 585   The following example code demonstrates the code that you need to include in\r
 586   your application to handle alarms. It is the interrupt service routine for the\r
 587   RTC wakeup interrupt input to the Cortex-M3 NVIC. You need to add your\r
 588   application code in this function in place of the process_alarm() function but\r
 589   you must retain the call to MSS_RTC_clear_irq() to ensure that the same alarm\r
 590   does not retrigger the interrupt.\r
 591   \r
 592   @code\r
 593     #if defined(__GNUC__)\r
 594     __attribute__((__interrupt__)) void RTC_Wakeup_IRQHandler( void )\r
 595     #else\r
 596     void RTC_Wakeup_IRQHandler( void )\r
 597     #endif\r
 598     {\r
 599         process_alarm();\r
 600         MSS_RTC_clear_irq();\r
 601     }\r
 602   @endcode\r
 603  */\r
 604 void MSS_RTC_set_calendar_count_alarm\r
 605 (\r
 606     const mss_rtc_calendar_t * alarm_value\r
 607 );\r
 608 \r
 609 /*-------------------------------------------------------------------------*//**\r
 610   The MSS_RTC_set_binary_count_alarm() function sets up the RTC to generate an\r
 611   alarm when the RTC count reaches the value specified by the alarm_value\r
 612   parameter. The alarm asserts a wakeup interrupt to the Cortex-M3. This\r
 613   function enables the RTC\92s wakeup interrupt output, however the RTC wakeup\r
 614   interrupt input to the Cortex-M3 NVIC must be enabled separately by calling\r
 615   the MSS_RTC_enable_irq() function. The alarm can be disabled at any time by\r
 616   calling the MSS_RTC_disable_irq() function.\r
 617 \r
 618   Single-shot alarm\r
 619   The alarm can be a single-shot alarm, which will generate a single wakeup\r
 620   interrupt the first time the RTC count reaches the value specified by the\r
 621   alarm_value parameter. Setting the alarm_value parameter to\r
 622   MSS_RTC_PERIODIC_ALARM produces a single-shot alarm. The RTC counter continues\r
 623   incrementing when a single shot alarm occurs.\r
 624 \r
 625   Periodic alarm\r
 626   The alarm can also be a periodic alarm, which will generate a wakeup interrupt\r
 627   every time the RTC count reaches the value specified by the alarm_value\r
 628   parameter. Setting the alarm_value parameter to MSS_RTC_SINGLE_SHOT_ALARM\r
 629   produces a periodic alarm. The RTC counter automatically wraps around to zero\r
 630   and continues incrementing when a periodic alarm occurs.\r
 631   Note: This function must only be used when the RTC is configured to operate in\r
 632         binary counter mode\r
 633   \r
 634   @param alarm_value\r
 635     The alarm_value parameter is a 64-bit unsigned value specifying the RTC\r
 636     counter value that must be reached for the requested alarm to occur.\r
 637   \r
 638   @param alarm_type\r
 639     The alarm_type parameter specifies whether the requested alarm is a single\r
 640     shot or periodic alarm. It can only take one of these two values:\r
 641      - MSS_RTC_SINGLE_SHOT_ALARM,\r
 642      - MSS_RTC_PERIODIC_ALARM\r
 643   \r
 644   @return\r
 645     This function does not return a value.\r
 646  */\r
 647 void MSS_RTC_set_binary_count_alarm\r
 648 (\r
 649     uint64_t alarm_value,\r
 650     mss_rtc_alarm_type_t alarm_type\r
 651 );\r
 652 \r
 653 /*-------------------------------------------------------------------------*//**\r
 654   The MSS_RTC_get_update_flag() function indicates if the RTC counter has\r
 655   incremented since the last call to MSS_RTC_clear_update_flag(). It returns\r
 656   zero if no RTC counter increment has occurred. It returns a non-zero value if\r
 657   the RTC counter has incremented. This function can be used whether the RTC is\r
 658   configured to operate in calendar or binary counter mode.\r
 659   \r
 660   @return\r
 661    This function returns, \r
 662    zero:     if the RTC has not incremented since the last call to\r
 663              MSS_RTC_clear_update_flag(), \r
 664    non-zero: if the RTC has incremented since the last call to\r
 665              MSS_RTC_clear_update_flag().\r
 666 \r
 667    \r
 668   Example\r
 669   This example waits for the RTC timer to increment by one second.\r
 670   @code\r
 671     void wait_start_of_second(void)\r
 672     {\r
 673         uint32_t rtc_count_updated;\r
 674         MSS_RTC_clear_update_flag();\r
 675         do {\r
 676             rtc_count_updated = MSS_RTC_get_update_flag();\r
 677         } while(!rtc_count_updated)\r
 678     }\r
 679   @endcode\r
 680  */\r
 681 uint32_t MSS_RTC_get_update_flag(void);\r
 682 \r
 683 /*-------------------------------------------------------------------------*//**\r
 684   The MSS_RTC_clear_update_flag() function clears the CONTROL register flag that\r
 685   is set when the RTC counter increments. It is used alongside function\r
 686   MSS_RTC_get_update_flag() to detect RTC counter increments.\r
 687   \r
 688   @return\r
 689     This function does not return a value.\r
 690     \r
 691   Example\r
 692   The example below will wait for the RTC timer to increment by one second.\r
 693   @code\r
 694   void wait_start_of_second(void)\r
 695   {\r
 696       uint32_t rtc_count_updated;\r
 697       MSS_RTC_clear_update_flag();\r
 698       do {\r
 699           rtc_count_updated = MSS_RTC_get_update_flag();\r
 700       } while(!rtc_count_updated)\r
 701   }\r
 702   @endcode\r
 703  */\r
 704 void MSS_RTC_clear_update_flag(void);\r
 705 \r
 706 #ifdef __cplusplus\r
 707 }\r
 708 #endif\r
 709 \r
 710 #endif /* MSS_RTC_H_ */\r