1=================
2SoundWire Locking
3=================
4
5This document explains locking mechanism of the SoundWire Bus. Bus uses
6following locks in order to avoid race conditions in Bus operations on
7shared resources.
8
9  - Bus lock
10
11  - Message lock
12
13Bus lock
14========
15
16SoundWire Bus lock is a mutex and is part of Bus data structure
17(sdw_bus) which is used for every Bus instance. This lock is used to
18serialize each of the following operations(s) within SoundWire Bus instance.
19
20  - Addition and removal of Slave(s), changing Slave status.
21
22  - Prepare, Enable, Disable and De-prepare stream operations.
23
24  - Access of Stream data structure.
25
26Message lock
27============
28
29SoundWire message transfer lock. This mutex is part of
30Bus data structure (sdw_bus). This lock is used to serialize the message
31transfers (read/write) within a SoundWire Bus instance.
32
33Below examples show how locks are acquired.
34
35Example 1
36---------
37
38Message transfer.
39
40  1. For every message transfer
41
42     a. Acquire Message lock.
43
44     b. Transfer message (Read/Write) to Slave1 or broadcast message on
45        Bus in case of bank switch.
46
47     c. Release Message lock
48
49     ::
50
51	+----------+                    +---------+
52	|          |                    |         |
53	|   Bus    |                    | Master  |
54	|          |                    | Driver  |
55	|          |                    |         |
56	+----+-----+                    +----+----+
57	     |                               |
58	     |     bus->ops->xfer_msg()      |
59	     <-------------------------------+   a. Acquire Message lock
60	     |                               |   b. Transfer message
61	     |                               |
62	     +------------------------------->   c. Release Message lock
63	     |    return success/error       |   d. Return success/error
64	     |                               |
65	     +                               +
66
67Example 2
68---------
69
70Prepare operation.
71
72  1. Acquire lock for Bus instance associated with Master 1.
73
74  2. For every message transfer in Prepare operation
75
76     a. Acquire Message lock.
77
78     b. Transfer message (Read/Write) to Slave1 or broadcast message on
79        Bus in case of bank switch.
80
81     c. Release Message lock.
82
83  3. Release lock for Bus instance associated with Master 1 ::
84
85	+----------+                    +---------+
86	|          |                    |         |
87	|   Bus    |                    | Master  |
88	|          |                    | Driver  |
89	|          |                    |         |
90	+----+-----+                    +----+----+
91	     |                               |
92	     |    sdw_prepare_stream()       |
93	     <-------------------------------+   1. Acquire bus lock
94	     |                               |   2. Perform stream prepare
95	     |                               |
96	     |                               |
97	     |     bus->ops->xfer_msg()      |
98	     <-------------------------------+   a. Acquire Message lock
99	     |                               |   b. Transfer message
100	     |                               |
101	     +------------------------------->   c. Release Message lock
102	     |    return success/error       |   d. Return success/error
103	     |                               |
104	     |                               |
105	     |    return success/error       |   3. Release bus lock
106	     +------------------------------->   4. Return success/error
107	     |                               |
108	     +                               +
109