/* libhw/generic/alarmclock.h - Device-independent alarmclock definitions
 *
 * Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

#ifndef _LIBHW_GENERIC_ALARMCLOCK_H_
#define _LIBHW_GENERIC_ALARMCLOCK_H_

#include <stdbool.h> /* for bool */
#include <stdint.h>  /* for uint{n}_t and UINT{n}_C */

#include <libmisc/private.h>
#include <libobj/obj.h>

/* Useful constants ***********************************************************/

#define NS_PER_S UINT64_C(1000000000) /* needs at least log₂(10⁹) ≈ 29.9 bits */
#define US_PER_S UINT64_C(1000000)    /* needs at least log₂(10⁶) ≈ 19.9 bits */
#define MS_PER_S UINT64_C(1000)       /* needs at least log₂(10³) ≈  9.9 bits */

/* Structs ********************************************************************/

struct alarmclock_trigger;
struct alarmclock_trigger {
	BEGIN_PRIVATE(LIBHW_GENERIC_ALARMCLOCK_H)
	void                            *alarmclock;
	struct alarmclock_trigger       *prev, *next;

	uint64_t                         fire_at_ns;
	void                             (*cb)(void *);
	void                            *cb_arg;
	END_PRIVATE(LIBHW_GENERIC_ALARMCLOCK_H)
};

/* Interface ******************************************************************/

#define alarmclock_LO_IFACE                                            \
	/**                                                            \
	 * (2⁶⁴-1 nanoseconds is more than 500 years; there is little  \
	 * risk of this overflowing)                                   \
	 */                                                            \
	LO_FUNC(uint64_t, get_time_ns)                                 \
                                                                       \
	/**                                                            \
	 * Returns true on error.                                      \
	 *                                                             \
	 * Implementations may return an error if fire_at_ns is more   \
	 * than UINT32_MAX µs (72 minutes) in the future.              \
	 *                                                             \
	 * If fire_at_ns is in the past, then it will fire             \
	 * immediately.                                                \
	 */                                                            \
	LO_FUNC(bool, add_trigger, struct alarmclock_trigger *trigger, \
	                           uint64_t   fire_at_ns,              \
	                           void       (*cb)(void *),           \
	                           void      *cb_arg)                  \
                                                                       \
	LO_FUNC(void, del_trigger, struct alarmclock_trigger *trigger)
LO_INTERFACE(alarmclock)

/* Utilities ******************************************************************/

void alarmclock_sleep_until_ns(lo_interface alarmclock clock, uint64_t abstime_ns);

static inline void alarmclock_sleep_for_ns(lo_interface alarmclock clock, uint64_t delta_ns) {
	alarmclock_sleep_until_ns(clock, LO_CALL(clock, get_time_ns) + delta_ns);
}

static inline void alarmclock_sleep_for_us(lo_interface alarmclock clock, uint64_t delta_us) {
	alarmclock_sleep_for_ns(clock, delta_us * (NS_PER_S/US_PER_S));
}

static inline void alarmclock_sleep_for_ms(lo_interface alarmclock clock, uint64_t delta_ms) {
	alarmclock_sleep_for_ns(clock, delta_ms * (NS_PER_S/MS_PER_S));
}

static inline void alarmclock_sleep_for_s(lo_interface alarmclock clock, uint64_t delta_s) {
	alarmclock_sleep_for_ns(clock, delta_s * NS_PER_S);
}

/* Globals ********************************************************************/

extern lo_interface alarmclock bootclock;

#define sleep_until_ns(t) alarmclock_sleep_until_ns(bootclock, t)
#define sleep_for_ns(t)   alarmclock_sleep_for_ns(bootclock, t)
#define sleep_for_us(t)   alarmclock_sleep_for_us(bootclock, t)
#define sleep_for_ms(t)   alarmclock_sleep_for_ms(bootclock, t)
#define sleep_for_s(t)    alarmclock_sleep_for_s(bootclock, t)

#endif /* _LIBHW_GENERIC_ALARMCLOCK_H_ */