Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

- File List

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 */
50 clk_rtc_div_t prescaler;
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. */
59 } qm_rtc_config_t;
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__ */
qm_rtc_read
int qm_rtc_read(const qm_rtc_t rtc, uint32_t *const value)
Read the RTC register value.
Definition: qm_rtc.c:101
qm_rtc_config_t::callback_data
void * callback_data
Callback user data.
Definition: qm_rtc.h:58
qm_rtc_config_t::alarm_val
uint32_t alarm_val
Alarm value in RTC clocks.
Definition: qm_rtc.h:42
qm_rtc_set_alarm
int qm_rtc_set_alarm(const qm_rtc_t rtc, const uint32_t alarm_val)
Set Alarm value.
Definition: qm_rtc.c:85
qm_rtc_restore_context
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
qm_rtc_config_t::prescaler
clk_rtc_div_t prescaler
RTC Clock prescaler.
Definition: qm_rtc.h:50
qm_rtc_config_t::init_val
uint32_t init_val
Initial value in RTC clocks.
Definition: qm_rtc.h:40
clk_rtc_div_t
clk_rtc_div_t
RTC clock divider type.
Definition: clk.h:97
qm_rtc_t
qm_rtc_t
Number of RTC controllers.
Definition: qm_soc_regs.h:818
qm_rtc_set_config
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
qm_rtc_config_t::alarm_en
bool alarm_en
Alarm enable.
Definition: qm_rtc.h:41
qm_rtc_save_context
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_config_t
QM RTC configuration type.
Definition: qm_rtc.h:39