caffeine-hal 0.6.6
A Header-Defined Interface c library, it provides the hal layer for the Caffeine framework
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
cfn_hal_rtc.h File Reference

Real-Time Clock (RTC) HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_types.h"
#include <time.h>

Go to the source code of this file.

Data Structures

struct  cfn_hal_rtc_phy_t
 RTC hardware physical mapping. More...
 
struct  cfn_hal_rtc_config_t
 RTC configuration structure. More...
 
struct  cfn_hal_rtc_api_s
 RTC Virtual Method Table (VMT). More...
 

Typedefs

typedef struct tm cfn_hal_rtc_time_t
 RTC time representation (std tm).
 
typedef struct cfn_hal_rtc_s cfn_hal_rtc_t
 
typedef struct cfn_hal_rtc_api_s cfn_hal_rtc_api_t
 
typedef void(* cfn_hal_rtc_callback_t) (cfn_hal_rtc_t *driver, uint32_t event_mask, uint32_t error_mask, uint32_t id, void *user_arg)
 RTC callback signature.
 

Enumerations

enum  cfn_hal_rtc_event_t {
  CFN_HAL_RTC_EVENT_NONE = 0 , CFN_HAL_RTC_EVENT_ALARM = CFN_HAL_BIT(0) , CFN_HAL_RTC_EVENT_WAKEUP = CFN_HAL_BIT(1) , CFN_HAL_RTC_EVENT_TIMESTAMP = CFN_HAL_BIT(2) ,
  CFN_HAL_RTC_EVENT_TAMPER = CFN_HAL_BIT(3)
}
 RTC nominal event flags. More...
 
enum  cfn_hal_rtc_error_t { CFN_HAL_RTC_ERROR_NONE = 0 , CFN_HAL_RTC_ERROR_INIT = CFN_HAL_BIT(0) , CFN_HAL_RTC_ERROR_GENERAL = CFN_HAL_BIT(1) }
 RTC exception error flags. More...
 
enum  cfn_hal_rtc_config_format_t { CFN_HAL_RTC_CONFIG_FORMAT_12H , CFN_HAL_RTC_CONFIG_FORMAT_24H , CFN_HAL_RTC_CONFIG_FORMAT_MAX }
 RTC time format. More...
 
enum  cfn_hal_rtc_config_mode_t { CFN_HAL_RTC_CONFIG_MODE_BCD , CFN_HAL_RTC_CONFIG_MODE_BINARY , CFN_HAL_RTC_CONFIG_MODE_BINARY_BCD , CFN_HAL_RTC_CONFIG_MODE_MAX }
 RTC clocking mode. More...
 

Functions

 CFN_HAL_VMT_CHECK (struct cfn_hal_rtc_api_s)
 
 CFN_HAL_CREATE_DRIVER_TYPE (rtc, cfn_hal_rtc_config_t, cfn_hal_rtc_api_t, cfn_hal_rtc_phy_t, cfn_hal_rtc_callback_t)
 
CFN_HAL_INLINE void cfn_hal_rtc_populate (cfn_hal_rtc_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_rtc_api_t *api, const cfn_hal_rtc_phy_t *phy, const cfn_hal_rtc_config_t *config, cfn_hal_rtc_callback_t callback, void *user_arg)
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_validate (const cfn_hal_rtc_t *driver, const cfn_hal_rtc_config_t *config)
 Validates the RTC configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_init (cfn_hal_rtc_t *driver)
 Initializes the RTC driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_deinit (cfn_hal_rtc_t *driver)
 Deinitializes the RTC driver.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_set (cfn_hal_rtc_t *driver, const cfn_hal_rtc_config_t *config)
 Sets the RTC configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_get (cfn_hal_rtc_t *driver, cfn_hal_rtc_config_t *config)
 Gets the current RTC configuration.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_callback_register (cfn_hal_rtc_t *driver, const cfn_hal_rtc_callback_t callback, void *user_arg)
 Registers a callback for RTC events and errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_power_state_set (cfn_hal_rtc_t *driver, cfn_hal_power_state_t state)
 Sets the RTC power state.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_enable (cfn_hal_rtc_t *driver, uint32_t event_mask)
 Enables one or more RTC nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_disable (cfn_hal_rtc_t *driver, uint32_t event_mask)
 Disables one or more RTC nominal events.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_get (cfn_hal_rtc_t *driver, uint32_t *event_mask)
 Retrieves the current RTC nominal event status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_enable (cfn_hal_rtc_t *driver, uint32_t error_mask)
 Enables one or more RTC exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_disable (cfn_hal_rtc_t *driver, uint32_t error_mask)
 Disables one or more RTC exception errors.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_get (cfn_hal_rtc_t *driver, uint32_t *error_mask)
 Retrieves the current RTC exception error status.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_set_time (cfn_hal_rtc_t *driver, cfn_hal_rtc_time_t *time)
 Sets the RTC current wall-clock time.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_get_time (cfn_hal_rtc_t *driver, cfn_hal_rtc_time_t *time)
 Retrieves the current wall-clock time from the RTC.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_set_alarm (cfn_hal_rtc_t *driver, uint32_t id, cfn_hal_rtc_time_t *time)
 Configures an alarm event for a specific time.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_get_alarm (cfn_hal_rtc_t *driver, uint32_t id, bool *elapsed, cfn_hal_rtc_time_t *time)
 Retrieves configuration and status of a specific alarm.
 
CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_stop_alarm (cfn_hal_rtc_t *driver, uint32_t id)
 Disables a previously configured alarm.
 
cfn_hal_error_code_t cfn_hal_rtc_construct (cfn_hal_rtc_t *driver, const cfn_hal_rtc_config_t *config, const cfn_hal_rtc_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_rtc_callback_t callback, void *user_arg)
 
cfn_hal_error_code_t cfn_hal_rtc_destruct (cfn_hal_rtc_t *driver)
 

Detailed Description

Real-Time Clock (RTC) HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

◆ cfn_hal_rtc_api_t

◆ cfn_hal_rtc_callback_t

typedef void(* cfn_hal_rtc_callback_t) (cfn_hal_rtc_t *driver, uint32_t event_mask, uint32_t error_mask, uint32_t id, void *user_arg)

RTC callback signature.

Parameters
driverPointer to the RTC driver instance.
event_maskMask of triggered nominal events.
error_maskMask of triggered exception errors.
idIdentifier of the source (e.g., Alarm index).
user_argUser-defined argument passed during registration.

◆ cfn_hal_rtc_t

typedef struct cfn_hal_rtc_s cfn_hal_rtc_t

◆ cfn_hal_rtc_time_t

typedef struct tm cfn_hal_rtc_time_t

RTC time representation (std tm).

Enumeration Type Documentation

◆ cfn_hal_rtc_config_format_t

RTC time format.

Enumerator
CFN_HAL_RTC_CONFIG_FORMAT_12H 

12-hour clock (AM/PM)

CFN_HAL_RTC_CONFIG_FORMAT_24H 

24-hour clock

CFN_HAL_RTC_CONFIG_FORMAT_MAX 

◆ cfn_hal_rtc_config_mode_t

RTC clocking mode.

Enumerator
CFN_HAL_RTC_CONFIG_MODE_BCD 

Binary Coded Decimal format

CFN_HAL_RTC_CONFIG_MODE_BINARY 

Standard binary format

CFN_HAL_RTC_CONFIG_MODE_BINARY_BCD 

Mixed mode support

CFN_HAL_RTC_CONFIG_MODE_MAX 

◆ cfn_hal_rtc_error_t

RTC exception error flags.

Enumerator
CFN_HAL_RTC_ERROR_NONE 
CFN_HAL_RTC_ERROR_INIT 

Synchronization or oscillator error

CFN_HAL_RTC_ERROR_GENERAL 

General hardware error

◆ cfn_hal_rtc_event_t

RTC nominal event flags.

Enumerator
CFN_HAL_RTC_EVENT_NONE 
CFN_HAL_RTC_EVENT_ALARM 

Alarm time reached

CFN_HAL_RTC_EVENT_WAKEUP 

Periodic wakeup timer event

CFN_HAL_RTC_EVENT_TIMESTAMP 

External timestamp capture event

CFN_HAL_RTC_EVENT_TAMPER 

Security tamper event

Function Documentation

◆ CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE ( rtc  ,
cfn_hal_rtc_config_t  ,
cfn_hal_rtc_api_t  ,
cfn_hal_rtc_phy_t  ,
cfn_hal_rtc_callback_t   
)

◆ cfn_hal_rtc_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_callback_register ( cfn_hal_rtc_t driver,
const cfn_hal_rtc_callback_t  callback,
void *  user_arg 
)

Registers a callback for RTC events and errors.

Parameters
driverPointer to the RTC driver instance.
callbackThe callback function to register.
user_argUser-defined argument passed to the callback.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_get ( cfn_hal_rtc_t driver,
cfn_hal_rtc_config_t config 
)

Gets the current RTC configuration.

Parameters
driverPointer to the RTC driver instance.
config[out] Pointer to store the configuration.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_set ( cfn_hal_rtc_t driver,
const cfn_hal_rtc_config_t config 
)

Sets the RTC configuration.

