# RTC - [Overview](#section471241871165623) - [Summary](#section162759248165623) - [Files](#files) - [Data Structures](#nested-classes) - [Typedefs](#typedef-members) - [Enumerations](#enum-members) - [Functions](#func-members) - [Details](#section1063913536165623) - [Typedef](#section1614801129165623) - [RtcAlarmCallback](#gaf9932b7e647bce0503f1314bbe5eef8d) - [Enumeration Type](#section1322628777165623) - [RtcAlarmIndex](#gad7b3a575c848e2669db5e5b6f7e74330) - [Function](#section173008276165623) - [RtcAlarmInterruptEnable\(\)](#ga8b0f2951646ebd17313d905553bd8e0e) - [RtcClose\(\)](#ga395aa79ef260bfcd603ed56f9839d73b) - [RtcGetFreq\(\)](#ga766e2df8045177cd030e1133df4cba12) - [RtcOpen\(\)](#ga35004a866f23081ce2a446f1b0f88e32) - [RtcReadAlarm\(\)](#gabc4a137f0aed13e41da2db2dccc32b08) - [RtcReadReg\(\)](#gaec39316c639860a032f802628276d366) - [RtcReadTime\(\)](#gae8b242769eacd00b71eb1debce9be4de) - [RtcRegisterAlarmCallback\(\)](#ga0c42d787adde8d56a82b0c21624049d5) - [RtcReset\(\)](#ga7eb8a5ecf1058b9f90a133e2caa14573) - [RtcSetFreq\(\)](#ga17fdfb7ba3c876974cf9099aab092345) - [RtcWriteAlarm\(\)](#gaf4dd53c3e5b6c7a1766f6b15a77c96e9) - [RtcWriteReg\(\)](#gab8cc20f50b103acef06aa7887610be1c) - [RtcWriteTime\(\)](#ga7b6da87bfe9af2bcbfeebe9793876eb8) ## **Overview** **Description:** Provides standard real-time clock \(RTC\) APIs. These APIs allow you to perform operations such as reading or writing system time, reading or writing alarm time, setting alarm interrupts, registering alarm callbacks, setting the external frequency, resetting the RTC driver, and customizing RTC configurations. The RTC driver provides precise real time for the operating system \(OS\). If the OS is powered off, the RTC driver continues to keep track of the system time using an external battery. **Since:** 1.0 ## **Summary** ## Files

File Name

Description

rtc_if.h

Declares the standard RTC APIs.

## Data Structures

Data Structure Name

Description

RtcTime

Defines the RTC information.

## Typedefs

Typedef Name

Description

RtcAlarmCallback) (enum RtcAlarmIndex)

