XMC RTC

1 /**
2 * @file xmc_rtc.h
3 * @date 2015-06-20
4 *
5 * @cond
6 **************************************************************************************
*******************************
7 * XMClib v2.0.0 - XMC Peripheral Driver Library
8 *
9 * Copyright (c) 2015, Infineon Technologies AG
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or without
modification,are permitted provided that the
13 * following conditions are met:
14 *
15 * Redistributions of source code must retain the above copyright notice, this list
of conditions and the following
16 * disclaimer.
17 *
18 * Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following
19 * disclaimer in the documentation and/or other materials provided with the
distribution.
20 *
21 * Neither the name of the copyright holders nor the names of its contributors may be
used to endorse or promote
22 * products derived from this software without specific prior written
permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES,
25 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE
26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR
28 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY,
29 * WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
31 *
32 * To improve the quality of the software, users are encouraged to share
modifications, enhancements or bug fixes with
33 * Infineon Technologies AG
[email protected]).
34
*************************************************************************************
********************************
35 *
36 * Change History
37 * --------------
38 *
39 * 2015-02-20:
40 * - Initial
41 *
42 * 2015-05-20:
43 * - Documentation updates 
44 * - In xmc1_rtc file XMC_RTC_Init function
45 * is modified by adding the RTC running condition check
46 *
47 * 2015-06-20:
48 * - Removed version macros and declaration of GetDriverVersion API
49 * @endcond
50 *
51 */
52
53 #ifndef XMC_RTC_H
54 #define XMC_RTC_H
55
56 /*************************************************************************************
********************************
57 * HEADER FILES
58
*************************************************************************************
********************************/
59
60 #include <xmc_common.h>
61 #include <time.h>
62 #if UC_FAMILY == XMC1
63 #include "xmc1_rtc.h"
64 #endif
65
66 #if UC_FAMILY == XMC4
67 #include "xmc4_rtc.h"
68 #endif
69 /**
70 *
71 * @addtogroup XMClib XMC Peripheral Library
72 * @{
73 */
74
75 /**
76 * @addtogroup RTC
77 * @brief RTC driver for XMC microcontroller family.
78 *
79 * Real-time clock (RTC) is a clock that keeps track of the current time. Precise
80 * real time keeping is with a 32.768 KHz external crystal clock or a 32.768 KHz
81 * high precision internal clock. It provides a periodic time based interrupt and
82 * a programmable alarm interrupt on time match. It also supports wakeup from
83 * hibernate.
84 *
85 * The RTC low level driver provides functions to configure and initialize the RTC
86 * hardware peripheral.
87 *
88 * @{
89 */
90
91 /*************************************************************************************
********************************
92 * MACROS
93
*************************************************************************************
********************************/
94
95 /*************************************************************************************
********************************
96 * ENUMS
97
*************************************************************************************
********************************/
98
99 /**
100 * Status return values for RTC low level driver
101 */
102 typedef enum XMC_RTC_STATUS
103 {
104 XMC_RTC_STATUS_OK = 0U, /**< Operation successful */
105 XMC_RTC_STATUS_ERROR = 1U, /**< Operation unsuccessful */
106 XMC_RTC_STATUS_BUSY = 2U /**< Busy with a previous request */
107 } XMC_RTC_STATUS_t;
108
109 /**
110 * Events which enables interrupt request generation
111 */
112 typedef enum XMC_RTC_EVENT
113 {
114 XMC_RTC_EVENT_PERIODIC_SECONDS = RTC_MSKSR_MPSE_Msk, /**< Mask value to enable an
event on periodic seconds */
115 XMC_RTC_EVENT_PERIODIC_MINUTES = RTC_MSKSR_MPMI_Msk, /**< Mask value to enable an
116 XMC_RTC_EVENT_PERIODIC_HOURS = RTC_MSKSR_MPHO_Msk, /**< Mask value to enable an
117 XMC_RTC_EVENT_PERIODIC_DAYS = RTC_MSKSR_MPDA_Msk, /**< Mask value to enable an
118 XMC_RTC_EVENT_PERIODIC_MONTHS = RTC_MSKSR_MPMO_Msk, /**< Mask value to enable an
119 XMC_RTC_EVENT_PERIODIC_YEARS = RTC_MSKSR_MPYE_Msk, /**< Mask value to enable an
120 XMC_RTC_EVENT_ALARM = RTC_MSKSR_MAI_Msk /**< Mask value to enable an
121 } XMC_RTC_EVENT_t;
122
123 /**
124 * Months used to program the date
125 */
126 typedef enum XMC_RTC_MONTH
127 {
128 XMC_RTC_MONTH_JANUARY = 0U,
129 XMC_RTC_MONTH_FEBRUARY = 1U,
130 XMC_RTC_MONTH_MARCH = 2U,
131 XMC_RTC_MONTH_APRIL = 3U,
132 XMC_RTC_MONTH_MAY = 4U,
133 XMC_RTC_MONTH_JUNE = 5U,
134 XMC_RTC_MONTH_JULY = 6U,
135 XMC_RTC_MONTH_AUGUST = 7U,
136 XMC_RTC_MONTH_SEPTEMBER = 8U,
137 XMC_RTC_MONTH_OCTOBER = 9U,
138 XMC_RTC_MONTH_NOVEMBER = 10U,
139 XMC_RTC_MONTH_DECEMBER = 11U
140 } XMC_RTC_MONTH_t;
141
142 /**
143 * Week days used program the date
144 */
145 typedef enum XMC_RTC_WEEKDAY
146 {
147 XMC_RTC_WEEKDAY_SUNDAY = 0U,
148 XMC_RTC_WEEKDAY_MONDAY = 1U,
149 XMC_RTC_WEEKDAY_TUESDAY = 2U,
150 XMC_RTC_WEEKDAY_WEDNESDAY = 3U,
151 XMC_RTC_WEEKDAY_THURSDAY = 4U,
152 XMC_RTC_WEEKDAY_FRIDAY = 5U,
153 XMC_RTC_WEEKDAY_SATURDAY = 6U
154 } XMC_RTC_WEEKDAY_t;
155
156 /*************************************************************************************
********************************
157 * DATA STRUCTURES
158
*************************************************************************************
********************************/
159 /*Anonymous structure/union guard start*/
160 #if defined(__CC_ARM)
161 #pragma push
162 #pragma anon_unions
163 #elif defined(__TASKING__)
164 #pragma warning 586
165 #endif
166
167
168 /**
169 * Alarm time values of RTC 
170 *
171 * The structure presents a convenient way to set/obtain the
172 * alarm time values for seconds, minutes, hours, days, month and year of RTC.
173 * The XMC_RTC_SetAlarm() and XMC_RTC_GetAlarm() can be
174 * used to populate the structure with the alarm time value of
175 * RTC
176 */
177 typedef struct XMC_RTC_ALARM
178 {
179 union
180 {
181 uint32_t raw0;
182 struct
183 {
184 uint32_t seconds : 6; /**< Alarm seconds compare value (0-59: Above this
causes this bitfield to be set with 0)*/
185 uint32_t : 2;
186 uint32_t minutes : 6; /**< Alarm minutes compare value (0-59: Above this
187 uint32_t : 2;
188 uint32_t hours : 5; /**< Alarm hours compare value (0-23: Above this
189 uint32_t : 3;
190 uint32_t days : 5; /**< Alarm days compare value (0-Actual days of month:
Above this causes this bitfield to be set with 0)*/
191 uint32_t : 3;
192 };
193 };
194
195 union
196 {
197 uint32_t raw1;
198 struct
199 {
200 uint32_t : 8;
201 uint32_t month : 4; /**< Alarm month compare value (0-11: Above this
causes this bitfield to be set with 0) */
202 uint32_t : 4;
203 uint32_t year : 16; /**< Alarm year compare value */
204 };
205 };
206 } XMC_RTC_ALARM_t;
207
208 /**
209 * Time values of RTC 
210 *
211 * The structure presents a convenient way to set/obtain the
212 * time values for seconds, minutes, hours, days, month and year of RTC.
213 * The XMC_RTC_SetTime() and XMC_RTC_GetTime() can be
214 * used to populate the structure with the time value of
215 * RTC
216 */
217 typedef struct XMC_RTC_TIME
218 {
219 union
220 {
221 uint32_t raw0;
222 struct
223 {
224 uint32_t seconds : 6; /**< Seconds time value (0-59: Above this causes this
bitfield to be set with 0) */
225 uint32_t : 2;
226 uint32_t minutes : 6; /**< Minutes time value (0-59: Above this causes this
227 uint32_t : 2;
228 uint32_t hours : 5; /**< Hours time value (0-23: Above this causes this
229 uint32_t : 3;
230 uint32_t days : 5; /**< Days time value (0-Actual days of month: Above
this causes this bitfield to be set with 0)*/
231 uint32_t : 3;
232 };
233 };
234
235 union
236 {
237 uint32_t raw1;
238 struct
239 {
240 uint32_t daysofweek : 3; /**< Days of week time value (0-6: Above this
241 uint32_t : 5;
242 uint32_t month : 4; /**< Month time value (0-11: Above this
243 uint32_t : 4;
244 uint32_t year : 16; /**< Year time value */
245 };
246 };
247 } XMC_RTC_TIME_t;
248 /*Anonymous structure/union guard end*/
249 #if defined(__CC_ARM)
250 #pragma pop
251 #elif defined(__TASKING__)
252 #pragma warning restore
253 #endif
254
255 /**
256 * RTC initialization with time, alarm and clock divider(prescaler) configurations 
257 *
258 * The structure presents a convenient way to set/obtain the time and alarm
configurations
259 * for RTC. The XMC_RTC_Init() can be used to populate the structure with the time
and alarm
260 * values of RTC.
261 */
262 typedef struct XMC_RTC_CONFIG
263 {
264 XMC_RTC_TIME_t time;
265 XMC_RTC_ALARM_t alarm;
266 uint16_t prescaler;
267 } XMC_RTC_CONFIG_t;
268
269 /*************************************************************************************
********************************
270 * API PROTOTYPES
271
*************************************************************************************
********************************/
272
273 #ifdef __cplusplus
274 extern "C" {
275 #endif
276
277 /**
278 * @param config Constant pointer to a constant ::XMC_RTC_CONFIG_t structure
containing the
279 * time, alarm time and clock divider(prescaler) configuration.
280 * @return XMC_RTC_STATUS_t Always returns XMC_RTC_STATUS_OK (It contains only
register assignment statements)
281 *
282 * \parDescription: 
283 * Initialize the RTC peripheral 
284 *
285 * \par \if XMC4
286 * The function enables the hibernate domain for accessing RTC peripheral registers,
configures
287 * internal clock divider, time and alarm values by writing to the CTR.DIV, TIM0,
TIM1, ATIM0 and
288 * ATIM1 registers.
289 * \endif
290 *
291 * \if XMC1
292 * The function ungates the peripheral clock for RTC, configures
293 * internal clock divider, time and alarm values by writing to the CTR.DIV, TIM0,
TIM1, ATIM0 and
294 * ATIM1 registers.
295 * \endif
296 */
297 XMC_RTC_STATUS_t XMC_RTC_Init(const XMC_RTC_CONFIG_t *const config);
298
299 /**
300 * @return None
301 *
302 * \parDescription 
303 * Enables RTC peripheral for programming its registers 
304 *
305 * \par \if XMC4
306 * Enables the hibernate domain for accessing RTC peripheral registers.
307 * \endif
308 *
309 * \if XMC1
310 * Ungates the peripheral clock.
311 * \endif
312 *
313 * \parRelated APIs: 
314 * XMC_RTC_Disable(), XMC_SCU_RESET_DeassertPeripheralReset()
315 */
316 void XMC_RTC_Enable(void);
317
318 /**
319 * @return None
320 *
322 * Disables RTC peripheral for programming its registers 
323 *
324 * \par \if XMC4
325 * Empty function (Hibernate domain is not disabled).
326 * \endif
327 *
328 * \if XMC1
329 * Gates the peripheral clock.
330 * \endif
331 *
333 * XMC_RTC_Enable(), XMC_SCU_RESET_AssertPeripheralReset()
334 */
335 void XMC_RTC_Disable(void);
336
337 /**
338 * @return None
339 *
341 * Checks RTC peripheral is enabled for programming its registers 
342 *
343 * \par \if XMC4
344 * Checks the hibernate domain is enabled or not.
345 * \endif
346 *
347 * \if XMC1
348 * Checks peripheral clock is ungated or not.
349 * \endif
350 *
352 * XMC_RTC_Enable(), XMC_RTC_Disable(), XMC_SCU_RESET_DeassertPeripheralReset(),
353 * XMC_SCU_RESET_AssertPeripheralReset()
354 */
355 bool XMC_RTC_IsEnabled(void);
356
357 /**
358 * @return None
359 *
361 * Enables RTC peripheral to start counting time 
362 *
363 * \par
364 * The function starts the RTC for counting time by setting
365 * CTR.ENB bit. Before starting the RTC, it should not be in
366 * running mode and also hibernate domain should be enabled.
367 *
369 * XMC_RTC_Enable(), XMC_RTC_Stop(), XMC_SCU_RESET_DeassertPeripheralReset()
370 */
371 void XMC_RTC_Start(void);
372
373 /**
374 * @return None
375 *
377 * Disables RTC peripheral to start counting time 
378 *
379 * \par
380 * The function stops the RTC for counting time by resetting
381 * CTR.ENB. Before stopping the RTC, hibernate domain should be enabled.
382 *
384 * XMC_RTC_Enable(), XMC_RTC_Start(), XMC_SCU_RESET_AssertPeripheralReset()
385 */
386 void XMC_RTC_Stop(void);
387
388 /**
389 * @param prescaler Prescaler value to be set
390 * @return None
391 *
393 * Sets the RTC module prescaler value 
394 *
395 * \par
396 * The function sets the CTR.DIV bitfield to configure the prescalar value.
397 * The default value for the prescalar with the 32.768kHz crystal (or the internal
clock)
398 * is 7FFFH for a time interval of 1 sec. Before setting the prescaler value RTC
should be
399 * in stop mode and hibernate domain should be enabled.
400 *
402 * XMC_RTC_Stop(), XMC_RTC_Enable(), XMC_RTC_GetPrescaler()
403 */
404 void XMC_RTC_SetPrescaler(uint16_t prescaler);
405
406 /**
407 * @return None
408 *
410 * Gets the RTC module prescaler value 
411 *
412 * \par
413 * The function reads the CTR.DIV bitfield to get the prescalar value. The default
value
414 * for the prescalar with the 32.768kHz crystal (or the internal clock) is 7FFFH for
a
415 * time interval of 1 sec.
416 *
418 * XMC_RTC_SetPrescaler()
419 */
420 __STATIC_INLINE uint32_t XMC_RTC_GetPrescaler(void)
421 {
422 return (uint32_t)(((uint32_t)RTC->CTR & (uint32_t)RTC_CTR_DIV_Msk) >> (uint32_t)
RTC_CTR_DIV_Pos);
423 }
424
425 /**
426 * @param timeval Contstant pointer to a constant ::XMC_RTC_TIME_t structure
containing the
427 * time parameters seconds, minutes, hours, days, daysofweek, month
and year.
428 * @return None
429 *
431 * Sets the RTC module time values 
432 *
433 * \par
434 * The function sets the TIM0, TIM1 registers with time values.
435 * The values can only be written when RTC is disabled.
436 * See the structure ::XMC_RTC_TIME_t for the valid range of time value parameters. 
437 *
439 * XMC_RTC_GetTime(), XMC_RTC_Stop()
440 */
441 void XMC_RTC_SetTime(const XMC_RTC_TIME_t *const timeval);
442
443 /**
444 * @param time Pointer to a constant ::XMC_RTC_TIME_t structure containing the time
parameters
445 * seconds, minutes, hours, days, daysofweek, month and year.
446 * @return None
447 *
449 * Gets the RTC module time value 
450 *
451 * \par
452 * The function gets the time values from TIM0, TIM1 registers.
br>
454 *
456 * XMC_RTC_SetTime()
457 */
458 void XMC_RTC_GetTime(XMC_RTC_TIME_t *const time);
459
460 /**
461 * @param stdtime Pointer to a constant ::tm structure containing the time parameters
seconds,
462 * minutes, hours, days, daysofweek, month, year(since 1900) and days
in a
463 * year in standard format.
464 * @return None
465 *
467 * Gets the RTC module time value in standard format 
468 *
469 * \par
470 * The function gets the time values from TIM0, TIM1 registers.
br>
472 * For days the valid range is (1 - Actual days of month), year (since 1900) and
473 * daysinyear (0 -365).
474 *
476 * XMC_RTC_SetTime(), XMC_RTC_GetTime()
477 */
478 void XMC_RTC_GetTimeStdFormat(struct tm *const stdtime);
479
480 /**
481 * @param timeval Contstant pointer to a constant ::XMC_RTC_ALARM_t structure
containing the
482 * alarm time parameters alarm seconds, alarm minutes, alarm hours,
alarm days,
483 * alarm daysofweek, alarm month and alarm year.
484 * @return None
485 *
487 * Sets the RTC module alarm time value 
488 *
489 * \par
490 * The function sets the ATIM0, ATIM1 registers with alarm time values.
491 * See the structure ::XMC_RTC_ALARM_t for the valid range of alarm time value
parameters. 
492 *
494 * XMC_RTC_GetAlarm()
495 */
496 void XMC_RTC_SetAlarm(const XMC_RTC_ALARM_t *const alarm);
497
498 /**
499 * @param time Pointer to a constant ::XMC_RTC_ALARM_t structure containing the
500 * time parameters alarm seconds, alarm minutes, alarm hours, alarm days,
501 * alarm daysofweek, alarm month and alarm year.
502 * @return None
503 *
505 * Gets the RTC module alarm time value 
506 *
507 * \par
508 * The function gets the alarm time values from ATIM0, ATIM1 registers.
parameters. 
510 *
512 * XMC_RTC_SetAlarm()
513 */
514 void XMC_RTC_GetAlarm(XMC_RTC_ALARM_t *const alarm);
515
516 /**
517 * @param stdtime Pointer to a constant ::tm structure containing the time parameters
alarm seconds,
518 * alarm minutes, alarm hours, alarm days, alarm daysofweek, alarm
month,
519 * alarm year(since 1900) and alarm days in a year in standard
format.
520 * @return None
521 *
523 * Gets the RTC module alarm time value in standard format 
524 *
525 * \par
526 * The function gets the alarm time values from ATIM0, ATIM1 registers.
parameters. 
528 * For days the valid range is (1 - Actual days of month), year (since 1900) and
529 * daysinyear (0 -365).
530 *
532 * XMC_RTC_SetAlarm(), XMC_RTC_GetAlarm()
533 */
534 void XMC_RTC_GetAlarmStdFormat(struct tm *const stdtime);
535
536 /**
537 * @param event A valid RTC event (::XMC_RTC_EVENT_t) or a valid combination of
538 * logically OR'd events
539 * @return None
540 *
542 * Enable RTC periodic and alarm event(s) 
543 *
544 * \par
545 * The function sets the bitfields of MSKSR register to enable interrupt generation
546 * for requested RTC event(s).
547 * Setting the masking value for the event(s) containing in the ::XMC_RTC_EVENT_t
leads
548 * to a generation of the interrupt.
549 *
551 * XMC_RTC_DisableEvent()
552 */
553 void XMC_RTC_EnableEvent(const uint32_t event);
554
555 /**
558 * @return None
559 *
561 * Disable RTC periodic and alarm event(s) 
562 *
563 * \par
564 * The function resets the bitfields of MSKSR register to disable interrupt
generation
565 * for requested RTC event(s).
566 * Resetting the masking value for the the event(s) containing in the
::XMC_RTC_EVENT_t blocks
567 * the generation of the interrupt.
568 *
570 * XMC_RTC_EnableEvent()
571 */
572 void XMC_RTC_DisableEvent(const uint32_t event);
573
574 /**
577 * @return None
578 *
580 * Clears periodic and alarm event(s) status 
581 *
582 * \par
583 * The function sets the bitfields of CLRSR register to clear status bits in RAWSTAT
and STSSR registers.
584 * Setting the value for the the RTC event(s) containing in the ::XMC_RTC_EVENT_t
clears the
585 * corresponding status bits in RAWSTAT and STSSR registers.
586 *
588 * XMC_RTC_GetEventStatus()
589 */
590 void XMC_RTC_ClearEvent(const uint32_t event);
591
592 /**
593 * @return None
594 *
596 * Gets the RTC periodic and alarm event(s) status 
597 *
598 * \par
599 * The function reads the bitfields of STSSR register
600 * to get the status of RTC events.
601 * Reading the value of the register STSSR gives the status of the event(s)
containing in the ::XMC_RTC_EVENT_t.
602 *
604 * XMC_RTC_ClearEvent()
605 */
606 uint32_t XMC_RTC_GetEventStatus(void);
607
608 /**
609 * @return bool true if RTC is running
610 * false if RTC is not running
611 *
613 * Checks the running status of the RTC 
614 *
615 * \par
616 * The function reads the bitfield ENB of CTR register
617 * to get the running status of RTC.
618 *
620 * XMC_RTC_Start(), XMC_RTC_Stop()
621 */
622 __STATIC_INLINE bool XMC_RTC_IsRunning(void)
623 {
624 return (bool)(RTC->CTR & RTC_CTR_ENB_Msk);
625 }
626
627 #ifdef __cplusplus
628 }
629 #endif
630
631 /**
632 * @}
633 */
634
635 /**
636 * @}
637 */
638
639 #endif /* XMC_RTC_H */
640

XMC RTC

Uploaded by

Copyright:

Available Formats

XMC RTC

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

XMC RTC

Uploaded by

Copyright:

Available Formats

1 /**

You might also like