Locking Subsystem Details

Locking Subsystem Details

Lock Context Compatibility

Using the wrong lock type for the execution context causes deadlocks (sleeping in atomic context), missed wakeups, or priority inversion. The table below shows which lock types provide correct protection for data shared across the listed contexts.

The "vs" columns indicate whether the lock variant provides mutual exclusion against code running in that context. For example, spin_lock_bh is safe vs process and softirq context, but not vs hardirq context. The Sleeps column indicates whether acquiring the lock may sleep, which determines what other operations are legal while holding it (sleeping locks cannot be held in atomic context or under a spinlock).

Notes:

• spin_lock does not mask softirqs or hardirqs; data can still be accessed concurrently by softirq or hardirq handlers on the same CPU
  • Nesting spin_lock(lock_b) inside spin_lock_irq/_bh/_irqsave(lock_a) keeps whatever masking was in place from lock_a while lock_b is held. The locks MUST be nested for this to work.
• spin_lock_bh disables softirqs; use when the lock is shared between process context and softirq context
• See the IRQ-Safe Lock Variants section for guidance on choosing between spin_lock_irq and spin_lock_irqsave
• mutex and rwsem can only be used in process context because they may sleep; never hold a spinlock while acquiring a mutex/rwsem

Preemption, Migration, and IRQ Context

Confusing these three CPU-affinity mechanisms causes use-after-free on per-CPU data, races where code assumes it stays on the same CPU, or deadlocks from sleeping with preemption disabled.

