be1038846b
There's an ascii artwork at Example 1 whose code-block is not properly
idented, causing those warnings.
Documentation/driver-api/soundwire/locking.rst:50: WARNING: Inconsistent literal block quoting.
Documentation/driver-api/soundwire/locking.rst:51: WARNING: Line block ends without a blank line.
Documentation/driver-api/soundwire/locking.rst:55: WARNING: Inline substitution_reference start-string without end-string.
Documentation/driver-api/soundwire/locking.rst:56: WARNING: Line block ends without a blank line.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Signed-off-by: Vinod Koul <vkoul@kernel.org>
109 lines
3.4 KiB
ReStructuredText
109 lines
3.4 KiB
ReStructuredText
=================
|
|
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.
|
|
|
|
1. Acquire lock for Bus instance associated with Master 1.
|
|
|
|
2. For every message transfer in Prepare operation
|
|
|
|
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.
|
|
|
|
3. Release lock for Bus instance associated with Master 1 ::
|
|
|
|
+----------+ +---------+
|
|
| | | |
|
|
| Bus | | Master |
|
|
| | | Driver |
|
|
| | | |
|
|
+----+-----+ +----+----+
|
|
| |
|
|
| sdw_prepare_stream() |
|
|
<-------------------------------+ 1. Acquire bus lock
|
|
| | 2. Perform stream prepare
|
|
| |
|
|
| |
|
|
| bus->ops->xfer_msg() |
|
|
<-------------------------------+ a. Acquire Message lock
|
|
| | b. Transfer message
|
|
| |
|
|
+-------------------------------> c. Release Message lock
|
|
| return success/error | d. Return success/error
|
|
| |
|
|
| |
|
|
| return success/error | 3. Release bus lock
|
|
+-------------------------------> 4. Return success/error
|
|
| |
|
|
+ +
|