LOX · Liquid Oxygen for Embedded Systems
LOX Budget
Risky operations start while RAM, queue, energy or write budgets are already under pressure.
A caller-owned admission controller returns an explicit allow, degrade, defer or deny decision before work starts.
Developmentv1.0.1MITC99
01 / ADMISSION BEFORE WORKDECLAREResource limitsreusable, consumable or state →PROFILEOperation needsactions by pressure level →CHECKEvaluate availabilityrecord reason and decision →CALLERRun, degrade or deferapplication chooses the work
Ask whether an operation should start now
LOX Budget is a no-heap C99 admission-control library. Firmware declares operation profiles and resource requirements; application-owned state tracks current budgets and pressure. A check returns a decision such as allow full, allow degraded, wait, reject or lockdown before the operation begins.
The library answers a policy question; it does not schedule deferred work, allocate resources, or perform the operation.
02 / RESOURCE ACCOUNTING
Budgets combine different resource lifetimes
A resource entry has a limit, usage, reservations, available amount and high-water mark. The public API distinguishes reusable resources, consumable quantities and state values. Examples include queue slots, flash-write allowance or a bounded RAM budget.
Operations register profiles that describe requirements and desired behavior under pressure. Decisions include the blocked resource, requested/available quantities and a reason such as insufficient resource, rate limit, exhausted lifetime, pressure block or unmet precondition.
Resource readings and preconditions come from the application or configured HAL callbacks. LOX Budget does not discover physical memory, voltage, network connectivity or flash health by itself.
DECISION OUTPUT
action: FULL / DEGRADED / WAIT / REJECT / LOCKDOWN
↓pressure level
↓reason code
↓denied resource + requested / available
03 / CHECK VERSUS RESERVATION
A query does not reserve; enter/leave brackets work
loxbudget_check() evaluates the operation against current state and returns a decision. When the operation needs a reservation that stays held during execution, loxbudget_enter() acquires a lease and loxbudget_leave() returns the reserved resources. The integration must release the lease on every normal exit path.
check only→decision snapshot·enter→lease held during operation→leave releases
Lease APIs coordinate the budget model, not arbitrary external side effects. They do not make an operation transactional or protect resource changes that bypass the configured budget instance.
04 / PRESSURE IS APPLICATION POLICY
Pressure levels alter the profile's selected action
Profiles can select different actions under NORMAL, ELEVATED, CRITICAL, SURVIVAL and LOCKDOWN pressure. The application sets the global pressure state; the library evaluates configured profiles against it. This makes a pressure response explicit and testable, but the project does not infer a correct pressure level for a particular product.
Operation preconditions can represent requirements such as boot proven, voltage acceptable or network up. Their truth comes from the application's observations or HAL path. A profile that allows a costly action through every pressure level is still a caller policy choice.
05 / OPT-IN CAPABILITIESRATE AND LIFETIME AUDIT CALIBRATION CAUSALITY
Extend decisions only where the integration needs them
Time-window budgets
Optional second, minute, hour, day and lifetime windows can constrain repeated use. These are library accounting windows, not a general job scheduler.
Bounded decision history
An optional audit ring retains recent decisions for later inspection. It is not a logger or durable event store.
Suggested limits from samples
Optional calibration collects application-provided RAM, stack, flash-write, queue and duration samples, then exports a binary snapshot for a host report. Suggestions depend on those samples and are not self-measured guarantees.
Account for downstream work
Optional causality edges describe operations that may trigger others. A bounded graph walk adds weighted child requirements; cycles are handled by a visited bitmap and recursion is bounded by configured depth.
06 / SIZE AND TEST EVIDENCE
Measured object footprint is not MCU timing
The repository records Cortex-M0 freestanding relocatable-object `.text` measurements of 4,192 bytes without causality and 5,340 bytes with causality in its v1.1 footprint notes; both report zero `.data` and `.bss` for that measurement method. These are toolchain/build artifacts, not complete firmware image sizes.
A host microbenchmark reports 260.7 ns/check baseline and 338.8 ns/check with two causality edges. The README explicitly says these host timings are not MCU cycle counts. Cortex-M WCET and stack peak are marked TBD in the current benchmark table; a real-hardware benchmark document remains a template.
The repository configures CI for GCC/Clang host builds, Cortex-M0 cross-build, format/static checks, sanitizers and fuzz smoke. The public README describes these as CI-covered gates; this site has not inspected a current workflow run result. It makes no safety certification or production-readiness claim.
README and verification statusCausality modeCalibrationFootprint methodology
07 / APPLICATION BOUNDARY
An admission layer, not a safety case
- Policies, pressure measurements and resource observations are supplied by the application/HAL.
- Check without enter does not hold a reservation while work runs.
- External side effects and resource mutations outside the budget instance are not protected.
- Calibration suggestions depend on representative input samples and do not certify a resource limit.
- Optional causality modeling covers declared edges within configured bounds, not every possible downstream effect.
- The project explicitly disclaims safety certification and formal verification; verify policies in the complete firmware.
Current release line: tagged v1.0.1; README labels the development line Unreleased. LOX family · All products