pm.h

/*
 * Copyright (C) 2026 Kamil Lulko <kamil.lulko@gmail.com>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * This file is part of oveRTOS.
 */
 
#ifndef OVE_PM_H
#define OVE_PM_H
 
#include "ove/types.h"
#include "ove/gpio.h"
#include "ove_config.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ── Enumerations ───────────────────────────────────────────────────── */
 
typedef enum {
    OVE_PM_STATE_ACTIVE     = 0, 
    OVE_PM_STATE_IDLE       = 1, 
    OVE_PM_STATE_STANDBY    = 2, 
    OVE_PM_STATE_DEEP_SLEEP = 3, 
    OVE_PM_STATE_COUNT      = 4,
} ove_pm_state_t;
 
typedef enum {
    OVE_PM_WAKE_GPIO  = 0, 
    OVE_PM_WAKE_TIMER = 1, 
    OVE_PM_WAKE_UART  = 2, 
    OVE_PM_WAKE_RTC   = 3, 
} ove_pm_wake_type_t;
 
typedef enum {
    OVE_PM_DOMAIN_RADIO   = 0,
    OVE_PM_DOMAIN_SENSOR  = 1,
    OVE_PM_DOMAIN_DISPLAY = 2,
    OVE_PM_DOMAIN_AUDIO   = 3,
    OVE_PM_DOMAIN_STORAGE = 4,
    OVE_PM_DOMAIN_COMMS   = 5,
    OVE_PM_DOMAIN_USER0   = 6,
    OVE_PM_DOMAIN_USER1   = 7,
    OVE_PM_DOMAIN_COUNT   = 8,
} ove_pm_domain_t;
 
typedef enum {
    OVE_PM_EVENT_PRE_SLEEP = 0, 
    OVE_PM_EVENT_POST_WAKE = 1, 
} ove_pm_event_t;
 
/* ── Structures ─────────────────────────────────────────────────────── */
 
struct ove_pm_cfg {
    uint32_t idle_threshold_ms;       
    uint32_t standby_threshold_ms;    
    uint32_t deep_sleep_threshold_ms; 
};
 
struct ove_pm_wake_src {
    ove_pm_wake_type_t type; 
    union {
        struct {
            unsigned int port;
            unsigned int pin;
            ove_gpio_irq_mode_t edge;
        } gpio;               
        struct {
            uint32_t timeout_ms;
        } timer;              
        struct {
            unsigned int instance;
        } uart;               
        struct {
            uint32_t alarm_ms;
        } rtc;                
    };
};
 
struct ove_pm_stats {
    uint64_t time_in_state_us[OVE_PM_STATE_COUNT]; 
    uint32_t transition_count[OVE_PM_STATE_COUNT];  
    uint64_t total_runtime_us;                      
    uint32_t active_pct_x100;                       
};
 
/* ── Callback types ─────────────────────────────────────────────────── */
 
typedef ove_pm_state_t (*ove_pm_policy_fn)(ove_pm_state_t current,
                       uint32_t idle_ms,
                       uint32_t next_timeout_ms,
                       void *user_data);
 
typedef void (*ove_pm_notify_fn)(ove_pm_event_t event,
                 ove_pm_state_t from_state,
                 ove_pm_state_t to_state,
                 void *user_data);
 
/* ── Public API ─────────────────────────────────────────────────────── */
 
#ifdef CONFIG_OVE_PM
 
int ove_pm_init(const struct ove_pm_cfg *cfg);
 
void ove_pm_deinit(void);
 
int ove_pm_set_state(ove_pm_state_t state);
 
ove_pm_state_t ove_pm_get_state(void);
 
void ove_pm_activity(void);
 
int ove_pm_wake_register(const struct ove_pm_wake_src *src);
 
int ove_pm_wake_unregister(const struct ove_pm_wake_src *src);
 
int ove_pm_domain_request(ove_pm_domain_t domain);
 
int ove_pm_domain_release(ove_pm_domain_t domain);
 
int ove_pm_domain_get_refcount(ove_pm_domain_t domain);
 
int ove_pm_set_policy(ove_pm_policy_fn policy, void *user_data);
 
int ove_pm_notify_register(ove_pm_notify_fn cb, void *user_data);
 
int ove_pm_notify_unregister(ove_pm_notify_fn cb, void *user_data);
 
int ove_pm_get_stats(struct ove_pm_stats *stats);
 
void ove_pm_reset_stats(void);
 
int ove_pm_set_budget(uint32_t target_low_power_pct_x100);
 
int ove_pm_get_budget_status(uint32_t *actual_pct_x100);
 
void ove_pm_idle_process(void);
 
#else /* !CONFIG_OVE_PM */
 
static inline int            ove_pm_init(const struct ove_pm_cfg *c) { (void)c; return OVE_ERR_NOT_SUPPORTED; }
static inline void           ove_pm_deinit(void) {}
static inline int            ove_pm_set_state(ove_pm_state_t s) { (void)s; return OVE_ERR_NOT_SUPPORTED; }
static inline ove_pm_state_t ove_pm_get_state(void) { return OVE_PM_STATE_ACTIVE; }
static inline void           ove_pm_activity(void) {}
static inline int            ove_pm_wake_register(const struct ove_pm_wake_src *s) { (void)s; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_wake_unregister(const struct ove_pm_wake_src *s) { (void)s; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_domain_request(ove_pm_domain_t d) { (void)d; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_domain_release(ove_pm_domain_t d) { (void)d; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_domain_get_refcount(ove_pm_domain_t d) { (void)d; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_set_policy(ove_pm_policy_fn p, void *u) { (void)p; (void)u; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_notify_register(ove_pm_notify_fn c, void *u) { (void)c; (void)u; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_notify_unregister(ove_pm_notify_fn c, void *u) { (void)c; (void)u; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_get_stats(struct ove_pm_stats *s) { (void)s; return OVE_ERR_NOT_SUPPORTED; }
static inline void           ove_pm_reset_stats(void) {}
static inline int            ove_pm_set_budget(uint32_t t) { (void)t; return OVE_ERR_NOT_SUPPORTED; }
static inline int            ove_pm_get_budget_status(uint32_t *a) { (void)a; return OVE_ERR_NOT_SUPPORTED; }
static inline void           ove_pm_idle_process(void) {}
 
#endif /* CONFIG_OVE_PM */
 
#ifdef __cplusplus
}
#endif
 
 
#endif /* OVE_PM_H */