power_mgmt.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file power_mgmt.h
 * @brief SoC power governor: frequency scaling, thermal throttle, brownout recovery, gating
 *        (PROTOCORE_ENABLE_POWER_MGMT).
 *
 * network_drivers/physical/radio_power owns the radio and server/sleep_sched decides how *long* to sleep. Neither
 * owns the SoC itself, which is where the rest of the power budget goes: the CPU clock, the die
 * temperature, and the peripherals nobody is using.
 *
 * The governor answers one question - given the current load, die temperature, and how the board
 * last reset, what should the CPU clock be right now:
 *
 *  - **Scaling.** Busy work runs at the ceiling; an idle server drops to the floor. Running a
 *    240 MHz core to poll an idle socket is the single easiest power win on this part.
 *  - **Thermal throttle.** Hot parts clock down, and the restore threshold is *lower* than the
 *    throttle threshold. Without that gap a device sitting exactly at the limit oscillates between
 *    full speed and floor forever, which is worse than either.
 *  - **Brownout recovery.** A board that just browned out is on a supply that could not hold up the
 *    last load it saw, so slamming straight back to full speed invites the same collapse and a boot
 *    loop. After a brownout reset it comes up at the floor and stays there for a settle window.
 *  - **Gating.** Blocks the firmware never uses still burn current; Bluetooth is the big one, since
 *    the controller draws power whether or not anything is connected.
 *
 * The decision is pure and takes every input explicitly - load, temperature, the brownout flag, the
 * time since boot, and the previous throttle state for the hysteresis - so the whole governor is
 * host-testable with no hardware. The binding only reads the sensors and applies the result.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_POWER_MGMT_H
#define PROTOCORE_POWER_MGMT_H
 
#include "protocore_config.h" // the entry point: protocore_types.h for the widths
 
#if PROTOCORE_ENABLE_POWER_MGMT
 
PROTOCORE_BEGIN_DECLS
 
/** @brief Governor limits. Temperatures in whole degrees C; frequencies in MHz. */
typedef struct
{
    uint16_t mhz_max;    ///< clock when there is work to do.
    uint16_t mhz_min;    ///< clock when idle, throttled, or recovering.
    uint8_t busy_pct;    ///< load at/above which the ceiling is used.
    int16_t temp_hot_c;  ///< throttle at/above this die temperature.
    int16_t temp_cool_c; ///< release the throttle at/below this one (must be < temp_hot_c).
    uint32_t recover_ms; ///< how long to stay at the floor after a brownout reset.
} PowerCfg;
 
/** @brief What the governor decided this tick. */
typedef struct
{
    uint16_t cpu_mhz;      ///< clock to apply.
    proto_bool throttled;  ///< the thermal limit is holding the clock down.
    proto_bool recovering; ///< still inside the post-brownout settle window.
} PowerPlan;
 
/** @brief What the pure plan reads. */
typedef struct
{
    const PowerCfg *cfg;      ///< the thresholds
    uint8_t load_pct;         ///< how busy the loop has been
    int16_t temp_c;           ///< the die temperature, or INT16_MIN when there is no sensor
    proto_bool brownout_boot; ///< this boot followed a brownout
    uint32_t since_boot_ms;   ///< how long it has been running
    proto_bool was_throttled; ///< the plan's own previous output, which is what gives it hysteresis
} PowerPlanArgs;
 
/** @brief The plan a call acts on, and where a report is written. */
typedef struct
{
    const PowerPlan *plan; ///< the plan an apply carries out, or a report describes
    int16_t temp_c;        ///< the temperature that report carries
    char *out;             ///< where the JSON lands
    size_t cap;            ///< how much room it has
} PowerOutArgs;
 
