vasilito
9f2de2a0b1
Docs:
- Baseline was stated as 0.3.1 across the canonical set while the branch,
Cat 0/1 crates and every Cat 2 fork are 0.3.2. AGENTS.md also cited a
sources/redbear-0.3.1/ archive that does not exist; the only archive
present is sources/redbear-0.1.0/. Versioning examples now match the
forks as they actually stand (redoxfs/syscall 0.9.1, libredox 0.1.19).
- Repaired 18 instances of 'immutable archived' across 8 documents, where
a global find/replace had turned sync/synced/archived into that phrase
and produced ungrammatical text ('never auto-immutable archived',
'### Source immutable archived').
- Settled the apply-patches.sh contradiction empirically. Both sides were
wrong: the GROSS WARNING blocks (x5) described it as routine
patch-linking, and SCRIPT-BEHAVIOR-MATRIX.md said build-redbear.sh
'never invokes' it. It is invoked at build-redbear.sh:487, but only to
auto-repair a failed verify-overlay-integrity.sh check.
- Dropped the dangling reference to a local/AGENTS.md section
'NO OVERLAY-STYLE PATCHES — SCOPED POLICY' that does not exist.
Build system:
- mk/prefix.mk hardcoded 13.2.0 in the limits.h removal, which silently
no-ops after a toolchain upgrade and leaves the conflicting header.
Version-globbed.
- Parameterized GCC_RECIPE so the from-source toolchain path is not
pinned to gcc13.
- The three cstdlib strtold seds were not idempotent -- the shipped GCC
13 toolchain carried that comment block 17 times from repeated
'make prefix' runs. Each is now guarded.
112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# redbear-upower — D-Bus Interface
|
||
|
||
**Bus:** system
|
||
**Well-known name:** `org.freedesktop.UPower`
|
||
**Object paths:**
|
||
- `/org/freedesktop/UPower` — UPower daemon root
|
||
- `/org/freedesktop/UPower/devices/DisplayDevice` — Composite display device
|
||
- `/org/freedesktop/UPower/devices/line_power_<id>` — Per-adapter AC power devices
|
||
- `/org/freedesktop/UPower/devices/battery_<id>` — Per-battery devices
|
||
|
||
## Interface: `org.freedesktop.UPower`
|
||
|
||
### Methods
|
||
|
||
| Method | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `EnumerateDevices` | `() → (ao)` | List all device object paths |
|
||
| `GetCriticalAction` | `() → (s)` | Returns `"PowerOff"` |
|
||
|
||
### Properties
|
||
|
||
| Property | Type | Description |
|
||
|----------|------|-------------|
|
||
| `DaemonVersion` | `s` | `"0.1.0"` (const) |
|
||
| `OnBattery` | `b` | Whether running on battery (no AC adapters online and at least one battery discharging). Computed from snapshot. |
|
||
|
||
### Signals
|
||
|
||
| Signal | Signature | Description |
|
||
|--------|-----------|-------------|
|
||
| `Changed` | `()` | Power state changed (emitted on poll interval or ACPI notification) |
|
||
|
||
## Interface: `org.freedesktop.UPower.Device`
|
||
|
||
### Methods
|
||
|
||
None (property-only interface).
|
||
|
||
### Properties (all devices)
|
||
|
||
| Property | Type | Description |
|
||
|----------|------|-------------|
|
||
| `Type` | `u` | Device kind: 0=unknown, 1=line power, 2=battery |
|
||
| `State` | `u` | Device state: 0=unknown, 1=charging, 2=discharging, 3=empty, 4=fully charged |
|
||
| `Percentage` | `d` | Battery percentage (0.0–100.0). 0.0 for adapters, average across batteries for DisplayDevice |
|
||
| `IsPresent` | `b` | Whether the device hardware is present |
|
||
| `Online` | `b` | True for AC adapters that are plugged in; false for batteries |
|
||
| `NativePath` | `s` | ACPI scheme path (e.g. `/scheme/acpi/power/adapters/ACAD`) |
|
||
| `TimeToFull` | `x` | Seconds until fully charged (0 if not charging) |
|
||
| `TimeToEmpty` | `x` | Seconds until empty (0 if not discharging) |
|
||
| `Energy` | `d` | Current energy in Wh |
|
||
| `EnergyRate` | `d` | Present power draw in W (positive=discharging, negative=charging) |
|
||
| `BatteryLevel` | `u` | Higher-level battery status: 0=unknown, 3=normal, 4=low, 5=critical, 7=full |
|
||
| `PowerSupply` | `b` | Whether the device supplies power (true for online adapters, false for batteries) |
|
||
| `Serial` | `s` | Hardware serial identifier |
|
||
|
||
### DisplayDevice properties
|
||
|
||
The DisplayDevice at `/org/freedesktop/UPower/devices/DisplayDevice` is a composite view:
|
||
- `Type`: `DEVICE_KIND_BATTERY` if at least one battery exists, else `DEVICE_KIND_UNKNOWN`
|
||
- `State`: Aggregate state across all batteries (charging if any battery charging, discharging if any battery discharging)
|
||
- `Percentage`: Average of all battery percentages
|
||
- `IsPresent`: True if at least one battery exists
|
||
- `Online`: Always false
|
||
|
||
## State Discovery
|
||
|
||
At startup, `PowerRuntime::discover()` reads:
|
||
- `/scheme/acpi/power/adapters/` — lists subdirectories, each an AC adapter
|
||
- `/scheme/acpi/power/batteries/` — lists subdirectories, each a battery
|
||
|
||
For each adapter:
|
||
- `path` — native ACPI path
|
||
- `online` — `u64`, non-zero means plugged in
|
||
|
||
For each battery:
|
||
- `path` — native ACPI path
|
||
- `state` — `u64` bitmask (bit 0=discharging, bit 1=charging, bit 2=critical)
|
||
- `percentage` — `f64`, percentage charge
|
||
- `energy` — `f64`, energy in Wh
|
||
- `energy_rate` — `f64`, power in W
|
||
- `time_to_full` — `f64`, seconds
|
||
- `time_to_empty` — `f64`, seconds
|
||
- `serial` — hardware serial string
|
||
|
||
## State Change Detection
|
||
|
||
Two mechanisms:
|
||
1. **Poll interval:** Every 30 seconds (`POLL_INTERVAL_SECS`), take a snapshot and compare with the last. If the state changed, emit `Changed` signal.
|
||
2. **ACPI notification drain:** Every 250 ms (`NOTIFICATION_POLL_MS`), read `/scheme/acpi/notifications`. If notifications are present and the state changed, emit `Changed` signal. This reduces battery state change latency from 30 s to sub-second for ACPI-aware hardware.
|
||
|
||
## Battery Level Mapping
|
||
|
||
| Condition | Level |
|
||
|-----------|-------|
|
||
| State bit 0x4 (critical) set | `BATTERY_LEVEL_CRITICAL` (5) |
|
||
| Percentage < 10.0 | `BATTERY_LEVEL_CRITICAL` (5) |
|
||
| 10.0 ≤ Percentage < 25.0 | `BATTERY_LEVEL_LOW` (4) |
|
||
| Percentage ≥ 100.0 | `BATTERY_LEVEL_FULL` (7) |
|
||
| 25.0 ≤ Percentage < 100.0 | `BATTERY_LEVEL_NORMAL` (3) |
|
||
| Percentage unavailable | `BATTERY_LEVEL_UNKNOWN` (0) |
|
||
|
||
## Connection
|
||
|
||
- System bus, same env var resolution as other D-Bus daemons
|
||
- 3 retry attempts at 1 s intervals
|
||
- If `/scheme/acpi/power` is unavailable, serves an empty provisional UPower surface (no devices, daemon still registers on bus)
|
||
|
||
## References
|
||
- [UPower D-Bus API](https://upower.freedesktop.org/docs/ref-dbus.html)
|
||
- Conformance: Subset implementation. Device enumeration from ACPI power scheme. Composite DisplayDevice. Changed signal on state transitions. No history/statistics. No Wakeups API. No suspend/hibernate integration (handled by login1). No backlight control.
|