[PATCH 1/2] rtc: Add rtc_read_next_alarm() to read next expiring timer

[Mario Limonciello]

Add a new function rtc_read_next_alarm() that reads the next expiring
alarm from the RTC timerqueue. This is different from rtc_read_alarm(),
which only reads the aie_timer.

The wakealarm sysfs file programs the rtc->aie_timer, whereas the
alarmtimer suspend routine programs its own timer into the RTC timerqueue.
Both timers end up in the RTC's timerqueue, and the first expiring timer
is what gets armed in the hardware.

This new function allows code to query which alarm will actually fire
next, regardless of which subsystem programmed it. This is needed by
platform code that needs to program secondary timers based on the
actual next wakeup time.

Link: https://lore.kernel.org/all/87ed50z0le.ffs@tglx
Suggested-by: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
Assisted-by: Claude:claude-opus-4-6
Signed-off-by: Mario Limonciello <mario.limonciello@xxxxxxx>
---
 drivers/rtc/interface.c | 42 +++++++++++++++++++++++++++++++++++++++++
 include/linux/rtc.h     |  2 ++
 2 files changed, 44 insertions(+)

diff --git a/drivers/rtc/interface.c b/drivers/rtc/interface.c
index 1906f4884a834..dfcb32e272eb9 100644
--- a/drivers/rtc/interface.c
+++ b/drivers/rtc/interface.c
@@ -384,6 +384,48 @@ int __rtc_read_alarm(struct rtc_device *rtc, struct rtc_wkalrm *alarm)
 	return err;
 }
 
+/**
+ * rtc_read_next_alarm - read the next expiring alarm
+ * @rtc: RTC device
+ * @alarm: storage for the alarm information
+ *
+ * Read the next expiring alarm from the RTC timerqueue. This returns
+ * the alarm that will actually fire next, which may be different from
+ * rtc_read_alarm() if multiple timers are queued (e.g., alarmtimer
+ * and wakealarm sysfs both active).
+ *
+ * Returns 0 on success, -ENOENT if no alarm is pending, or other error.
+ */
+int rtc_read_next_alarm(struct rtc_device *rtc, struct rtc_wkalrm *alarm)
+{
+	struct timerqueue_node *next;
+	int err;
+
+	if (!rtc || !alarm)
+		return -EINVAL;
+
+	err = mutex_lock_interruptible(&rtc->ops_lock);
+	if (err)
+		return err;
+
+	next = timerqueue_getnext(&rtc->timerqueue);
+	if (!next) {
+		err = -ENOENT;
+		goto unlock;
+	}
+
+	memset(alarm, 0, sizeof(struct rtc_wkalrm));
+	alarm->time = rtc_ktime_to_tm(next->expires);
+	alarm->enabled = 1;
+	alarm->pending = 0;
+	err = 0;
+
+unlock:
+	mutex_unlock(&rtc->ops_lock);
+	return err;
+}
+EXPORT_SYMBOL_GPL(rtc_read_next_alarm);
+
 int rtc_read_alarm(struct rtc_device *rtc, struct rtc_wkalrm *alarm)
 {
 	int err;
diff --git a/include/linux/rtc.h b/include/linux/rtc.h
index 95da051fb155d..c09fc22819d0c 100644
--- a/include/linux/rtc.h
+++ b/include/linux/rtc.h
@@ -190,6 +190,8 @@ extern int rtc_set_time(struct rtc_device *rtc, struct rtc_time *tm);
 int __rtc_read_alarm(struct rtc_device *rtc, struct rtc_wkalrm *alarm);
 extern int rtc_read_alarm(struct rtc_device *rtc,
 			struct rtc_wkalrm *alrm);
+extern int rtc_read_next_alarm(struct rtc_device *rtc,
+			       struct rtc_wkalrm *alrm);
 extern int rtc_set_alarm(struct rtc_device *rtc,
 				struct rtc_wkalrm *alrm);
 extern int rtc_initialize_alarm(struct rtc_device *rtc,
-- 
2.43.0