Parameters
driverPointer to the RTC driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_config_validate ( const cfn_hal_rtc_t driver,
const cfn_hal_rtc_config_t config 
)

Validates the RTC configuration.

Parameters
driverPointer to the RTC driver instance.
configPointer to the configuration structure.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_construct()

cfn_hal_error_code_t cfn_hal_rtc_construct ( cfn_hal_rtc_t driver,
const cfn_hal_rtc_config_t config,
const cfn_hal_rtc_phy_t phy,
struct cfn_hal_clock_s *  clock,
void *  dependency,
cfn_hal_rtc_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_rtc_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_deinit ( cfn_hal_rtc_t driver)

Deinitializes the RTC driver.

Parameters
driverPointer to the RTC driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_destruct()

cfn_hal_error_code_t cfn_hal_rtc_destruct ( cfn_hal_rtc_t driver)

◆ cfn_hal_rtc_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_disable ( cfn_hal_rtc_t driver,
uint32_t  error_mask 
)

Disables one or more RTC exception errors.

Parameters
driverPointer to the RTC driver instance.
error_maskMask of errors to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_enable ( cfn_hal_rtc_t driver,
uint32_t  error_mask 
)

Enables one or more RTC exception errors.

Parameters
driverPointer to the RTC driver instance.
error_maskMask of errors to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_error_get ( cfn_hal_rtc_t driver,
uint32_t *  error_mask 
)

Retrieves the current RTC exception error status.

Parameters
driverPointer to the RTC driver instance.
error_mask[out] Pointer to store the error mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_disable ( cfn_hal_rtc_t driver,
uint32_t  event_mask 
)

Disables one or more RTC nominal events.

Parameters
driverPointer to the RTC driver instance.
event_maskMask of events to disable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_enable ( cfn_hal_rtc_t driver,
uint32_t  event_mask 
)

Enables one or more RTC nominal events.

Parameters
driverPointer to the RTC driver instance.
event_maskMask of events to enable.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_event_get ( cfn_hal_rtc_t driver,
uint32_t *  event_mask 
)

Retrieves the current RTC nominal event status.

Parameters
driverPointer to the RTC driver instance.
event_mask[out] Pointer to store the event mask.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_get_alarm()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_get_alarm ( cfn_hal_rtc_t driver,
uint32_t  id,
bool *  elapsed,
cfn_hal_rtc_time_t time 
)

Retrieves configuration and status of a specific alarm.

Parameters
driverPointer to the RTC driver instance.
idIndex of the alarm.
elapsed[out] Set to true if the alarm has triggered.
time[out] Pointer to store the configured alarm time.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_get_time()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_get_time ( cfn_hal_rtc_t driver,
cfn_hal_rtc_time_t time 
)

Retrieves the current wall-clock time from the RTC.

Parameters
driverPointer to the RTC driver instance.
time[out] Pointer to store the current time.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_init ( cfn_hal_rtc_t driver)

Initializes the RTC driver.

Parameters
driverPointer to the RTC driver instance.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_populate()

CFN_HAL_INLINE void cfn_hal_rtc_populate ( cfn_hal_rtc_t driver,
uint32_t  peripheral_id,
struct cfn_hal_clock_s *  clock,
void *  dependency,
const cfn_hal_rtc_api_t api,
const cfn_hal_rtc_phy_t phy,
const cfn_hal_rtc_config_t config,
cfn_hal_rtc_callback_t  callback,
void *  user_arg 
)

◆ cfn_hal_rtc_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_power_state_set ( cfn_hal_rtc_t driver,
cfn_hal_power_state_t  state 
)

Sets the RTC power state.

Parameters
driverPointer to the RTC driver instance.
stateTarget power state.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_set_alarm()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_set_alarm ( cfn_hal_rtc_t driver,
uint32_t  id,
cfn_hal_rtc_time_t time 
)

Configures an alarm event for a specific time.

Parameters
driverPointer to the RTC driver instance.
idIndex of the alarm to set.
timePointer to the structure containing the alarm time.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_set_time()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_set_time ( cfn_hal_rtc_t driver,
cfn_hal_rtc_time_t time 
)

Sets the RTC current wall-clock time.

Parameters
driverPointer to the RTC driver instance.
timePointer to the structure containing the new time.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ cfn_hal_rtc_stop_alarm()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_rtc_stop_alarm ( cfn_hal_rtc_t driver,
uint32_t  id 
)

Disables a previously configured alarm.

Parameters
driverPointer to the RTC driver instance.
idIndex of the alarm to stop.
Returns
CFN_HAL_ERROR_OK on success, or a specific error code on failure.

◆ CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK ( struct cfn_hal_rtc_api_s  )