/**
 * @brief The CPU clock governor.
 *
 * A caller sets the members a call takes, invokes it through ::Power, and reads the outcome off the
 * same handle. The latched boot cause and the released-domain flag are behind @ref internal.
 *
 * @var PowerMgmtNs::plan_args   what the pure plan reads
 * @var PowerMgmtNs::out_args    the plan a call acts on, and where a report is written
 * @var PowerMgmtNs::cfg_out     where defaults are written
 * @var PowerMgmtNs::plan        the plan a decide produced
 * @var PowerMgmtNs::ok          a call's true/false outcome
 * @var PowerMgmtNs::n           bytes a report wrote, or 0 when it did not fit
 * @var PowerMgmtNs::temp_c      the die temperature a read reports, INT16_MIN for no sensor
 * @var PowerMgmtNs::mhz         the CPU clock a read reports
 * @var PowerMgmtNs::defaults    fill a config from the build flags
 * @var PowerMgmtNs::decide      choose a clock, reading nothing outside plan_args
 * @var PowerMgmtNs::json        serialize a plan
 * @var PowerMgmtNs::brownout    this boot followed a brownout; latched, so it stays true
 * @var PowerMgmtNs::die_temp    the die temperature, from the platform seam
 * @var PowerMgmtNs::cpu_mhz     the clock the part is running at
 * @var PowerMgmtNs::apply       set the clock a plan asks for, when it is not already there
 * @var PowerMgmtNs::gate_bt     release the radio controller's power domain
 *
 * decide takes its own previous output back in as @c plan_args.was_throttled: with one threshold a
 * part sitting at the limit would flap between ceiling and floor every tick, so once throttled it
 * holds until the die drops to the cool threshold.
 */
typedef struct
{
    PowerPlanArgs plan_args;
    PowerOutArgs out_args;
    PowerCfg *cfg_out;
    PowerPlan plan;
    proto_bool ok;
    size_t n;
    int16_t temp_c;
    uint16_t mhz;
#if PROTOCORE_HAS_VENDOR_PM
#endif
#if PROTOCORE_HAS_VENDOR_BT
#endif
} PowerVars;
 
/** @brief The operands and the outcome. */
extern PowerVars PowerV;
 
/** @brief The entries. */
typedef struct
{
    void (*const defaults)(uint8_t *work);
    void (*const decide)(uint8_t *work);
    void (*const json)(uint8_t *work);
    void (*const brownout)(uint8_t *work);
    void (*const die_temp)(uint8_t *work);
    void (*const cpu_mhz)(uint8_t *work);
    void (*const apply)(uint8_t *work);
    void (*const gate_bt)(uint8_t *work);
} PowerMgmtNs;
 
// What the table binds, defined once in the .c and taking one parameter each: everything
// else an entry needs is an operand in PowerV or a region of the borrow at a fixed offset.
void protocore_power_defaults(uint8_t *work);
void protocore_power_decide(uint8_t *work);
void protocore_power_json(uint8_t *work);
#if PROTOCORE_HAS_VENDOR_PM
void protocore_power_brownout(uint8_t *work);
void protocore_power_die_temp(uint8_t *work);
void protocore_power_cpu_mhz(uint8_t *work);
void protocore_power_apply(uint8_t *work);
#endif
#if PROTOCORE_HAS_VENDOR_BT
void protocore_power_gate_bt(uint8_t *work);
#endif
 
// `static const`, initialised HERE rather than `extern` against a definition in the .c: a
// const object whose initializer every translation unit can see is a COMPILE-TIME FACT, so
// `Power.defaults(work)` resolves to a named function and becomes a DIRECT call. An extern table
// leaves the call indirect and the symbol live at every level, -O2 -flto included.
static const PowerMgmtNs Power __attribute__((unused)) = {
    .defaults = protocore_power_defaults,
    .decide = protocore_power_decide,
    .json = protocore_power_json,
#if PROTOCORE_HAS_VENDOR_PM
    .brownout = protocore_power_brownout,
    .die_temp = protocore_power_die_temp,
    .cpu_mhz = protocore_power_cpu_mhz,
    .apply = protocore_power_apply,
#endif
#if PROTOCORE_HAS_VENDOR_BT
    .gate_bt = protocore_power_gate_bt,
#endif
};
 
/**
 * @brief The PROTOCORE_POWER_MGMT_BORROW bytes this module's state lives in.
 *
 * Stated beside the namespace rather than on it: an entry takes a borrow, and this is where
 * that borrow comes from. Taken once from the end of the pool, which no mark and no release
 * walks, so the state lasts the life of the program.
 *
 * @return the span.
 */
uint8_t *protocore_power_mgmt_span(void);
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_ENABLE_POWER_MGMT
 
#endif // PROTOCORE_POWER_MGMT_H