SPB Git

Repository Public License

macos-capability-matrix.md 14.8 KB 150 lines markdown

1<!--2ORIX Monitor3File: docs/research/macos-capability-matrix.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# macOS capability matrix910This document records what an unprivileged, non-sandbox-escaping macOS app can read about the machine it runs on, and what ORIX Monitor does with each item. It is the written counterpart of `SensorCapabilityResolver.resolve()` in `Packages/ORIXMonitorCore/Sources/ORIXMonitorCore/Collectors/PowerThermalGPU.swift`, which probes the running Mac and feeds the table shown on the **Thermal & Sensors** page ("Sensor and metric availability on this Mac").1112## Audited environment1314Every statement below was established on one machine. Nothing here has been verified on another Mac model, on an Intel Mac, or on an earlier macOS release.1516| Item | Value |17|---|---|18| Model | MacBook Pro, `hw.model` = `Mac17,6` |19| Chip | Apple M5 Max |20| CPU cores | 18 (6 "Super" + 12 "Performance", as named by `hw.perflevelN.name`) |21| Memory | 48 GB |22| macOS | 27.0 (build 26A5425a) |23| Xcode | 27.2 |24| Swift | 6.4.2 |2526## Classification2728Each row carries exactly one class. The first six are the standard taxonomy; the seventh is ORIX Monitor's own addition (`CapabilityClass.bestEffort`).2930| Class | `CapabilityClass` case | Meaning |31|---|---|---|32| Available through public APIs | `publicAPI` | A documented call returns the value without any prompt or privilege. |33| Available with user authorization | `userAuthorization` | A documented call exists, but macOS shows a consent prompt first. |34| Available through supported system commands | `systemCommand` | Only a bundled command-line tool exposes it. |35| Available through approved privileged helper | `privilegedHelper` | The kernel returns it only to root; an app would need a helper installed with administrator approval. |36| Unavailable through supported mechanisms | `unavailable` | Only private frameworks, the SMC or undocumented kernel interfaces expose it. |37| Estimated rather than directly measured | `estimated` | The system (or ORIX Monitor) computes a projection; it is not a reading. |38| Best effort (public API, undocumented property name) | `bestEffort` | Read with a public IOKit call (`IORegistryEntryCreateCFProperties`) from a registry property whose *name* Apple does not document. It can disappear or change with any update. |3940What ORIX Monitor does with each class:4142| Class | Behaviour in the app |43|---|---|44| Public API | Shown. Stored metrics carry the quality `measured` or `derived`; no badge is drawn for those two on cards. |45| User authorization | Not requested. ORIX Monitor asks for no permission except, optionally, notifications. |46| System command | Not used. No collector spawns a process; the class exists in the enum but no row uses it. |47| Privileged helper | Not installed. The value is shown as "—" (never as zero) with an explanation. |48| Unavailable | Shown as an `UnavailableRow` with the badge "Unavailable" and the text "Not available through supported system interfaces." (or a more specific reason). |49| Estimated | Shown with the badge "Estimate". |50| Best effort | Shown with the badge "Best effort". Read only while `TelemetryConfiguration.bestEffortMetrics` is on (Settings › Sampling › "Read undocumented system properties"). |5152## Matrix5354The `id` column is the identifier used by `SensorCapabilityResolver`. "Present" is evaluated live on each Mac by the resolver (the `present` field); it is not restated here because it depends on the machine and the moment.5556### CPU5758| id | Metric | Class | Source | What ORIX Monitor does |59|---|---|---|---|---|60| `cpu.load` | CPU load, total and per core | Available through public APIs | `host_processor_info(PROCESSOR_CPU_LOAD_INFO)` | Shows it (total, user, system, idle, per-core bars and heatmap). Stores `cpu.total`, `cpu.user`, `cpu.system`. |61| — | Load average | Available through public APIs | `getloadavg(3)` | Shows 1, 5 and 15 minute values; stores the 1-minute value as `cpu.load1`. |62| `cpu.groups` | Core groups (count per performance level) | Available through public APIs | `sysctl hw.nperflevels`, `hw.perflevelN.{name,physicalcpu,logicalcpu}` | Shows the count and kernel-given name of each group. Does **not** label individual cores: the kernel publishes how many cores each level has, not which core index belongs to which level. |63| `cpu.frequency` | CPU frequency | Unavailable through supported mechanisms | — | Shows "Not published on Apple Silicon." |64| `cpu.temperature` | CPU temperature | Unavailable through supported mechanisms | — (SMC and private HID sensor services only) | Shows "Not available through supported system interfaces." |6566### Thermal6768| id | Metric | Class | Source | What ORIX Monitor does |69|---|---|---|---|---|70| `thermal.state` | Thermal state | Available through public APIs | `ProcessInfo.thermalState` | Shows it (Nominal / Fair / Serious / Critical) and stores it as `thermal.state`. |71| `thermal.fans` | Fan speed | Unavailable through supported mechanisms | — (SMC only) | Shows "Not available through supported system interfaces." A UI test asserts no "rpm" figure is ever displayed. |72| `battery.temperature` | Battery temperature | Best effort | IORegistry `AppleSmartBattery`, key `Temperature` | Shows it with a "Best effort" badge **when the key exists**. On the audited Mac the key is absent, so the page shows "The battery gauge on this Mac and macOS version publishes no temperature." |73| `gpu.temperature` | GPU temperature | Unavailable through supported mechanisms | — | Shows "Not available through supported system interfaces." |7475### Memory7677| id | Metric | Class | Source | What ORIX Monitor does |78|---|---|---|---|---|79| `memory.accounting` | Memory accounting and paging | Available through public APIs | `host_statistics64(HOST_VM_INFO64)`, `hw.memsize`, `host_page_size` | Shows used / app / wired / compressed / cached / free, page-in, page-out, swap-in and swap-out rates. |80| `memory.pressure` | Memory pressure level | Available through public APIs | `sysctl kern.memorystatus_vm_pressure_level` | Shows the three-level signal and stores it as `memory.pressure`. |81| `memory.swap` | Swap usage | Available through public APIs | `sysctl vm.swapusage` (`xsw_usage`) | Shows used and allocated swap; stores `memory.swap`. |8283### Disk8485| id | Metric | Class | Source | What ORIX Monitor does |86|---|---|---|---|---|87| `disk.capacity` | Volume capacity | Available through public APIs | `URLResourceValues`, DiskArbitration | Shows every mounted, non-hidden volume; stores the startup volume's available space as `disk.free`. |88| `disk.io` | Disk throughput | Available through public APIs | IOKit `IOBlockStorageDriver` "Statistics" | Shows read/write rates and cumulative totals per block device; stores `disk.read` and `disk.write`. |89| `disk.health` | SSD health and wear | Unavailable through supported mechanisms | — (NVMe SMART needs a privileged or private interface) | Shows "NVMe SMART data is only reachable through privileged or private interfaces. ORIX Monitor shows none rather than guess." |90| — | Per-process disk throughput | Unavailable through supported mechanisms | — | Shows the reason; only cumulative bytes per process (`ri_diskio_bytesread` / `ri_diskio_byteswritten`) are displayed, in the process inspector. |9192### Network9394| id | Metric | Class | Source | What ORIX Monitor does |95|---|---|---|---|---|96| `network.throughput` | Interface throughput | Available through public APIs | `sysctl` `NET_RT_IFLIST2` (`if_msghdr2`, `if_data64`) | Shows per-interface and total rates; stores `network.down` and `network.up`. |97| `network.wifi` | Wi-Fi signal and rate | Available through public APIs | CoreWLAN (`CWWiFiClient`) | Shows RSSI, noise, signal-to-noise, link rate, channel, band and PHY mode. |98| `network.ssid` | Wi-Fi network name | Available with user authorization | CoreWLAN + Location Services | **Does not request it.** The page states that the name is not shown because reading it requires Location Services. |99| `network.perprocess` | Per-process network traffic | Unavailable through supported mechanisms | — (network extension or private framework) | Shows the reason. ORIX Monitor does not intercept traffic. |100| — | DNS servers, router, primary interface | Available through public APIs | `SCDynamicStoreCopyValue` (`State:/Network/Global/DNS`, `…/IPv4`) | Shows them; masked by the privacy mask. |101| — | Connection time to a host | Available through public APIs | `NWConnection` TCP handshake | Runs only on demand (button). Not stored. |102103### Processes104105| id | Metric | Class | Source | What ORIX Monitor does |106|---|---|---|---|---|107| `process.identity` | Process identity (all processes) | Available through public APIs | libproc (`proc_listallpids`, `proc_pidinfo`, `proc_pidpath`) | Shows PID, parent PID, name, user and path for every process. |108| `process.stats` | CPU, memory, disk and energy of your own processes | Available through public APIs | `proc_pid_rusage(RUSAGE_INFO_V4)`, `proc_pidinfo(PROC_PIDTASKINFO)` | Shows CPU %, CPU time, physical footprint, threads, cumulative disk bytes and billed power. |109| `process.stats.other` | CPU and memory of other users' processes | Available through approved privileged helper | — | **Installs no helper.** Shows "—" in those cells and a "Restricted" card in the inspector; such processes are counted in `ProcessSample.restricted` and excluded from rankings. |110111### GPU112113| id | Metric | Class | Source | What ORIX Monitor does |114|---|---|---|---|---|115| `gpu.devices` | GPU devices and Metal capabilities | Available through public APIs | Metal (`MTLCopyAllDevices`) | Shows name, unified memory, recommended working set, largest buffer, ray tracing, low-power / removable / headless flags. |116| `gpu.utilization` | GPU utilization | Best effort | IORegistry `IOAccelerator`, `PerformanceStatistics["Device Utilization %"]` | Shows it with a "Best effort" badge; stores `gpu.utilization`. Renderer and tiler utilization, GPU core count and driver memory figures come from the same dictionary and carry the same badge. |117| `gpu.perprocess` | Per-process GPU usage | Unavailable through supported mechanisms | — | Shows "Not available through supported system interfaces." |118| — | GPU power draw | Unavailable through supported mechanisms | — | Shows "Not available through supported system interfaces." |119120### Power121122| id | Metric | Class | Source | What ORIX Monitor does |123|---|---|---|---|---|124| `power.battery` | Battery charge and state | Available through public APIs | IOKit `IOPowerSources` | Shows charge, charging state, power source, adapter wattage, condition; stores `battery.charge`. |125| `power.timeremaining` | Time remaining / time until full | Estimated rather than directly measured | IOKit `IOPowerSources` (`kIOPSTimeToEmptyKey`, `kIOPSTimeToFullChargeKey`) | Shows the system's estimate with an "Estimate" badge, or "Calculating…" while the system has none. |126| `power.cycles` | Cycle count and capacity | Best effort | IORegistry `AppleSmartBattery` | Shows cycle count, design and full-charge capacity and their ratio with "Best effort" badges. |127| `power.flow` | Battery power flow | Best effort | IORegistry `AppleSmartBattery` (`Voltage`, `Amperage`) | Shows voltage, current and their product; stores `battery.power`. |128| `power.system` | Whole-system power draw | Best effort | IORegistry `AppleSmartBattery`, `PowerTelemetryData.SystemLoad` | Shows it as "System load (battery gauge)" with a "Best effort" badge. Not stored. Portable Macs only; desktop Macs show "Desktop Macs expose no power figure through supported system interfaces." |129| `power.lowpower` | Low Power Mode | Available through public APIs | `ProcessInfo.isLowPowerModeEnabled` | Shows it and uses it to slow the sampler (battery saver). |130| — | Per-process power | Available through public APIs (own processes) | `rusage_info_v4.ri_billed_energy` | Shows average watts billed by the kernel over the last process interval, for the user's own processes only. An accounting figure, not a wall measurement. |131132## Verified facts about the audited system133134These were observed on the Mac described above and are encoded in the collectors and their tests.1351361. **Other users' processes.** The kernel refuses `proc_pidinfo(PROC_PIDTBSDINFO)` and `proc_pid_rusage` for processes owned by another user. `ProcessCollector.sample()` therefore falls back to `PROC_PIDT_SHORTBSDINFO` (`proc_bsdshortinfo`), which yields PID, parent PID, UID and short command name but no start time. `ProcessRecord.hasStatistics` stays `false`, and CPU, memory, threads, CPU time and power are displayed as "—". The live test `processTableContainsThisProcessWithPlausibleFigures` checks that `launchd` (PID 1, root) is listed by name without statistics when the test does not run as root.1372. **`AppleSmartBattery` layout on macOS 27.** The registry entry nests capacities under a `BatteryData` dictionary, publishes no `Temperature` key, and has a `PowerTelemetryData.SystemLoad` value. `PowerMath.batteryFields(registry:)` reads both the flat and the nested layout and treats every field as optional; the unit tests `nestedBatteryLayout` and `flatBatteryLayoutAndImplausibleTemperature` cover both shapes.1383. **Signed values in the registry.** Registry integers are unsigned 64-bit even for signed quantities: a discharge current reads as 2⁶⁴ − x. `PowerMath.signed(_:)` reinterprets the bits.1394. **CPU-time units.** `rusage_info_v4.ri_user_time` and `ri_system_time` are in Mach absolute-time units, not nanoseconds. On Apple Silicon the timebase is 125/3. `ProcessMath.nanos(machUnits:numer:denom:)` converts with a full-width multiply, and the live test `cpuTimeAgreesWithGetrusage` checks the result against `getrusage(RUSAGE_SELF)` within 5 % (or 50 ms).1405. **Performance levels.** `hw.perflevel0.name` and `hw.perflevel1.name` return "Super" and "Performance" on this chip. ORIX Monitor prints whatever names the kernel returns; it hard-codes no "P-core"/"E-core" vocabulary.141142## Limitations of this matrix143144- It describes one Mac. The `present` column of the in-app table is the authoritative answer for any other machine.145- "Best effort" rows depend on property names that Apple may rename. The parsers return `nil` rather than a default when a key is missing, so a rename removes the reading instead of corrupting it.146- The matrix lists what ORIX Monitor reads. It is not a complete inventory of macOS telemetry interfaces; items the app never attempts to read (for example Bluetooth, display or audio state) are out of scope.147- The `systemCommand` class is defined but unused: no value in ORIX Monitor comes from spawning `powermetrics`, `ioreg`, `pmset` or any other tool. (`Scripts/bench.sh` uses `ps`, `footprint`, `sysctl`, `sw_vers` and `pmset`, but that is a development script, not the app.)148149See also: [CPU](../metrics/cpu.md), [GPU](../metrics/gpu.md), [memory](../metrics/memory.md), [disk](../metrics/disk.md), [network](../metrics/network.md), [power](../metrics/power.md), [thermal](../metrics/thermal.md), and [collectors](../architecture/collectors.md).150
Files main
Menu

Theme