1# Recount 2 3CPU resource accounting interfaces and implementation. 4 5## Overview 6 7Recount is a resource accounting subsystem in the kernel that tracks the CPU resources consumed by threads, tasks, coalitions, and processors. 8It supports attributing counts to a specific level of the CPU topology (per-CPU and per-CPU kind). 9ARM64 devices with a fast timebase read and Intel devices can track time spent in the kernel (system) separately from user space. 1064-bit, non-virtualized (e.g. _not_ running under a hypervisor) devices also accumulate instructions and cycles at each context switch. 11These two metrics are abbreviated to cycles-per-instruction, or CPI, for brevity. 12ARM64 devices can also track task and thread energy in nanojoules, 13but only at the granularity of thread context switch, 14not between user and system. 15 16 17By default, Recount tracks its counters per-CPU kind (e.g. performance or efficiency) for threads, per-CPU for tasks, and per-CPU kind for coalitions. 18 19## High-Level Interfaces 20 21These interfaces report counter data to user space and are backed by Recount. 22 23| Interface | Entity | Target | Tests | Time | CPI | Energy | Perf Levels | Secure | 24| --------------------------: | ----------- | ------------- | :---: | :--: | :-: | :----: | :---------: | :----: | 25| `getrusage` | task | self/children | FP | ✓¹ | | | | | 26| `prod_pid_rusage` | task | pid | FP | ✓ | ✓ | ✓ | ✓² | ✓² | 27| `PROC_PIDTASKINFO` | task | pid | FP | ✓ | ✓ | | ✓² | | 28| `TASK_BASIC_INFO` | task | task port | FP | ✓¹ | | | | | 29| `TASK_ABSOLUTETIME_INFO` | task | task port | FP | ✓ | | | | | 30| `TASK_POWER_INFO` | task | task port | FP | ✓ | | | | | 31| `TASK_INSPECT_BASIC_COUNTS` | task | task inspect | P | | ✓ | | | | 32| `THREAD_BASIC_INFO` | thread | thread port | P | ✓ | | | | | 33| `THREAD_EXTENDED_INFO` | thread | thread port | | ✓ | | | | | 34| `proc_threadinfo` | thread | thread ID | | ✓ | | | | | 35| `proc_threadcounts` | thread | thread ID | F | ✓ | ✓ | ✓ | ✓ | | 36| `thread_selfcounts` | thread | self | FP | ✓ | ✓ | ✓ | ✓ | | 37| `thread_selfusage` | thread | self | FP | ✓ | | | | | 38| `coalition_info` | coalition | coalition ID | F | ✓ | ✓ | ✓ | ✓² | | 39| `HOST_CPU_LOAD_INFO` | system | all | | ✓ | | | | | 40| `PROCESSOR_CPU_LOAD_INFO` | processor | port | | ✓ | | | | | 41| `stackshot` | task/thread | all | P | ✓ | ✓ | | ✓² | | 42| DTrace | thread | any | | ✓ | ✓ | | | | 43| kperf | task/thread | any | | ✓ | ✓ | | ✓² | | 44 45- Under Tests, "F" is functional and "P" is performance. 46- ¹ Time precision is microseconds. 47- ² These return overall totals and hard-code a separate, P-core-only value. 48 49## LLDB 50 51The `recount` macro inspects counters in an LLDB session and is generally useful for retrospective analysis of CPU usage. 52Its subcommands print each metric as a column and then uses rows for the groupings, like per-CPU or per-CPU kind values. 53Tables also include formulaic columns that can be derived from two metrics, like CPI or power. 54By default, it prints the times in seconds, but the `-M` flag switches the output to Mach time values. 55 56- `recount thread <thread-ptr> [...]` prints a table of per-CPU kind counts for threads. 57 58- `recount task <task-ptr> [...]` prints a table of per-CPU counts for tasks. 59 - `-T` prints the task's active thread counters in additional tables. 60 - `-F <name>` finds the task matching the provided name instead of using a task pointer. 61 62- `recount coalition <coalition-ptr>` prints a table of per-CPU kind counts for each coalition, not including the currently-active tasks. 63Coalition pointers can be found with the `showtaskcoalitions` macro, and should be _resource_ coalitions. 64 65- `recount processor <processor-ptr-or-cpu-id>` prints a table of counts for a processor. 66 - `-T` prints the processor's active thread counters in an additional table. 67 - `-A` includes all processors in the output. 68 69- `recount diagnose` prints information useful for debugging the Recount subsystem itself. 70 71- `recount triage` is meant to be used by the automated panic debug scripts. 72 73## Internals 74 75Accounting for groups of entities like threads and tasks starts with a `recount_plan_t`, declared using `RECOUNT_PLAN_DECLARE` and defined with `RECOUNT_PLAN_DEFINE`, which takes the topology, or granularity, of the counting. 76The plan topology defines how many `recount_usage` structures are needed. 77To count CPU resource usage, a `struct recount_usage` has the following fields: 78 79- `ru_metrics[RCT_LVL_COUNT]`: metrics accumulated in each exception level 80- `ru_energy_nj`: the energy consumed by a CPU, in nano-Joules with `CONFIG_PERVASIVE_ENERGY` 81 82The metrics are stored in a `recount_metrics` structure with the following fields: 83 84- `ru_time_mach`: the time spent, in Mach time units 85- `ru_cycles`: the cycles run by a CPU with `CONFIG_PERVASIVE_CPI` 86- `ru_instructions`: the instructions retired by a CPU with `CONFIG_PERVASIVE_CPI` 87 88At context switch, `recount_switch_thread` captures the hardware counters with `recount_snapshot` into a `struct recount_snap`. 89The CPU's previous snapshot, stored in the `_snaps_percpu` per-CPU variable, is subtracted from the new one to get a delta to add to the currently-executing entity's usage structure. 90The per-CPU variable is then updated with the current snapshot for the next switch. 91The user/kernel transition code calls `recount_leave_user` or `recount_enter_user`, which performs the same operation, except with `recount_snapshot_speculative`. 92It relies on other synchronization barriers in the transition code to provide keep the snapshot precise. 93During preemption, the context switch handler attributes metrics back to the level stored in each thread. 94On the boundaries of secure execution handoff, `recount_enter_secure` and `recount_leave_secure` update the current thread's level and attribute metrics back to the previous level. 95 96Processors also track their idle time separately from the usage structure with paired calls to `recount_processor_idle` and `recount_processor_run`. 97Idle time has no user component and doesn't consume instructions or cycles, so a full usage structure isn't necessary. 98It stores the last update time in a 64-bit value combined with a state stored in the top two bits to determine whether the processor is currently idle or active. 99 100A `struct recount_track` is the primary data structure found in threads, tasks, and processors. 101Tracks include a `recount_usage` structure but ensures that each is updated atomically with respect to readers. 102 103### Track Atomicity 104 105To ensure the accuracy of formulas involving multiple metrics, like CPI, all metrics must be updated atomically from the perspective of the reader. 106A traditional locking mechanism would prevent the writer from updating the counts while readers are present, so Recount uses a sequence lock instead. 107Writers make a generation count odd before updating any of the values and then set it back to even when all values are updated. 108Readers wait until the generation count becomes even before trying to read the values, and if the counter changes by the time they're done reading them, it retries the read. 109Since three entities need to be updated at once (thread, task, and processor), only the last update has a release barrier to publish the writes. 110When reporting just user and system time, taking the sequence lock as a reader introduced unacceptable overhead. 111The sequence lock doesn't need to be taken for these metrics since they're never updated simultaneously. 112 113The coalition counters are not updated by threads switching off-CPU and are instead protected by the coalition lock while a task exits and rolls up its counters to the coalition. 114Reading the counters requires holding the lock and iterating the constituent tasks, grouping their per-CPU counters into per-CPU kind ones. 115 116### Energy 117 118The energy counters on ARM systems count a custom unit of energy that needs to be scaled to nanojoules. 119Because this unit can be very small and may overflow a 64-bit counter, it's scaled to nanojoules during context-switch. 120 121Unlike the other metrics, the energy counters are not sampled directly by Recount so the values cannot be tracked at user/kernel/secure granularity. 122 123## See Also 124 125- <doc:cpu_counters> 126