tr_rtc_driver.h File Reference

RTC driver. More...

#include <stdint.h>
#include <stdbool.h>
#include "tr_hal_rtc.h"

Include dependency graph for tr_rtc_driver.h:

Go to the source code of this file.

Functions
void	tr_rtc_driver_init (uint32_t reset_reason)
	Initialize the RTC driver and reconstruct internal state.
uint64_t	tr_rtc_get_hw_ms (void)
	Get the current hardware RTC time in milliseconds since 2000‑01‑01.
uint64_t	tr_rtc_get_uptime_ms (void)
	Get the 64‑bit monotonic uptime in milliseconds.
uint64_t	tr_rtc_wallclock_ms_get (void)
	Get the wall‑clock time (ms since 2000‑01‑01).
void	tr_rtc_wallclock_ms_set (uint64_t ms_since_2000)
	Set the wall‑clock (ms since 2000‑01‑01) using the offset model.
void	tr_rtc_calendar_get (tr_hal_rtc_date_time *date)
	Read the current hardware RTC calendar.
void	tr_rtc_calendar_set (const tr_hal_rtc_date_time *date)
	Set the hardware RTC calendar safely (preserving uptime).
void	tr_rtc_setup_alarm (uint64_t delta_ms)
	Program an RTC alarm to fire approximately delta_ms in the future.
void	tr_rtc_ms_to_calendar (uint64_t ms_since_2000, tr_hal_rtc_date_time *date)
	Convert ms‑since‑2000 to a calendar (Y/M/D h:m:s.ms).
uint64_t	tr_rtc_calendar_to_ms (const tr_hal_rtc_date_time *date)
	Convert a calendar (Y/M/D h:m:s.ms) to ms‑since‑2000.

Detailed Description

RTC driver.

Design overview

• Hardware calendar epoch: The RTC keeps calendar time starting at 2000‑01‑01 00:00:00.000 with millisecond resolution. The driver provides helpers to convert to/from a linear milliseconds‑since‑2000 domain that is used for all arithmetic.
• Monotonic uptime: A 64‑bit timer that increases monotonically during a power session and across deep‑sleep resets, and resets to 0 only on power‑on / external reset / watchdog. Internally, uptime is reconstructed as uptime = base + (now_ms - ref_ms) with (base, ref_ms) stored in retention RAM.
• Wall clock: A logical wall clock defined as wall = now_ms + wallclock_offset. The offset lives in retention RAM, so it persists across deep sleep but is cleared on cold reset. This lets applications represent “human time” without reprogramming the RTC.
• Safe calendar edits: When the calendar is set, the driver re‑anchors (base, ref_ms) to the new hardware “now” so monotonic uptime remains continuous (no forward/backward jump).
• Tickless alarm: For FreeRTOS tickless idle, an alarm is programmed for “now + delta_ms”. WFI/Sleep resumes in place; Deep‑Sleep may reset the CPU, but uptime/wall clock are reconstructed on boot from retention.

Quick start

1. Call tr_rtc_driver_init() very early in main() after you read the reset cause and before using any time APIs or starting FreeRTOS.
2. Read monotonic time via tr_rtc_get_uptime_ms() (never decreases within a power session; preserved across deep‑sleep).
3. If you need a “human” wall clock without changing the calendar, use tr_rtc_wallclock_ms_set() / tr_rtc_wallclock_ms_get().
4. If you must change the hardware calendar itself (factory/service), call tr_rtc_calendar_set(); it preserves uptime continuity.
5. For tickless idle, schedule wakeups with tr_rtc_setup_alarm().

Note

The RTC driver can be used in bare-metal applications. The only requirement is a suitable implementation of tr_hal_power_get_reset_cause(). The current implementation of tr_hal_power_get_reset_cause(), depends on the T32CZ20B bootloader.