- Generated by
1.16.1
|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
Bounded, allocation-free low-battery nag policy. More...
Go to the source code of this file.
Data Structures | |
| struct | ra8_batt_monitor_t |
| Caller-owned nag state carried across ra8_batt_update calls. More... | |
Enumerations | |
| enum | ra8_batt_nag_t : uint8_t { k_ra8_batt_nag_none = 0U , k_ra8_batt_nag_low = 1U , k_ra8_batt_nag_critical = 2U } |
| The low-battery warning a single ra8_batt_update step raises. More... | |
| enum | ra8_batt_threshold_t : uint8_t { k_ra8_batt_low_pct = 20U , k_ra8_batt_critical_pct = 10U , k_ra8_batt_rearm_margin = 3U , k_ra8_batt_pct_max = 100U } |
| Nag thresholds and hysteresis margin, in whole percent. More... | |
Functions | |
| ra8_err_t | ra8_batt_monitor_init (ra8_batt_monitor_t *mon) |
| Reset a nag monitor to the un-nagged, fully-armed state. | |
| ra8_err_t | ra8_batt_update (ra8_batt_monitor_t *mon, uint8_t soc_pct, bool charging, ra8_batt_nag_t *out_nag) |
| Fold one SOC reading into the monitor and report the nag to raise. | |
| const char * | ra8_batt_nag_str (ra8_batt_nag_t nag) |
| Map a nag level to a short, stable upper-case label. | |
Bounded, allocation-free low-battery nag policy.
ra8_batt decides when to raise a low-battery warning from a stream of state-of-charge (SOC) readings. It is geometry-free and hardware-free: a caller feeds it the percent + charge flag each tick (e.g. from a MAX17048 fuel gauge read over ra8_smbus) and it returns the nag to surface, if any. The display / UART / e-reader chrome layer on top decide how to show it.
The policy is edge-triggered with hysteresis, so a steady or jittering battery does not spam the user:
The decision is a single forward step with no loop, no recursion, and no allocation (NASA P10 Rules 1-3), so it runs identically on the host test harness and on the RA8D2.
[Ring 5 / UI] {World: NS}
Definition in file ra8_batt.h.
| enum ra8_batt_nag_t : uint8_t |
The low-battery warning a single ra8_batt_update step raises.
Returned by value through ra8_batt_update. k_ra8_batt_nag_none means no new edge this step (the common case); the other two are the one-shot warnings for the low and critical bands.
| Enumerator | |
|---|---|
| k_ra8_batt_nag_none | No new warning this step. |
| k_ra8_batt_nag_low | SOC fell to the low band (<=20%). |
| k_ra8_batt_nag_critical | SOC fell to the critical band (<=10%). |
Definition at line 54 of file ra8_batt.h.
| enum ra8_batt_threshold_t : uint8_t |
Nag thresholds and hysteresis margin, in whole percent.
The bands are inclusive at and below their threshold; a band re-arms once SOC rises strictly above (threshold + k_ra8_batt_rearm_margin) so a battery hovering at the boundary does not re-nag every step.
Definition at line 68 of file ra8_batt.h.
| ra8_err_t ra8_batt_monitor_init | ( | ra8_batt_monitor_t * | mon | ) |
Reset a nag monitor to the un-nagged, fully-armed state.
Writes zero to both band-raised flags inside mon, placing the monitor into the fully-armed state so that the first subsequent call to ra8_batt_update can raise either the low or critical nag. The operation is a single struct clear with no loops, no allocation, and no hardware access, making it safe to call from any initialisation context on both the RA8D2 target and the host unit-test harness.
| [out] | mon | Monitor to initialise. |
| k_ra8_ok | Monitor zeroed; both bands armed. |
| k_ra8_err_null_ptr | mon is nullptr. |
mon points to writable storage. Definition at line 27 of file ra8_batt.c.
References ra8_batt_monitor_t::critical_raised, k_ra8_ok, ra8_batt_monitor_t::low_raised, RA8_CHECK_NULL_PTR, and s_tag.
Referenced by main().
| const char * ra8_batt_nag_str | ( | ra8_batt_nag_t | nag | ) |
Map a nag level to a short, stable upper-case label.
| [in] | nag | Nag level. |
| OK | For k_ra8_batt_nag_none. |
| LOW | For k_ra8_batt_nag_low. |
| CRITICAL | For k_ra8_batt_nag_critical. |
| ? | For any out-of-range value. |
Definition at line 71 of file ra8_batt.c.
References k_ra8_batt_nag_critical, k_ra8_batt_nag_low, k_ra8_batt_nag_none, and RA8_ASSERT.
| ra8_err_t ra8_batt_update | ( | ra8_batt_monitor_t * | mon, |
| uint8_t | soc_pct, | ||
| bool | charging, | ||
| ra8_batt_nag_t * | out_nag ) |
Fold one SOC reading into the monitor and report the nag to raise.
Re-arms each band when charging or when soc_pct has recovered above the band threshold by k_ra8_batt_rearm_margin, then, only while not charging, raises the low and/or critical band the reading newly enters. When a reading enters both bands at once (a large drop), the returned nag is the worse one (k_ra8_batt_nag_critical). soc_pct above k_ra8_batt_pct_max is clamped.
| [in,out] | mon | Monitor state (updated in place). |
| [in] | soc_pct | Current state-of-charge percent (clamped to 0..100). |
| [in] | charging | True when the fuel gauge reports a charging rate. |
| [out] | out_nag | Receives the nag to surface this step. |
| k_ra8_ok | Step folded; out_nag written. |
| k_ra8_err_null_ptr | mon or out_nag is nullptr. |
mon was initialised by ra8_batt_monitor_init. out_nag points to writable storage. out_nag holds one of ra8_batt_nag_t. Definition at line 36 of file ra8_batt.c.
References ra8_batt_monitor_t::critical_raised, k_ra8_batt_critical_pct, k_ra8_batt_low_pct, k_ra8_batt_nag_critical, k_ra8_batt_nag_low, k_ra8_batt_nag_none, k_ra8_batt_pct_max, k_ra8_batt_rearm_margin, k_ra8_ok, ra8_batt_monitor_t::low_raised, RA8_CHECK_NULL_PTR, and s_tag.
Referenced by er_poll_battery(), and main().
1.16.1