[PATCH v22 07/10] lib/hpcc: Document that accuracy is a property of settled counters

[Mathieu Desnoyers]

Answer a report from Sashiko at:
https://sashiko.dev/#/patchset/20260901182857.26690-1-mathieu.desnoyers@xxxxxxxxxxxx

This change is documentation only. The bound describes a settled tree;
the two-counter comparisons read their operands independently. No code
change.

I considered and rejected the preempt_disable() proposed by Sashiko and
an alternative dual pre/post counters design.

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@xxxxxxxxxxxx>
Cc: "Paul E. McKenney" <paulmck@xxxxxxxxxx>
Cc: Steven Rostedt <rostedt@xxxxxxxxxxx>
Cc: Masami Hiramatsu <mhiramat@xxxxxxxxxx>
Cc: Dennis Zhou <dennis@xxxxxxxxxx>
Cc: Tejun Heo <tj@xxxxxxxxxx>
Cc: Christoph Lameter <cl@xxxxxxxxx>
Cc: Martin Liu <liumartin@xxxxxxxxxx>
Cc: David Rientjes <rientjes@xxxxxxxxxx>
Cc: christian.koenig@xxxxxxx
Cc: Shakeel Butt <shakeel.butt@xxxxxxxxx>
Cc: SeongJae Park <sj@xxxxxxxxxx>
Cc: Michal Hocko <mhocko@xxxxxxxx>
Cc: Johannes Weiner <hannes@xxxxxxxxxxx>
Cc: Sweet Tea Dorminy <sweettea-kernel@xxxxxxxxxx>
Cc: Lorenzo Stoakes <ljs@xxxxxxxxxx>
Cc: Liam R. Howlett <liam@xxxxxxxxxxxxx>
Cc: Mike Rapoport <rppt@xxxxxxxxxx>
Cc: Suren Baghdasaryan <surenb@xxxxxxxxxx>
Cc: Vlastimil Babka <vbabka@xxxxxxxxxx>
Cc: Christian Brauner <brauner@xxxxxxxxxx>
Cc: Wei Yang <richard.weiyang@xxxxxxxxx>
Cc: David Hildenbrand <david@xxxxxxxxxx>
Cc: Miaohe Lin <linmiaohe@xxxxxxxxxx>
Cc: Al Viro <viro@xxxxxxxxxxxxxxxxxx>
Cc: Yu Zhao <yuzhao@xxxxxxxxxx>
Cc: Roman Gushchin <roman.gushchin@xxxxxxxxx>
Cc: Mateusz Guzik <mjguzik@xxxxxxxxx>
Cc: Matthew Wilcox <willy@xxxxxxxxxxxxx>
Cc: Baolin Wang <baolin.wang@xxxxxxxxxxxxxxxxx>
Cc: Aboorva Devarajan <aboorvad@xxxxxxxxxxxxx>
Cc: David Carlier <devnexen@xxxxxxxxx>
Cc: Josh Law <objecting@xxxxxxxxxxxxx>
Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
Cc: linux-mm@xxxxxxxxx
---
 Documentation/core-api/percpu-counter-tree.rst |  4 ++++
 include/linux/percpu_counter_tree.h            | 10 +++++++---
 lib/percpu_counter_tree.c                      |  6 ++++--
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/Documentation/core-api/percpu-counter-tree.rst b/Documentation/core-api/percpu-counter-tree.rst
index 196da056e7b4..bb13e28bef11 100644
--- a/Documentation/core-api/percpu-counter-tree.rst
+++ b/Documentation/core-api/percpu-counter-tree.rst
@@ -43,6 +43,10 @@ This allows reading an approximated value at the root, which has a
 bounded accuracy (minimum/maximum possible precise sum range) determined
 by the tree topology.
 
+The bounded accuracy is a property of the settled tree. While updates are
+in flight the transient error can exceed it, bounded by the number of
+updaters and their increment size.
+
 Use Cases
 =========
 
diff --git a/include/linux/percpu_counter_tree.h b/include/linux/percpu_counter_tree.h
index 4095acdc879b..d593806b4ab2 100644
--- a/include/linux/percpu_counter_tree.h
+++ b/include/linux/percpu_counter_tree.h
@@ -93,7 +93,8 @@ struct percpu_counter_tree {
 	 * The "under" accuracy is larger than the "over" accuracy because the negative range of a
 	 * two's complement signed integer is one unit larger than the positive range. This delta
 	 * is summed for each tree item, which leads to a significantly larger "under" accuracy range
-	 * compared to the "over" accuracy range.
+	 * compared to the "over" accuracy range. The accuracy range is a bound on a settled counter:
+	 * one with no update in progress.
 	 */
 	struct {
 		unsigned long under;
@@ -169,6 +170,8 @@ long percpu_counter_tree_approximate_sum(struct percpu_counter_tree *counter)
  * slightly larger than the "over" range.
  * Those values are derived from the hardware topology and the counter tree batch size.
  * They are invariant for a given counter tree.
+ * The bounds describe a settled counter: one with no update in progress.
+ * An update in flight between its per-CPU increment and its carry propagation is not covered.
  * Using this function should not be typically required, see the following functions instead:
  * * percpu_counter_tree_approximate_compare(),
  * * percpu_counter_tree_approximate_compare_value(),
@@ -341,8 +344,9 @@ long percpu_counter_tree_precise_sum_positive(struct percpu_counter_tree *counte
  * @precise_min: Minimum possible value for precise sum (output).
  * @precise_max: Maximum possible value for precise sum (output).
  *
- * Calculate the minimum and maximum precise values for a given
- * approximation and (under, over) accuracy range.
+ * Calculate the minimum and maximum precise values for a given approximation
+ * and (under, over) accuracy range. The accuracy range is a bound on a settled
+ * tree: one with no update in progress.
  *
  * The range of the approximation as a function of the precise sum is expressed as:
  *
diff --git a/lib/percpu_counter_tree.c b/lib/percpu_counter_tree.c
index cfa5b04e05d7..cd71581f56bb 100644
--- a/lib/percpu_counter_tree.c
+++ b/lib/percpu_counter_tree.c
@@ -483,7 +483,8 @@ int compare_delta(long delta, unsigned long accuracy_neg, unsigned long accuracy
  * answer if the counters are found to be either less than or greater
  * than the other. However, if the approximated comparison returns
  * 0, the counters respective sums are found to be within the two
- * counters accuracy range.
+ * counters accuracy range. The two counters are read independently;
+ * the result is not an atomic snapshot of both.
  *
  * Return:
  * * %0		- Counters @a and @b do not differ by more than the sum of their respective
@@ -532,7 +533,8 @@ EXPORT_SYMBOL_GPL(percpu_counter_tree_approximate_compare_value);
  * As an optimization, it uses the approximate counter comparison
  * to quickly compare counters which are far apart. Only cases where
  * counter sums are within the accuracy range require precise counter
- * sums.
+ * sums. The two counters are read independently; the result is not an
+ * atomic snapshot of both.
  *
  * Return:
  * * %0		- Counters are equal.
-- 
2.43.0