8 File kernel/include/rtc.h

8.1 Structures and Types

8.2 Functions

8.3 Macros

8.4 Structures and Types Documentation

8.4.1 struct bea_datetime

Represents a single point in time in the Gregorian calendar. Years begin at 2000 (since the RTC hardware can’t represent anything earlier than that), and hours are in 24-hour time. Always in UTC because the IANA timezone database is in itself bigger than the amount of flash we have to work with.

Variables:

• uint8_t day

• enum bea_dotw dotw

• uint8_t hour

• uint8_t minute

• enum bea_month month

• float second

• uint8_t year
  Years since 2000.

8.4.2 enum bea_dotw

Represents a day of the week in the Gregorian calendar.

enum bea_dotw {
    BEA_DOTW_MONDAY = 0,
    BEA_DOTW_TUESDAY,
    BEA_DOTW_WEDNESDAY,
    BEA_DOTW_THURSDAY,
    BEA_DOTW_FRIDAY,
    BEA_DOTW_SATURDAY,
    BEA_DOTW_SUNDAY
};

8.4.3 enum bea_month

Represents a month in the Gregorian calendar.

enum bea_month {
    BEA_MONTH_JANUARY = 0,
    BEA_MONTH_FEBRUARY,
    BEA_MONTH_MARCH,
    BEA_MONTH_APRIL,
    BEA_MONTH_MAY,
    BEA_MONTH_JUNE,
    BEA_MONTH_JULY,
    BEA_MONTH_AUGUST,
    BEA_MONTH_SEPTEMBER,
    BEA_MONTH_OCTOBER,
    BEA_MONTH_NOVEMBER,
    BEA_MONTH_DECEMBER
};

8.4.4 enum bea_rtc_clksrc

Represents a clock source for the RTC subsystem to use (see RM0434 pp. 263)

enum bea_rtc_clksrc {
    BEA_RTC_CLKSRC_LSE,
    BEA_RTC_CLKSRC_LSI,
    BEA_RTC_CLKSRC_HSE
};

8.5 Functions Documentation

8.5.1 function bea_datetime_is_valid

Checks whether a struct bea_datetime_ represents a valid point in time in the Gregorian calendar._

bool bea_datetime_is_valid (
    struct bea_datetime datetime
) 

Parameters:

• datetime The datetime to check

Returns:

true The represented datetime is valid

Returns:

false The represented datetime is invalid #### function bea_datetime_to_kstrz

Fills a buffer of at least 31 chars (please just use BEA_DATETIME_KSTRZ_LEN) with a null terminated string in BEATRIX kernel format.

void bea_datetime_to_kstrz (
    const struct bea_datetime datetime,
    char *buf
) 

The BEATRIX kernel format is loosely based on ISO and is “WDY MON DY YEAR HR:MN:SECOND UTC”, with seconds being given with 5 significant figures of precision and a decimal point.

Parameters:

• datetime The datetime to use
• buf The buffer to fill #### function bea_datetime_to_unix

converts a bea_datetime_ to a Unix timestamp (seconds since the beginning of the year 1970)_

bool bea_datetime_to_unix (
    struct bea_datetime datetime,
    uint64_t timestamp_out
) 

Parameters:

• datetime The datetime in bea_datetime format
• timestamp_out A pointer to an uninitialized uint64_t, whose value will be filled in by the function

Returns:

true The conversion was successful

Returns:

false The conversion was unsuccessful because datetime is invalid #### function bea_rtc_get_datetime

Reads the current date and time according to the RTC.

struct bea_datetime bea_rtc_get_datetime () 

Returns:

struct bea_datetime The returned date and time values #### function bea_rtc_initialize

Initialize the RTC subsystem.

bool bea_rtc_initialize (
    enum bea_rtc_clksrc clock_source,
    struct bea_datetime start_time,
    uint32_t subsec_frequency
) 

Parameters:

• clock_source Clock source for the RTC subsystem to use (see STMicroelectronics RM0434 pp. 263)
• start_time The time at initialization
• subsec_frequency The maximum frequency (in Hertz) the RTC can resolve. Validity depends on the clock source; reference page mentioned above

Returns:

true No error encountered

Returns:

false Error encountered

Todo

Add timeout for INITF flag

Add timeout for initialization completion

Add less opaque error return #### function bea_unix_to_datetime

Converts a standard Unix timestamp (seconds since the beginning of the year 1970) to a bea_datetime

bool bea_unix_to_datetime (
    uint64_t timestamp,
    struct bea_datetime *datetime_out
) 

Parameters:

• timestamp The timestamp in Unix format
• datetime_out A pointer to an uninitialized bea_datetime object, which will be filled out by the function

Returns:

true The conversion was successful

Returns:

false The conversion was unsuccessful due to a mismatch in representable ranges

8.6 Macros Documentation

8.6.1 define BEA_DATETIME_KSTRZ_LEN

##define BEA_DATETIME_KSTRZ_LEN 31

8.6.2 define BEA_RCC_BDCR_OFFSET

##define BEA_RCC_BDCR_OFFSET 0x024

8.6.3 define BEA_RTC_BASE_ADDR

##define BEA_RTC_BASE_ADDR (uint32_t *)(0x40002800)

8.6.4 define BEA_RTC_DR_OFFSET

##define BEA_RTC_DR_OFFSET 0x01

8.6.5 define BEA_RTC_ISR_OFFSET

##define BEA_RTC_ISR_OFFSET 0x03

8.6.6 define BEA_RTC_PRER_OFFSET

##define BEA_RTC_PRER_OFFSET 0x04

8.6.7 define BEA_RTC_SSR_OFFSET

##define BEA_RTC_SSR_OFFSET 0x0A

8.6.8 define BEA_RTC_TR_OFFSET

##define BEA_RTC_TR_OFFSET 0x00

8.6.9 define BEA_RTC_WPR_OFFSET

##define BEA_RTC_WPR_OFFSET 0x09