Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_rtc.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_RTC_H__
6 #define __QM_RTC_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #include "clk.h"
11 
12 /**
13  * Real Time Clock.
14  *
15  * @defgroup groupRTC RTC
16  * @{
17  *
18  * @warning The RTC clock resides in a different clock domain
19  * to the system clock.
20  * It takes 3-4 RTC ticks for a system clock write to propagate
21  * to the RTC domain.
22  * If an entry to sleep is initiated without waiting for a
23  * transaction to complete the SOC will not wake from sleep.
24  */
25 
26 /**
27  * RTC clock ticks to Real-time helpers
28  *
29  * The _prescale value is given in clk_rtc_div_t.
30  */
31 #define QM_RTC_ALARM_SECOND(_prescale) (32768 / BIT(_prescale))
32 #define QM_RTC_ALARM_MINUTE(_prescale) (QM_RTC_ALARM_SECOND(_prescale) * 60)
33 #define QM_RTC_ALARM_HOUR(_prescale) (QM_RTC_ALARM_MINUTE(_prescale) * 60)
34 #define QM_RTC_ALARM_DAY(_prescale) (QM_RTC_ALARM_HOUR(_prescale) * 24)
35 
36 /**
37  * QM RTC configuration type.
38  */
39 typedef struct {
40  uint32_t init_val; /**< Initial value in RTC clocks. */
41  bool alarm_en; /**< Alarm enable. */
42  uint32_t alarm_val; /**< Alarm value in RTC clocks. */
43 
44  /**
45  * RTC Clock prescaler.
46  *
47  * Used to divide the clock frequency of the RTC.
48  *
49  */
51 
52  /**
53  * User callback.
54  *
55  * @param[in] data User defined data.
56  */
57  void (*callback)(void *data);
58  void *callback_data; /**< Callback user data. */
60 
61 /**
62  * Set RTC configuration.
63  *
64  * This includes the initial value in RTC clock periods, and the alarm value if
65  * an alarm is required. If the alarm is enabled, register an ISR with the user
66  * defined callback function.
67  *
68  * @param[in] rtc RTC index.
69  * @param[in] cfg New RTC configuration. This must not be NULL.
70  *
71  * @return Standard errno return type for QMSI.
72  * @retval 0 on success.
73  * @retval Negative @ref errno for possible error codes.
74  */
75 int qm_rtc_set_config(const qm_rtc_t rtc, const qm_rtc_config_t *const cfg);
76 
77 /**
78  * Set Alarm value.
79  *
80  * Set a new RTC alarm value after an alarm, that has been set using the
81  * qm_rtc_set_config function, has expired and a new alarm value is required.
82  *
83  * The RTC clock resides in a different clock domain
84  * to the system clock.
85  * It takes 3-4 RTC ticks for a system clock write to propagate
86  * to the RTC domain.
87  * If an entry to sleep is initiated without waiting for the
88  * transaction to complete the SOC will not wake from sleep.
89  *
90  * @param[in] rtc RTC index.
91  * @param[in] alarm_val Value to set alarm to.
92  *
93  * @return Standard errno return type for QMSI.
94  * @retval 0 on success.
95  * @retval Negative @ref errno for possible error codes.
96  */
97 int qm_rtc_set_alarm(const qm_rtc_t rtc, const uint32_t alarm_val);
98 
99 /**
100  * Read the RTC register value.
101  *
102  * @param[in] rtc RTC index.
103  * @param[out] value Location to store RTC value. This must not be NULL.
104  *
105  * The RTC clock resides in a different clock domain
106  * to the system clock.
107  * It takes 3-4 RTC ticks for a system clock write to propagate
108  * to the RTC domain.
109  * If an entry to sleep is initiated without waiting for the
110  * transaction to complete the SOC will not wake from sleep.
111  *
112  * @return Standard errno return type for QMSI.
113  * @retval 0 on success.
114  * @retval Negative @ref errno for possible error codes.
115  */
116 int qm_rtc_read(const qm_rtc_t rtc, uint32_t *const value);
117 
118 /**
119  * Save RTC context.
120  *
121  * Save the configuration of the specified RTC peripheral
122  * before entering sleep.
123  *
124  * @param[in] rtc RTC index.
125  * @param[out] ctx RTC context structure. This must not be NULL.
126  *
127  * @return Standard errno return type for QMSI.
128  * @retval 0 on success.
129  * @retval Negative @ref errno for possible error codes.
130  */
131 int qm_rtc_save_context(const qm_rtc_t rtc, qm_rtc_context_t *const ctx);
132 
133 /**
134  * Restore RTC context.
135  *
136  * Restore the configuration of the specified RTC peripheral
137  * after exiting sleep.
138  *
139  * @param[in] rtc RTC index.
140  * @param[in] ctx RTC context structure. This must not be NULL.
141  *
142  * @return Standard errno return type for QMSI.
143  * @retval 0 on success.
144  * @retval Negative @ref errno for possible error codes.
145  */
146 int qm_rtc_restore_context(const qm_rtc_t rtc,
147  const qm_rtc_context_t *const ctx);
148 
149 /**
150  * @}
151  */
152 
153 #endif /* __QM_RTC_H__ */
int qm_rtc_read(const qm_rtc_t rtc, uint32_t *const value)
Read the RTC register value.
Definition: qm_rtc.c:101
void * callback_data
Callback user data.
Definition: qm_rtc.h:58
uint32_t alarm_val
Alarm value in RTC clocks.
Definition: qm_rtc.h:42
int qm_rtc_set_alarm(const qm_rtc_t rtc, const uint32_t alarm_val)
Set Alarm value.
Definition: qm_rtc.c:85
int qm_rtc_restore_context(const qm_rtc_t rtc, const qm_rtc_context_t *const ctx)
Restore RTC context.
Definition: qm_rtc.c:158
clk_rtc_div_t prescaler
RTC Clock prescaler.
Definition: qm_rtc.h:50
uint32_t init_val
Initial value in RTC clocks.
Definition: qm_rtc.h:40
clk_rtc_div_t
RTC clock divider type.
Definition: clk.h:97
qm_rtc_t
Number of RTC controllers.
Definition: qm_soc_regs.h:818
int qm_rtc_set_config(const qm_rtc_t rtc, const qm_rtc_config_t *const cfg)
Set RTC configuration.
Definition: qm_rtc.c:37
bool alarm_en
Alarm enable.
Definition: qm_rtc.h:41
int qm_rtc_save_context(const qm_rtc_t rtc, qm_rtc_context_t *const ctx)
Save RTC context.
Definition: qm_rtc.c:150
QM RTC configuration type.
Definition: qm_rtc.h:39