tools/memory-model/Documentation/herd-representation.txt

File Facts

System

Linux kernel

Corpus path

tools/memory-model/Documentation/herd-representation.txt

Extension

.txt

Size

7972 bytes

Lines

114

Domain

Support Tooling And Documentation

Bucket

tools

Inferred role

Support Tooling And Documentation: documentation

Status

atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

• Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
• Uses kernel synchronization; read lock ordering, sleepability, and interrupt context assumptions before translating.

Dependency Surface

• No C-style include directives detected by the generator.

Detected Declarations

• No top-level syscall, struct, function, initcall, or export declaration detected by the generator.

Annotated Snippet

#
# Legend:
#	R,	a Load event
#	W,	a Store event
#	F,	a Fence event
#	LKR,	a Lock-Read event
#	LKW,	a Lock-Write event
#	UL,	an Unlock event
#	LF,	a Lock-Fail event
#	RL,	a Read-Locked event
#	RU,	a Read-Unlocked event
#	R*,	a Load event included in RMW
#	W*,	a Store event included in RMW
#	SRCU,	a Sleepable-Read-Copy-Update event
#
#	po,	a Program-Order link
#	rmw,	a Read-Modify-Write link - every rmw link is a po link
#
# By convention, a blank line in a cell means "same as the preceding line".
#
# Note that the syntactic representation does not always match the sets and
# relations in linux-kernel.cat, due to redefinitions in linux-kernel.bell and
# lock.cat. For example, the po link between LKR and LKW is upgraded to an rmw
# link, and W[ACQUIRE] are not included in the Acquire set.
#
# Disclaimer.  The table includes representations of "add" and "and" operations;
# corresponding/identical representations of "sub", "inc", "dec" and "or", "xor",
# "andnot" operations are omitted.
#
    ------------------------------------------------------------------------------
    |                        C macro | Events                                    |
    ------------------------------------------------------------------------------
    |                    Non-RMW ops |                                           |
    ------------------------------------------------------------------------------
    |                      READ_ONCE | R[ONCE]                                   |
    |                    atomic_read |                                           |
    |                     WRITE_ONCE | W[ONCE]                                   |
    |                     atomic_set |                                           |
    |               smp_load_acquire | R[ACQUIRE]                                |
    |            atomic_read_acquire |                                           |
    |              smp_store_release | W[RELEASE]                                |
    |             atomic_set_release |                                           |
    |                   smp_store_mb | W[ONCE] ->po F[MB]                        |
    |                         smp_mb | F[MB]                                     |
    |                        smp_rmb | F[rmb]                                    |
    |                        smp_wmb | F[wmb]                                    |
    |          smp_mb__before_atomic | F[before-atomic]                          |
    |           smp_mb__after_atomic | F[after-atomic]                           |
    |                    spin_unlock | UL                                        |
    |                 spin_is_locked | On success: RL                            |
    |                                | On failure: RU                            |
    |         smp_mb__after_spinlock | F[after-spinlock]                         |
    |      smp_mb__after_unlock_lock | F[after-unlock-lock]                      |
    |                  rcu_read_lock | F[rcu-lock]                               |
    |                rcu_read_unlock | F[rcu-unlock]                             |
    |                synchronize_rcu | F[sync-rcu]                               |
    |                rcu_dereference | R[ONCE]                                   |
    |             rcu_assign_pointer | W[RELEASE]                                |
    |                 srcu_read_lock | R[srcu-lock]                              |
    |                 srcu_down_read |                                           |
    |               srcu_read_unlock | W[srcu-unlock]                            |
    |                   srcu_up_read |                                           |
    |               synchronize_srcu | SRCU[sync-srcu]                           |
    | smp_mb__after_srcu_read_unlock | F[after-srcu-read-unlock]                 |
    ------------------------------------------------------------------------------
    |       RMW ops w/o return value |                                           |
    ------------------------------------------------------------------------------
    |                     atomic_add | R*[NORETURN] ->rmw W*[NORETURN]           |
    |                     atomic_and |                                           |
    |                      spin_lock | LKR ->po LKW                              |

Annotation

• Atlas domain: Support Tooling And Documentation / tools.
• Implementation status: atlas-only.
• Synchronization appears in or near this file; preserve lock ordering, sleepability, and interrupt-context constraints.

Implementation Notes

• This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
• Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
• Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.