• Introduction
• Relevant types of memory ordering
• Comparison of functions
  • case 1) - non-“Read/Modify/Write” (RMW) ops
  • case 2) - increment-based ops that return no value
  • case 3) - decrement-based RMW ops that return no value
  • case 4) - increment-based RMW ops that return a value
  • case 5) - generic dec/sub decrement-based RMW ops that return a value
  • case 6) other decrement-based RMW ops that return a value
  • case 7) - lock-based RMW

Introduction¶

The goal of refcount_t API is to provide a minimal API for implementingan object’s reference counters. While a generic architecture-independentimplementation from lib/refcount.c uses atomic operations underneath,there are a number of differences between some of therefcount_*() andatomic_*() functions with regards to the memory ordering guarantees.This document outlines the differences and provides respective examplesin order to help maintainers validate their code against the change inthese memory ordering guarantees.

The terms used through this document try to follow the formal LKMM defined intools/memory-model/Documentation/explanation.txt.

memory-barriers.txt and atomic_t.txt provide more background to thememory ordering in general and for atomic operations specifically.

Relevant types of memory ordering¶

In the absence of any memory ordering guarantees (i.e. fully unordered)atomics & refcounters only provide atomicity andprogram order (po) relation (on the same CPU). It guarantees thateachatomic_*() andrefcount_*() operation is atomic and instructionsare executed in program order on a single CPU.This is implemented using READ_ONCE()/WRITE_ONCE() andcompare-and-swap primitives.

A strong (full) memory ordering guarantees that all prior loads andstores (all po-earlier instructions) on the same CPU are completedbefore any po-later instruction is executed on the same CPU.It also guarantees that all po-earlier stores on the same CPUand all propagated stores from other CPUs must propagate to allother CPUs before any po-later instruction is executed on the originalCPU (A-cumulative property). This is implemented using smp_mb().

A RELEASE memory ordering guarantees that all prior loads andstores (all po-earlier instructions) on the same CPU are completedbefore the operation. It also guarantees that all po-earlierstores on the same CPU and all propagated stores from other CPUsmust propagate to all other CPUs before the release operation(A-cumulative property). This is implemented usingsmp_store_release().

An ACQUIRE memory ordering guarantees that all post loads andstores (all po-later instructions) on the same CPU arecompleted after the acquire operation. It also guarantees that allpo-later stores on the same CPU must propagate to all other CPUsafter the acquire operation executes. This is implemented usingsmp_acquire__after_ctrl_dep().

A control dependency (on success) for refcounters guarantees thatif a reference for an object was successfully obtained (referencecounter increment or addition happened, function returned true),then further stores are ordered against this operation.Control dependency on stores are not implemented using any explicitbarriers, but rely on CPU not to speculate on stores. This is onlya single CPU relation and provides no guarantees for other CPUs.

Comparison of functions¶