typedef int32_t(*

Defines a callback that will be invoked when an alarm is generated at the specified time.

## Enumerations

Enumeration Name

Description

RtcAlarmIndex { RTC_ALARM_INDEX_A = 0, RTC_ALARM_INDEX_B = 1 }

Enumerates alarm indexes.

## Functions

Function

Description

RtcOpen (void)

DevHandle

Opens the RTC device to obtain its handle.

RtcClose (DevHandle handle)

void

Releases a specified handle of the RTC device.

RtcReadTime (DevHandle handle, struct RtcTime *time)

int32_t

Reads time from the RTC driver.

RtcWriteTime (DevHandle handle, const struct RtcTime *time)

int32_t

Writes format-compliant time to the RTC driver.

RtcReadAlarm (DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime *time)

int32_t

Reads the RTC alarm time that was set last time.

RtcWriteAlarm (DevHandle handle, enum RtcAlarmIndex alarmIndex, const struct RtcTime *time)

int32_t

Writes the RTC alarm time based on the alarm index.

RtcRegisterAlarmCallback (DevHandle handle, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb)

int32_t

Registers RtcAlarmCallback that will be invoked when an alarm is generated at the specified time.

RtcAlarmInterruptEnable (DevHandle handle, enum RtcAlarmIndex alarmIndex, uint8_t enable)

int32_t

Enables or disables alarm interrupts.

RtcGetFreq (DevHandle handle, uint32_t *freq)

int32_t

Reads the RTC external frequency.

RtcSetFreq (DevHandle handle, uint32_t freq)

int32_t

Sets the frequency of the external crystal oscillator connected to the RTC driver.

RtcReset (DevHandle handle)

int32_t

Resets the RTC driver.

RtcReadReg (DevHandle handle, uint8_t usrDefIndex, uint8_t *value)

int32_t

Reads the configuration of a custom RTC register based on the register index.

RtcWriteReg (DevHandle handle, uint8_t usrDefIndex, uint8_t value)

int32_t

Writes the configuration of a custom RTC register based on the register index.

## **Details** ## **Typedef ** ## RtcAlarmCallback ``` typedef int32_t(* RtcAlarmCallback) (enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330)) ``` **Description:** Defines a callback that will be invoked when an alarm is generated at the specified time. ## **Enumeration Type ** ## RtcAlarmIndex ``` enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330) ``` **Description:** Enumerates alarm indexes. The alarm indexes will be used when you perform operations related to alarms.

Enumerator

Description
RTC_ALARM_INDEX_A

Index of alarm A

RTC_ALARM_INDEX_B

Index of alarm B

## **Function ** ## RtcAlarmInterruptEnable\(\) ``` int32_t RtcAlarmInterruptEnable ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330) alarmIndex, uint8_t enable ) ``` **Description:** Enables or disables alarm interrupts. Before performing alarm operations, you need to call this function to enable alarm interrupts, so that the [RtcRegisterAlarmCallback](RTC.md#ga0c42d787adde8d56a82b0c21624049d5) will be called when the alarm is not generated upon a timeout. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
alarmIndex Indicates the RTC alarm index. For details, see RtcAlarmIndex.
enable Specifies whether to enable RTC alarm interrupts. The value 1 means to enable alarm interrupts and value 0 means to disable alarm interrupts.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcClose\(\) ``` void RtcClose ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle) ``` **Description:** Releases a specified handle of the RTC device. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle to release, which is created via RtcGetHandle.
## RtcGetFreq\(\) ``` int32_t RtcGetFreq ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint32_t * freq ) ``` **Description:** Reads the RTC external frequency. This function reads the frequency of the external crystal oscillator connected to the RTC driver. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
freq Indicates the pointer to the frequency of the external crystal oscillator, in Hz.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcOpen\(\) ``` [DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) RtcOpen (void ) ``` **Description:** Opens the RTC device to obtain its handle. The OS supports only one RTC device. **Returns:** Returns [DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) if the operation is successful; returns **NULL** if the operation fails. ## RtcReadAlarm\(\) ``` int32_t RtcReadAlarm ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330) alarmIndex, struct [RtcTime](RtcTime.md) * time ) ``` **Description:** Reads the RTC alarm time that was set last time. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
alarmIndex Indicates the RTC alarm index. For details, see RtcAlarmIndex.
time Indicates the pointer to the RTC alarm time information. For details, see RtcTime.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcReadReg\(\) ``` int32_t RtcReadReg ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint8_t usrDefIndex, uint8_t * value ) ``` **Description:** Reads the configuration of a custom RTC register based on the register index. One index corresponds to one byte of the configuration value. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
usrDefIndex Indicates the index of the custom register.
value Indicates the pointer to the configuration value of the specified register index.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcReadTime\(\) ``` int32_t RtcReadTime ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, struct [RtcTime](RtcTime.md) * time ) ``` **Description:** Reads time from the RTC driver. The time information includes the year, month, day, day of the week, hour, minute, second, and millisecond. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
time Indicates the pointer to the time information read from the RTC driver. For details, see RtcTime.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcRegisterAlarmCallback\(\) ``` int32_t RtcRegisterAlarmCallback ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330) alarmIndex, [RtcAlarmCallback](RTC.md#gaf9932b7e647bce0503f1314bbe5eef8d) cb ) ``` **Description:** Registers [RtcAlarmCallback](RTC.md#gaf9932b7e647bce0503f1314bbe5eef8d) that will be invoked when an alarm is generated at the specified time. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
alarmIndex Indicates the RTC alarm index. For details, see RtcAlarmIndex.
cb Indicates the callback to register. For details, see RtcAlarmCallback.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcReset\(\) ``` int32_t RtcReset ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle) ``` **Description:** Resets the RTC driver. After the reset, the configuration registers are restored to the default values. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcSetFreq\(\) ``` int32_t RtcSetFreq ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint32_t freq ) ``` **Description:** Sets the frequency of the external crystal oscillator connected to the RTC driver. Note that the frequency must be configured in accordance with the requirements specified in the product manual of the in-use component. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
freq Indicates the frequency to set for the external crystal oscillator, in Hz.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcWriteAlarm\(\) ``` int32_t RtcWriteAlarm ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, enum [RtcAlarmIndex](RTC.md#gad7b3a575c848e2669db5e5b6f7e74330) alarmIndex, const struct [RtcTime](RtcTime.md) * time ) ``` **Description:** Writes the RTC alarm time based on the alarm index. Note that the RTC start time is 1970/01/01 Thursday 00:00:00 \(UTC\). Set the maximum value of **year** based on the requirements specified in the product manual of the in-use component. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
alarmIndex Indicates the RTC alarm index. For details, see RtcAlarmIndex.
tm Indicates the pointer to the RTC alarm time information. For details, see RtcTime.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcWriteReg\(\) ``` int32_t RtcWriteReg ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, uint8_t usrDefIndex, uint8_t value ) ``` **Description:** Writes the configuration of a custom RTC register based on the register index. One index corresponds to one byte of the configuration value. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
usrDefIndex Indicates the index of the custom register.
value Indicates the configuration value to write at the index of the register.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67). ## RtcWriteTime\(\) ``` int32_t RtcWriteTime ([DevHandle](COMMON.md#gab8c2d38e46eec50bd097a27d3d8bf041) handle, const struct [RtcTime](RtcTime.md) * time ) ``` **Description:** Writes format-compliant time to the RTC driver. Note that the RTC start time is 1970/01/01 Thursday 00:00:00 \(UTC\). Set the maximum value of **year** based on the requirements specified in the product manual of the in-use component. **Parameters:**

Name

Description
handle Indicates the pointer to the RTC device handle, which is obtained via RtcGetHandle.
time Indicates the pointer to the time information to write. For details, see RtcTime.
**Returns:** Returns **0** if the operation is successful; returns a negative value if the operation fails. For details, see [HDF\_STATUS](DriverUtils.md#ga7e01536ecbe9b17563dd3fe256202a67).