class CounterDesc

Kernel counters are a facility designed to help field diagnostics and

to help devs properly dimension the load/clients/size of the kernel

constructs. It answers questions like:

- after N seconds how many outstanding

<x

> things are allocated?

- up to this point has

<Y

> ever happened?

- up to this point what is min(

<Z

>) or max(

<Z

>)?

Currently the only query interface to the counters is the kcounter command.

Issue 'kcounter --help' to learn what it can do.

Kernel counters public API:

1- Define a new counter in a .cc file. Do not define a counter in a header

file as that may lead to the creation of multiple, unrelated counters. Do not

define multiple counters with the same name.

KCOUNTER(counter_name, "<counter name>");

KCOUNTER_DECLARE(counter_name, "<counter name>", Sum);

KCOUNTER_DECLARE(counter_name, "<counter name>", Min);

KCOUNTER_DECLARE(counter_name, "<counter name>", Max);

2- Counters start at zero, but can be set to other values during startup.

Update the counter using sum, min, or max operations:

kcounter_add(counter_name, 1);

kcounter_min(counter_name, 1);

kcounter_max(counter_name, 1);

By default with KCOUNTER, the `kcounter` presentation will calculate a sum()

across cores. The Min and Max presentation types can be specified by using

KCOUNTER_DECLARE and will present with a min() or max() across cores,

respectively.

Naming the counters

The naming convention is "subsystem.thing_or_action"

for example "dispatcher.destroy"

"exceptions.fpu"

"handles.live"

The counter update methods use relaxed atomic loads and stores only to avoid

formal data races in the C++ memory model, not to ensure atomicity with

respect to concurrent updates. Consistency under concurrent updates may

require read-modify-write operations on some architectures, which can

incur significant code gen complexity and runtime overhead, particularly

when preemption/interrupts are not disabled during updates. Since counters

are expected to be used in situations where concurrent updates are unlikely,

and where performance outweighs absolute accuracy, the operations are not

required to be atomic with respect to concurrent updates.

The following provides some motivating comparisons of code gen on armv8-a:

https://godbolt.org/z/osz68aKq6

**NOTE**: Because the accuracy and consistency of the counter values is not

guaranteed, care must be taken when reading the counter values in non-

diagnostic code. In the appropriate diagnostic use cases, counter values may

be read via |ValueCurrCpu|, |SumAcrossAllCpus|, |MinAcrossAllCpus|, or

|MaxAcrossAllCpus|. When using these methods, please include comments to make

it clear that the values are NOT reliable for production logic or non-

diagnostic purposes.