pm.h

Go to the documentation of this file.

/*
 * 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 */