一、前言

RT-Thread 的 alarm 是系統(tǒng)提供的鬧鐘設(shè)備接口，提供了一系列用于管理定時(shí)事件的 API。然而，在實(shí)際使用過程中，遇到了一些與時(shí)間處理相關(guān)的問題。本文將圍繞這些問題展開分析，并提出對(duì)應(yīng)的解決方案。

二、問題點(diǎn)

在使用先楫平臺(tái)的 drv_rtc 驅(qū)動(dòng)時(shí)，發(fā)現(xiàn)兩個(gè)典型問題：

使用 local_time_r 設(shè)置鬧鐘時(shí)間時(shí)無法觸發(fā)回調(diào)函數(shù)

使用 gmtime_r 設(shè)置后雖然能觸發(fā)回調(diào)，但通過 list_alarm 命令打印出的鬧鐘時(shí)間顯示不正確。

例如：設(shè)置為 1719 的本地時(shí)間，實(shí)際輸出卻為 919，存在 8 小時(shí)的時(shí)間差。

這不單單在先楫平臺(tái)有所體現(xiàn)，在其他平臺(tái)比如STM32等都有類似現(xiàn)象。

三、原因分析

在解析原因之前，需要了解下rtthread對(duì)于ctime的實(shí)現(xiàn)。

（一）ctime相關(guān)接口的區(qū)別

在rtthread的rtc和alarm驅(qū)動(dòng)中，需要調(diào)用ctime的各類時(shí)間函數(shù)，其中最主要的是時(shí)間接口區(qū)別是：

local_time和local_time_t是將時(shí)間戳(time_t)轉(zhuǎn)換本地時(shí)間函數(shù)，比如設(shè)置時(shí)區(qū)為東八區(qū)，那么相比UTC時(shí)間就會(huì)多8個(gè)小時(shí)。

gmtime和gmtime_r是將時(shí)間戳轉(zhuǎn)換為UTC時(shí)間。

（二）rtthread的時(shí)區(qū)支持

考慮到嵌入式的場(chǎng)景應(yīng)用，rtthread采用的是輕量級(jí)的時(shí)區(qū)支持，沒有支持完整的時(shí)區(qū)數(shù)據(jù)庫。

默認(rèn)的時(shí)區(qū)是東八區(qū)（北京時(shí)間）

代碼宏是RT_LIBC_USING_LIGHT_TZ_DST，對(duì)應(yīng)的kconfig對(duì)應(yīng)以下，如果需要支持其他時(shí)區(qū)時(shí)間，可以改變以下配置。

（三）rtthread的時(shí)間轉(zhuǎn)換支持

在rtthread的時(shí)區(qū)支持上，主要影響localtime和mktime的行為，localtime_r和localtime會(huì)根據(jù)時(shí)區(qū)時(shí)間做偏移轉(zhuǎn)換為本地時(shí)間。

mktime會(huì)根據(jù)時(shí)區(qū)時(shí)間偏移將本地時(shí)間轉(zhuǎn)換為UTC的時(shí)間戳。

在rtthread的alarm實(shí)現(xiàn)中，涉及到時(shí)間戳轉(zhuǎn)換日歷時(shí)間的接口都使用了UTC時(shí)間的函數(shù)接口gmtime_r，而當(dāng)觸發(fā)鬧鐘更新的時(shí)候，需要使用鬧鐘時(shí)間與當(dāng)前時(shí)間做判斷以便是否到達(dá)鬧鐘觸發(fā)事件，如果此時(shí)鬧鐘時(shí)間使用的是local_time，那么判斷將永遠(yuǎn)不成立，也就無法觸發(fā)鬧鐘回調(diào)。而如果同樣使用的是gmtime，那么時(shí)間單位是一致的，就會(huì)觸發(fā)鬧鐘回調(diào)，但打印的鬧鐘列表是基于UTC時(shí)間。

由此可知：在 Alarm 模塊的實(shí)現(xiàn)中，時(shí)間戳轉(zhuǎn)日歷時(shí)間的操作均使用的是 UTC 時(shí)間函數(shù)（gmtime_r）。如果用戶傳入的是基于本地時(shí)間的結(jié)構(gòu)體，則因未統(tǒng)一轉(zhuǎn)換而造成比較失敗，導(dǎo)致無法觸發(fā)回調(diào)。

