SPB Git

Repository Public License

macos-capability-matrix.md 14.8 KB

# macOS capability matrix

This 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").

# Audited environment

Every 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.

Item Value
Model MacBook Pro, hw.model = Mac17,6
Chip Apple M5 Max
CPU cores 18 (6 "Super" + 12 "Performance", as named by hw.perflevelN.name)
Memory 48 GB
macOS 27.0 (build 26A5425a)
Xcode 27.2
Swift 6.4.2

# Classification

Each row carries exactly one class. The first six are the standard taxonomy; the seventh is ORIX Monitor's own addition (CapabilityClass.bestEffort).

Class CapabilityClass case Meaning
Available through public APIs publicAPI A documented call returns the value without any prompt or privilege.
Available with user authorization userAuthorization A documented call exists, but macOS shows a consent prompt first.
Available through supported system commands systemCommand Only a bundled command-line tool exposes it.
Available through approved privileged helper privilegedHelper The kernel returns it only to root; an app would need a helper installed with administrator approval.
Unavailable through supported mechanisms unavailable Only private frameworks, the SMC or undocumented kernel interfaces expose it.
Estimated rather than directly measured estimated The system (or ORIX Monitor) computes a projection; it is not a reading.
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.

What ORIX Monitor does with each class:

Class Behaviour in the app
Public API Shown. Stored metrics carry the quality measured or derived; no badge is drawn for those two on cards.
User authorization Not requested. ORIX Monitor asks for no permission except, optionally, notifications.
System command Not used. No collector spawns a process; the class exists in the enum but no row uses it.
Privileged helper Not installed. The value is shown as "—" (never as zero) with an explanation.
Unavailable Shown as an UnavailableRow with the badge "Unavailable" and the text "Not available through supported system interfaces." (or a more specific reason).
Estimated Shown with the badge "Estimate".
Best effort Shown with the badge "Best effort". Read only while TelemetryConfiguration.bestEffortMetrics is on (Settings › Sampling › "Read undocumented system properties").

# Matrix

The 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.

# CPU

id Metric Class Source What ORIX Monitor does
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.
— Load average Available through public APIs getloadavg(3) Shows 1, 5 and 15 minute values; stores the 1-minute value as cpu.load1.
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.
cpu.frequency CPU frequency Unavailable through supported mechanisms — Shows "Not published on Apple Silicon."
cpu.temperature CPU temperature Unavailable through supported mechanisms — (SMC and private HID sensor services only) Shows "Not available through supported system interfaces."

# Thermal

id Metric Class Source What ORIX Monitor does
thermal.state Thermal state Available through public APIs ProcessInfo.thermalState Shows it (Nominal / Fair / Serious / Critical) and stores it as thermal.state.
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.
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."
gpu.temperature GPU temperature Unavailable through supported mechanisms — Shows "Not available through supported system interfaces."

# Memory

id Metric Class Source What ORIX Monitor does
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.
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.
memory.swap Swap usage Available through public APIs sysctl vm.swapusage (xsw_usage) Shows used and allocated swap; stores memory.swap.

# Disk

id Metric Class Source What ORIX Monitor does
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.
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.
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."
— 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.

# Network

id Metric Class Source What ORIX Monitor does
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.
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.
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.
network.perprocess Per-process network traffic Unavailable through supported mechanisms — (network extension or private framework) Shows the reason. ORIX Monitor does not intercept traffic.
— DNS servers, router, primary interface Available through public APIs SCDynamicStoreCopyValue (State:/Network/Global/DNS, …/IPv4) Shows them; masked by the privacy mask.
— Connection time to a host Available through public APIs NWConnection TCP handshake Runs only on demand (button). Not stored.

# Processes

id Metric Class Source What ORIX Monitor does
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.
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.
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.

# GPU

id Metric Class Source What ORIX Monitor does
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.
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.
gpu.perprocess Per-process GPU usage Unavailable through supported mechanisms — Shows "Not available through supported system interfaces."
— GPU power draw Unavailable through supported mechanisms — Shows "Not available through supported system interfaces."

# Power

id Metric Class Source What ORIX Monitor does
power.battery Battery charge and state Available through public APIs IOKit IOPowerSources Shows charge, charging state, power source, adapter wattage, condition; stores battery.charge.
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.
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.
power.flow Battery power flow Best effort IORegistry AppleSmartBattery (Voltage, Amperage) Shows voltage, current and their product; stores battery.power.
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."
power.lowpower Low Power Mode Available through public APIs ProcessInfo.isLowPowerModeEnabled Shows it and uses it to slow the sampler (battery saver).
— 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.

# Verified facts about the audited system

These were observed on the Mac described above and are encoded in the collectors and their tests.

  1. 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.
  2. 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.
  3. 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.
  4. 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).
  5. 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.

# Limitations of this matrix

  • It describes one Mac. The present column of the in-app table is the authoritative answer for any other machine.
  • "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.
  • 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.
  • 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.)

See also: CPU, GPU, memory, disk, network, power, thermal, and collectors.

Files main
Menu

Theme