Skip to content

Commit b3399ee

Browse files
nfaurantnfaurant
committed
drivers: rtc: Dedicated API proposal
 - Currently all RTC peripherals are implemented through Counter - This new API is specific to RTC independently from Counter Signed-off-by: FAURANT Nicolas <[email protected]>
1 parent 56b435f commit b3399ee

File tree

2 files changed

+270
-3
lines changed

2 files changed

+270
-3
lines changed

‎doc/reference/peripherals/rtc.rst‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,14 @@ RTC
66
Overview
77
********
88

9-
This is a placeholder for API specific to real-time clocks. Currently
10-
all RTC peripherals are implemented through :ref:`counter_api` with
11-
device-specific API for counters with real-time support.
9+
This is a placeholder for API specific to real-time clocks.
10+
11+
Configuration Options
12+
*********************
13+
14+
Related configuration options:
15+
16+
* :kconfig:`CONFIG_RTC`
1217

1318
API Reference
1419
*************

‎include/drivers/rtc.h‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
/**
2+
* @file
3+
* @brief RTC public API header file.
4+
*/
5+
/*
6+
* Copyright (c) 2021 LACROIX Group
7+
*
8+
* SPDX-License-Identifier: Apache-2.0
9+
*/
10+
11+
#ifndef ZEPHYR_INCLUDE_DRIVERS_RTC_H_
12+
#define ZEPHYR_INCLUDE_DRIVERS_RTC_H_
13+
14+
#ifdef __cplusplus
15+
extern "C" {
16+
#endif
17+
18+
#include <time.h>
19+
#include <device.h>
20+
// #include <dt-bindings/rtc/rtc.h>
21+
22+
/**
23+
* @brief RTC driver APIs
24+
* @defgroup rtc_interface RTC driver APIs
25+
* @ingroup io_interfaces
26+
* @{
27+
*/
28+
29+
/** @brief Wake up timers enum. */
30+
enum rtc_wakeup_id {
31+
RTC_WUT0, /**< Wake Up timer 0. */
32+
/* Add new item before RTC_WUT_NUM. */
33+
RTC_WUT_NUM, /**< Number of wut for the driver. */
34+
};
35+
36+
/** @brief Alarms enum. */
37+
enum rtc_alarm_id {
38+
RTC_ALARMA, /**< Alarm A. */
39+
RTC_ALARMB, /**< Alarm B. */
40+
/* Add new item before RTC_ALARM_NUM. */
41+
RTC_ALARM_NUM, /**< Number of alarms for the driver. */
42+
};
43+
44+
/** @brief Specifies if the RTC Alarm is on date or Week day. */
45+
enum rtc_alarm_date_weekday {
46+
RTC_ALARM_DATE_SEL, /**< Alarm Date is selected, set parameter to a value in the 1-31 range. */
47+
RTC_ALARM_WEEKDAY_SEL, /**< Alarm Weekday is selected, set parameter to a value in the 0-6 range (days since Sunday). */
48+
};
49+
50+
/** @brief Specifies the RTC Alarm Masks. */
51+
enum rtc_alarm_mask {
52+
RTC_ALARM_MASK_NONE, /**< No mask. */
53+
RTC_ALARM_MASK_DATE_WEEKDAY, /**< Mask on date or weekday. */
54+
RTC_ALARM_MASK_HOURS, /**< Mask on hours. */
55+
RTC_ALARM_MASK_MIN, /**< Mask on minutes. */
56+
RTC_ALARM_MASK_SEC, /**< Mask on seconds. */
57+
RTC_ALARM_MASK_ALL, /**< Mask on all. */
58+
};
59+
60+
/** @brief Wake up timer structure. */
61+
struct rtc_wakeup {
62+
uint32_t period; /**< Wake up timer period in milliseconds. */
63+
void (*callback)(const struct device *dev); /**< Callback function. Can be NULL. */
64+
};
65+
66+
/** @brief Alarm structure.
67+
* @param alarm_time Alarm time members
68+
* @param alarm_date_weekday_sel Alarm selection: on Date or on WeekDay.
69+
* If Alarm date is selected, use tm_mday [1 to 31] to set the alarm
70+
* If WeekDay date is selected, use tm_wday [0 to 6] to set the alarm
71+
* @param callback Callback function. Can be NULL.
72+
*/
73+
struct rtc_alarm {
74+
struct tm alarm_time; /**< Alarm time members. */
75+
enum rtc_alarm_mask alarm_mask; /**< Alarm mask. */
76+
/** Alarm selection: on Date or on WeekDay.
77+
* If Alarm date is selected, use tm_mday [1 to 31] to set the alarm
78+
* If WeekDay date is selected, use tm_wday [0 to 6] to set the alarm
79+
*/
80+
enum rtc_alarm_date_weekday alarm_date_weekday_sel;
81+
void (*callback)(const struct device *dev); /**< Callback function. Can be NULL. */
82+
};
83+
84+
/**
85+
* @brief RTC driver API
86+
*
87+
* This is the mandatory API any RTC driver needs to expose.
88+
*/
89+
__subsystem struct rtc_driver_api {
90+
int (*set_time)(const struct device *dev, const struct tm date_time);
91+
int (*get_time)(const struct device *dev, struct tm *date_time);
92+
int (*set_wakeup_timer)(const struct device *dev, struct rtc_wakeup wut, enum rtc_wakeup_id wut_id);
93+
int (*start_wakeup_timer)(const struct device *dev, enum rtc_wakeup_id wut_id);
94+
int (*stop_wakeup_timer)(const struct device *dev, enum rtc_wakeup_id wut_id);
95+
int (*set_alarm)(const struct device *dev, struct rtc_alarm alarm, enum rtc_alarm_id alarm_id);
96+
int (*start_alarm)(const struct device *dev, enum rtc_alarm_id alarm_id);
97+
int (*stop_alarm)(const struct device *dev, enum rtc_alarm_id alarm_id);
98+
};
99+
100+
/**
101+
* @brief Set current date and time
102+
*
103+
* @param dev Pointeur to the device instance
104+
* @param date_time Structure with date and time structure.
105+
* @retval 0 On success.
106+
* @retval -ENOTSUP If request is not supported
107+
* @retval -EINVAL If date or time settings are invalid.
108+
*/
109+
__syscall int rtc_set_time(const struct device *dev, const struct tm date_time);
110+
static inline int z_impl_rtc_set_time(const struct device *dev, const struct tm date_time)
111+
{
112+
const struct rtc_driver_api *api = dev->api;
113+
114+
__ASSERT(api->print, "Callback pointer should not be NULL");
115+
return (api->set_time(dev, date_time));
116+
}
117+
118+
/**
119+
* @brief Get current date and time
120+
*
121+
* @param dev Pointeur to the device instance
122+
* @param date_time Pointeur to date and time structure.
123+
*
124+
* @retval 0 On success.
125+
* @retval -ENOTSUP If request is not supported.
126+
*/
127+
__syscall int rtc_get_time(const struct device *dev, struct tm *date_time);
128+
static inline int z_impl_rtc_get_time(const struct device *dev, struct tm *date_time)
129+
{
130+
const struct rtc_driver_api *api = dev->api;
131+
132+
__ASSERT(api->print, "Callback pointer should not be NULL");
133+
return (api->get_time(dev, date_time));
134+
}
135+
136+
/**
137+
* @brief Set wake up timer
138+
*
139+
* @param dev Pointeur to the device instance
140+
* @param wut Wake up timer parameters
141+
* @param wut_id Wake up timer id
142+
*
143+
* @retval 0 On success.
144+
* @retval -ENOTSUP If request is not supported.
145+
* @retval -EINVAL If wut_id is invalid.
146+
*/
147+
__syscall int rtc_set_wakeup_timer(const struct device *dev, struct rtc_wakeup wut, enum rtc_wakeup_id wut_id);
148+
static inline int z_impl_rtc_set_wakeup_timer(const struct device *dev, struct rtc_wakeup wut, enum rtc_wakeup_id wut_id)
149+
{
150+
const struct rtc_driver_api *api = dev->api;
151+
152+
__ASSERT(api->print, "Callback pointer should not be NULL");
153+
return (api->set_wakeup_timer(dev, wut, wut_id));
154+
}
155+
156+
/**
157+
* @brief Start wake up timer with interrupt
158+
*
159+
* @param dev Pointeur to the device instance
160+
* @param wut_id Wake up timer id
161+
*
162+
* @retval 0 On success.
163+
* @retval -ENOTSUP If request is not supported.
164+
* @retval -EINVAL If wut_id is invalid.
165+
*/
166+
__syscall int rtc_start_wakeup_timer(const struct device *dev, enum rtc_wakeup_id wut_id);
167+
static inline int z_impl_rtc_start_wakeup_timer(const struct device *dev, enum rtc_wakeup_id wut_id)
168+
{
169+
const struct rtc_driver_api *api = dev->api;
170+
171+
__ASSERT(api->print, "Callback pointer should not be NULL");
172+
return (api->start_wakeup_timer(dev, wut_id));
173+
}
174+
175+
/**
176+
* @brief Stop wake up timer
177+
*
178+
* @param dev Pointeur to the device instance
179+
* @param wut_id Wake up timer id
180+
*
181+
* @retval 0 On success.
182+
* @retval -ENOTSUP If request is not supported.
183+
* @retval -EINVAL If wut_id is invalid.
184+
*/
185+
__syscall int rtc_stop_wakeup_timer(const struct device *dev, enum rtc_wakeup_id wut_id);
186+
static inline int z_impl_rtc_stop_wakeup_timer(const struct device *dev, enum rtc_wakeup_id wut_id)
187+
{
188+
const struct rtc_driver_api *api = dev->api;
189+
190+
__ASSERT(api->print, "Callback pointer should not be NULL");
191+
return (api->stop_wakeup_timer(dev, wut_id));
192+
}
193+
194+
/**
195+
* @brief Set alarm
196+
*
197+
* @param dev Pointeur to the device instance
198+
* @param alarm Alarm parameters
199+
* @param alarm_id Alarm id
200+
*
201+
* @retval 0 On success.
202+
* @retval -ENOTSUP If request is not supported.
203+
* @retval -EINVAL If alarm_id is invalid.
204+
*/
205+
__syscall int rtc_set_alarm(const struct device *dev, struct rtc_alarm alarm, enum rtc_alarm_id alarm_id);
206+
static inline int z_impl_rtc_set_alarm(const struct device *dev, struct rtc_alarm alarm, enum rtc_alarm_id alarm_id)
207+
{
208+
const struct rtc_driver_api *api = dev->api;
209+
210+
__ASSERT(api->print, "Callback pointer should not be NULL");
211+
return (api->set_alarm(dev, alarm, alarm_id));
212+
}
213+
214+
/**
215+
* @brief Start alarm
216+
*
217+
* @param dev Pointeur to the device instance
218+
* @param alarm_id Alarm id
219+
*
220+
* @retval 0 On success.
221+
* @retval -ENOTSUP If request is not supported.
222+
* @retval -EINVAL If alarm_id is invalid.
223+
*/
224+
__syscall int rtc_start_alarm(const struct device *dev, enum rtc_alarm_id alarm_id);
225+
static inline int z_impl_rtc_start_alarm(const struct device *dev, enum rtc_alarm_id alarm_id)
226+
{
227+
const struct rtc_driver_api *api = dev->api;
228+
229+
__ASSERT(api->print, "Callback pointer should not be NULL");
230+
return (api->start_alarm(dev, alarm_id));
231+
}
232+
233+
/**
234+
* @brief Stop alarm
235+
*
236+
* @param dev Pointeur to the device instance
237+
* @param alarm_id Alarm id
238+
*
239+
* @retval 0 On success.
240+
* @retval -ENOTSUP If request is not supported.
241+
* @retval -EINVAL If alarm_id is invalid.
242+
*/
243+
__syscall int rtc_stop_alarm(const struct device *dev, enum rtc_alarm_id alarm_id);
244+
static inline int z_impl_rtc_stop_alarm(const struct device *dev, enum rtc_alarm_id alarm_id)
245+
{
246+
const struct rtc_driver_api *api = dev->api;
247+
248+
__ASSERT(api->print, "Callback pointer should not be NULL");
249+
return (api->stop_alarm(dev, alarm_id));
250+
}
251+
252+
/**
253+
* @}
254+
*/
255+
256+
#ifdef __cplusplus
257+
}
258+
#endif
259+
260+
#include <syscalls/rtc.h>
261+
262+
#endif /* ZEPHYR_INCLUDE_DRIVERS_RTC_H_ */

0 commit comments

Comments
 (0)