三、修復(fù)

根據(jù)上述原因，問題的根本在于Alarm 模塊未正確支持本地時(shí)間的判斷邏輯。針對(duì)這一問題，社區(qū)已在最新主線代碼中進(jìn)行了修復(fù)。

在對(duì)應(yīng)的時(shí)間戳轉(zhuǎn)換日歷時(shí)間上加個(gè)宏定義來切換為本地時(shí)間計(jì)算還是UTC時(shí)間計(jì)算即可。

Kconfig配置上加了RT_ALARM_USING_LOCAL_TIME配置宏，如果打開就是基于本地時(shí)間來計(jì)算。默認(rèn)不使能。

RT-Thread Components -> Device Drivers -> Using RTC device drivers-> Using RTC alarm -> Using local time for the alarm calculation

如果使能該配置，那么鬧鐘就是以本地時(shí)間local_time為準(zhǔn)

如果禁能該配置，那么鬧鐘就是以UTC時(shí)間gmtime為準(zhǔn)。

在使用rt_alarm_create增加鬧鐘時(shí)，配置的鬧鐘時(shí)間需要區(qū)分來，即可正常工作

在list_alarm命令中加入了timezone，查找鬧鐘列表更加直觀

1、使用UTC時(shí)間的alarm

2、使用東八區(qū)的本地時(shí)間的alarm

四、BSP的drv_rtc驅(qū)動(dòng)注意點(diǎn)

1. 實(shí)現(xiàn) set_timestamp 時(shí)注意時(shí)間轉(zhuǎn)換

當(dāng)啟用了 RT_ALARM_USING_LOCAL_TIME 宏定義時(shí)，必須使用 local_time 進(jìn)行時(shí)間轉(zhuǎn)換，否則可能導(dǎo)致時(shí)間偏差。

2、設(shè)置鬧鐘時(shí)必須完整填寫年月日字段

由于 RT_ALARM_ONESHOT 模式下，系統(tǒng)會(huì)將鬧鐘時(shí)間轉(zhuǎn)換為時(shí)間戳進(jìn)行比較，因此必須提供完整的日歷時(shí)間結(jié)構(gòu)（包括年、月、日）。否則可能因字段缺失導(dǎo)致匹配失敗。

而先楫只需要從鬧鐘寄存器中獲取即可。

五、總結(jié)

本文圍繞 RT-Thread 中的Alarm（鬧鐘）設(shè)備驅(qū)動(dòng)展開討論，結(jié)合先楫平臺(tái)的實(shí)際開發(fā)經(jīng)驗(yàn)，深入分析了在使用 rt_alarm_create 設(shè)置本地時(shí)間鬧鐘時(shí)遇到的問題，并從底層機(jī)制出發(fā)，解釋了問題根源，最終提出了有效的解決方案。

核心結(jié)論如下：

Alarm 子系統(tǒng)默認(rèn)使用 UTC 時(shí)間函數(shù)（如 gmtime_r）進(jìn)行時(shí)間戳與日歷時(shí)間的轉(zhuǎn)換；

若傳入本地時(shí)間結(jié)構(gòu)體但未統(tǒng)一轉(zhuǎn)換，會(huì)導(dǎo)致比較失敗，從而無法觸發(fā)鬧鐘回調(diào)；

rtthread社區(qū)已在主線中引入 RT_ALARM_USING_LOCAL_TIME 宏定義，支持基于本地時(shí)間的鬧鐘行為；

在使用 Alarm 功能時(shí)，開發(fā)者需關(guān)注系統(tǒng)時(shí)區(qū)設(shè)置以及是否啟用本地時(shí)間模式，以確保鬧鐘行為符合預(yù)期。

通過本文的分析與實(shí)踐，希望可以幫助開發(fā)者更好地理解和使用 RT-Thread 的 Alarm 子系統(tǒng)，提升嵌入式設(shè)備中定時(shí)任務(wù)管理的靈活性與準(zhǔn)確性。