Documentation/driver-api/soundwire/locking.rst

File Facts

System

Linux kernel

Corpus path

Documentation/driver-api/soundwire/locking.rst

Extension

.rst

Size

3463 bytes

Lines

109

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.

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

=================
SoundWire Locking
=================

This document explains locking mechanism of the SoundWire Bus. Bus uses
following locks in order to avoid race conditions in Bus operations on
shared resources.

  - Bus lock

  - Message lock

Bus lock
========

SoundWire Bus lock is a mutex and is part of Bus data structure
(sdw_bus) which is used for every Bus instance. This lock is used to
serialize each of the following operations(s) within SoundWire Bus instance.

  - Addition and removal of Slave(s), changing Slave status.

  - Prepare, Enable, Disable and De-prepare stream operations.

  - Access of Stream data structure.

Message lock
============

SoundWire message transfer lock. This mutex is part of
Bus data structure (sdw_bus). This lock is used to serialize the message
transfers (read/write) within a SoundWire Bus instance.

Below examples show how locks are acquired.

Example 1
---------

Message transfer.

  1. For every message transfer

     a. Acquire Message lock.

     b. Transfer message (Read/Write) to Slave1 or broadcast message on
        Bus in case of bank switch.

     c. Release Message lock

     ::

	+----------+                    +---------+
	|          |                    |         |
	|   Bus    |                    | Master  |
	|          |                    | Driver  |
	|          |                    |         |
	+----+-----+                    +----+----+
	     |                               |
	     |     bus->ops->xfer_msg()      |
	     <-------------------------------+   a. Acquire Message lock
	     |                               |   b. Transfer message
	     |                               |
	     +------------------------------->   c. Release Message lock
	     |    return success/error       |   d. Return success/error
	     |                               |
	     +                               +

Example 2
---------

Prepare operation.

Annotation

• Atlas domain: Support Tooling And Documentation / Documentation.
• Implementation status: atlas-only.

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.