• Preemption disabled (preempt_disable()/preempt_enable()): the current task stays on this CPU and will not be scheduled out, but IRQs can still occur. Per-CPU data access is safe. spin_lock() implicitly disables preemption on non-RT kernels (see PREEMPT_RT section for differences).
• Migration disabled (migrate_disable()/migrate_enable()): the task can be preempted (another task runs on this CPU) but will return to the same CPU. Useful when per-CPU data access does not need to be atomic but must stay on the same CPU across a longer operation.
• IRQs disabled (local_irq_disable()/local_irq_save()): no hardware interrupts will be delivered on this CPU. Implies preemption disabled (since the scheduler's timer tick is an IRQ). Required when sharing data between process/softirq context and hardirq handlers without a lock.
  • local_irq_disable(); spin_lock(lock_b); critical section; spin_unlock(lock_b); local_irq_enable();
    • critical section runs with IRQs off, just like spin_lock_irq() would provide

IRQ-Safe Lock Variants

Using the wrong variant causes deadlock: if a hardirq handler takes a lock that was already held by the interrupted code on the same CPU, the CPU spins forever waiting for itself. Use _irqsave when a lock is shared with interrupt handlers.

• spin_lock_irq()/spin_unlock_irq(): disables IRQs on lock, re-enables on unlock. Only safe when the caller knows IRQs are currently enabled.
• spin_lock_irqsave(lock, flags)/spin_unlock_irqrestore(lock, flags): saves current IRQ state, restores on unlock. Safe regardless of whether IRQs were already disabled. Use this when the calling context is unknown.
• Nesting: spin_lock_irqsave(lock1, flags1) inside spin_lock_irqsave(lock2, flags2) is safe as long as lock ordering is respected (no ABBA deadlocks)

When IRQs are already off:

• All holders of a lock shared with IRQ context must disable IRQs (or use _irqsave) to take it safely
• Plain spin_lock() (without IRQ masking) is safe from code paths that are only reachable when IRQs are already off
• spin_trylock() avoids the deadlock scenario: the deadlock only occurs when spin_lock() is called with IRQs off on a CPU that already holds the lock

PREEMPT_RT Differences

Code that works on non-RT kernels may deadlock or crash on PREEMPT_RT because spinlock_t becomes an rt_mutex-based preemptible lock. Any code path that disables preemption or IRQs while holding a spinlock_t will trigger a lockdep splat (BUG: Invalid wait context) on RT.

• spinlock_t: becomes an rt_mutex-based lock on RT. Acquisition may sleep on contention, and the holder can be preempted, but the critical section still cannot acquire a mutex or other sleeping lock (the lockdep wait-context hierarchy LD_WAIT_CONFIG < LD_WAIT_SLEEP forbids it). Must not be held in hardirq context or with preemption/IRQs explicitly disabled.
• raw_spinlock_t: remains a true spinning lock on RT. Never sleeps. Use for code that must run in hardirq context or with IRQs disabled even on RT (e.g., scheduler, interrupt controller, low-level timer code).
• local_irq_disable(): still disables IRQs on RT. Note that spin_lock_irq() on a spinlock_t does NOT disable IRQs on RT (it acquires the underlying rt_mutex without masking interrupts; see spin_lock_irq() in include/linux/spinlock_rt.h)

Seqlocks and Seqcounts

A seqlock is a reader-writer synchronization mechanism optimized for data that is read frequently and written rarely. Readers never block writers (no writer starvation).

How it works: readers speculatively read the data, then check a sequence counter to detect whether a writer was active during the read. If so, the read is retried. Writers increment the sequence counter before and after the update, and must serialize against each other.

Two variants exist: seqlock_t bundles a seqcount_spinlock_t with a spinlock_t that provides writer serialization automatically (see include/linux/seqlock_types.h). A bare seqcount_t can be used when writer serialization is provided by an external lock.

Use seqlocks when the protected data is small enough that retrying reads is cheap. Incorrect usage causes readers to use partially-updated data (missed retry) or infinite retry loops (side effects in the critical section that prevent convergence). Review both the reader and writer sides together.

Read side (see include/linux/seqlock.h):

• ALL code between read_seqbegin() and read_seqretry() is the critical section. If the writer was active, the entire section re-executes.
• The critical section must not have side effects (no allocations, no writes to shared state, no I/O) because it may run multiple times
• The critical section must not dereference pointers that could be freed by the writer; use rcu_dereference() for pointer-following under RCU

Write side:

• write_seqcount_begin()/write_seqcount_end() must be correctly paired; an unbalanced sequence count causes readers to either never retry (missing begin) or always retry in an infinite loop (missing end)
• raw_write_seqcount_begin()/raw_write_seqcount_end() skip the lockdep assertion that the write-serializing lock is held; only valid when serialization is provided by a different mechanism

Lock Nesting and Annotations

Taking the same lock type at multiple nesting levels without telling lockdep causes false-positive lockdep splats (or hides real deadlocks). Incorrect sparse annotations hide lock imbalance bugs from static analysis.

Nesting classes (see include/linux/lockdep_types.h):

• When code takes the same lock type at different levels (e.g., parent inode lock then child inode lock), use mutex_lock_nested(lock, subclass) or spin_lock_nested(lock, subclass) to tell lockdep they are different
• Lockdep supports up to MAX_LOCKDEP_SUBCLASSES (8) nesting levels
• Subclass 0 is the default; higher values indicate deeper nesting

Sparse annotations (include/linux/compiler_types.h):

• __must_hold(lock): function requires lock to be held on entry and exit
• __acquires(lock): function acquires lock (held on exit, not on entry)
• __releases(lock): function releases lock (held on entry, not on exit)
• Mismatched annotations cause sparse to report "context imbalance" warnings. Review any patch that adds or changes these annotations to verify they match the actual lock behavior.

RCU and Locking

Misunderstanding the relationship between RCU and traditional locks causes use-after-free (reading freed data in an RCU section) or unnecessary performance overhead (holding spinlocks where RCU suffices).

• rcu_read_lock() marks an RCU read-side critical section. Code must not sleep inside; use SRCU if sleeping is required.
• synchronize_rcu() blocks until all pre-existing RCU read-side critical sections complete (a full grace period)
• call_rcu(head, callback) defers callback execution until after a grace period; does not block
• SRCU (srcu_read_lock()/srcu_read_unlock()) allows sleeping in read sections; uses a domain-specific struct srcu_struct
• Holding spin_lock() or raw_spin_lock() implicitly provides RCU read-side protection. On non-RT kernels this is because they disable preemption; on PREEMPT_RT, spin_lock() calls rcu_read_lock() internally to preserve this guarantee (see __rt_spin_lock() in kernel/locking/spinlock_rt.c).

Memory Barriers

Assume the patch author's barrier usage is correct unless the usage is clearly wrong (e.g., missing a paired barrier, using smp_wmb() where a full smp_mb() is needed). Subtle barrier bugs require deep architecture knowledge to confirm.

• smp_mb(): full memory barrier. All loads and stores before the barrier appear to complete before all loads and stores after it.
• smp_rmb(): read barrier. Orders loads only; no effect on stores.
• smp_wmb(): write barrier. Orders stores only; no effect on loads.
• Barriers enforce ordering, not completion: they prevent CPU and compiler reordering across the barrier point
• Barriers must be paired between CPUs: if CPU A uses smp_wmb() before setting a flag, CPU B needs smp_rmb() after reading that flag to guarantee it sees the data written before the flag
• Common pattern (from Documentation/memory-barriers.txt):

  producer:                       consumer:
    my_data = value;                if (event_indicated) {
    smp_wmb();                          smp_rmb();
    event_indicated = 1;                do_something(my_data);
                                    }
  

• atomic_read() and atomic_set() provide relaxed ordering only; they guarantee atomicity of the access but do not imply memory barriers. RMW operations that return values (e.g., atomic_add_return(), atomic_cmpxchg()) provide full ordering. Use smp_load_acquire() / smp_store_release() or the _acquire/_release atomic variants when ordering is needed for plain loads and stores.

Lockdep Lock Pinning (lockdep_pin_lock/lockdep_unpin_lock)

Misusing lockdep_pin_lock() triggers false positive lockdep warnings ("releasing a pinned lock") that mask real bugs or cause CI failures.

How lock pinning works (see lock_pin_lock() in kernel/locking/lockdep.c):

• lockdep_pin_lock(lock) finds the held_lock entry for lock in the current task's lock stack and increments its pin_count
• When any held lock is released, lockdep checks hlock->pin_count via find_held_lock() and warns if the pin_count is non-zero
• Matching uses match_held_lock(), which compares by lock instance first. For ww_mutex-based locks (e.g., dma_resv) where multiple instances with a nest_lock share a single held_lock entry via reference counting, matching falls back to lock class comparison

Problematic pattern with ww_mutex locks:

When multiple ww_mutex locks of the same class are held with the same nest_lock, lockdep folds them into a single held_lock entry with references > 0. Pinning that entry and then unlocking any of the folded instances triggers the "releasing a pinned lock" warning.

// WRONG: Pinning a ww_mutex-based lock when other instances may be unlocked
lockdep_pin_lock(&vm->resv->lock.base);
ttm_bo_validate(...);  // May lock/unlock OTHER bos' dma_resv locks
lockdep_unpin_lock(&vm->resv->lock.base);  // Lockdep warned during validate!

When lock pinning is safe:

• The pinned region only manipulates the specific pinned lock instance
• No subsystem callbacks are invoked that might release the pinned lock or, for ww_mutex-based locks, other instances sharing the held_lock entry
• No iteration over lists of objects that share the lock class

Alternative approaches when pinning is not safe:

• Use a simple flag or pointer variable to track the state that pinning was meant to enforce (e.g., vm->validating = current)
• Use lockdep_assert_held() checks at critical points instead of continuous pinning
• Document the invariant rather than trying to enforce it through pinning

Quick Checks

Common locking review pitfalls. Missing any of these causes deadlocks, data corruption, or crashes that may only reproduce under specific timing or on RT/SMP configurations.

• Lock drop and reacquire: when a lock is dropped and retaken (e.g., to call a sleeping function), all data protected by that lock may have changed. Verify the code re-validates pointers, refcounts, and conditions after reacquiring. A common bug is using a stale pointer to the locked object after the lock was transiently dropped.
• Functions returning with different locks held: some functions acquire a new lock and release the original (e.g., lock rebalancing, hash table migration). Verify the caller knows which lock is held on return and releases the correct one.
• Reassigning locked objects: when code reassigns a pointer to a previously locked data structure (e.g., obj = next_obj in a loop), verify the old object's lock is properly released. A missed unlock leaves the lock held forever, causing deadlock on the next acquisition.
• raw_spinlock_t for hardirq paths on RT: on PREEMPT_RT, only raw_spinlock_t remains a true spinning lock. IRQ handlers that use spinlock_t will trigger a lockdep splat on RT kernels.
• Completion variables for event waiting: use wait_for_completion() / complete() instead of open-coded spinlock polling loops
• percpu_rw_semaphore for read-heavy patterns: when reads vastly outnumber writes, percpu_rw_semaphore avoids cache-line bouncing (see include/linux/percpu-rwsem.h)