Documentation/locking/locktypes.rst

File Facts

System

Linux kernel

Corpus path

Documentation/locking/locktypes.rst

Extension

.rst

Size

18128 bytes

Lines

556

Domain

Support Tooling And Documentation

Bucket

Documentation

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.
• Allocates kernel memory; connect allocation flags and lifetime to context constraints.
• Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

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

Detected Declarations

• function func1
• function func2
• function func3
• function func3
• function func2
• function func3
• function migrate_disable
• function migrate_disable

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

.. _kernel_hacking_locktypes:

==========================
Lock types and their rules
==========================

Introduction
============

The kernel provides a variety of locking primitives which can be divided
into three categories:

 - Sleeping locks
 - CPU local locks
 - Spinning locks

This document conceptually describes these lock types and provides rules
for their nesting, including the rules for use under PREEMPT_RT.


Lock categories
===============

Sleeping locks
--------------

Sleeping locks can only be acquired in preemptible task context.

Although implementations allow try_lock() from other contexts, it is
necessary to carefully evaluate the safety of unlock() as well as of
try_lock().  Furthermore, it is also necessary to evaluate the debugging
versions of these primitives.  In short, don't acquire sleeping locks from
other contexts unless there is no other option.

Sleeping lock types:

 - mutex
 - rt_mutex
 - semaphore
 - rw_semaphore
 - ww_mutex
 - percpu_rw_semaphore

On PREEMPT_RT kernels, these lock types are converted to sleeping locks:

 - local_lock
 - spinlock_t
 - rwlock_t


CPU local locks
---------------

 - local_lock

On non-PREEMPT_RT kernels, local_lock functions are wrappers around
preemption and interrupt disabling primitives. Contrary to other locking
mechanisms, disabling preemption or interrupts are pure CPU local
concurrency control mechanisms and not suited for inter-CPU concurrency
control.


Spinning locks
--------------

 - raw_spinlock_t
 - bit spinlocks

Annotation

• Detected declarations: `function func1`, `function func2`, `function func3`, `function func3`, `function func2`, `function func3`, `function migrate_disable`, `function migrate_disable`.
• Atlas domain: Support Tooling And Documentation / Documentation.
• 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.