Answer a report from Sashiko at: https://sashiko.dev/#/patchset/20260901182857.26690-1-mathieu.desnoyers@efficios.com 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 Cc: "Paul E. McKenney" Cc: Steven Rostedt Cc: Masami Hiramatsu Cc: Dennis Zhou Cc: Tejun Heo Cc: Christoph Lameter Cc: Martin Liu Cc: David Rientjes Cc: christian.koenig@amd.com Cc: Shakeel Butt Cc: SeongJae Park Cc: Michal Hocko Cc: Johannes Weiner Cc: Sweet Tea Dorminy Cc: Lorenzo Stoakes Cc: Liam R. Howlett Cc: Mike Rapoport Cc: Suren Baghdasaryan Cc: Vlastimil Babka Cc: Christian Brauner Cc: Wei Yang Cc: David Hildenbrand Cc: Miaohe Lin Cc: Al Viro Cc: Yu Zhao Cc: Roman Gushchin Cc: Mateusz Guzik Cc: Matthew Wilcox Cc: Baolin Wang Cc: Aboorva Devarajan Cc: David Carlier Cc: Josh Law Cc: Andrew Morton Cc: linux-mm@kvack.org --- 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