162306a36Sopenharmony_ci================= 262306a36Sopenharmony_ciSoundWire Locking 362306a36Sopenharmony_ci================= 462306a36Sopenharmony_ci 562306a36Sopenharmony_ciThis document explains locking mechanism of the SoundWire Bus. Bus uses 662306a36Sopenharmony_cifollowing locks in order to avoid race conditions in Bus operations on 762306a36Sopenharmony_cishared resources. 862306a36Sopenharmony_ci 962306a36Sopenharmony_ci - Bus lock 1062306a36Sopenharmony_ci 1162306a36Sopenharmony_ci - Message lock 1262306a36Sopenharmony_ci 1362306a36Sopenharmony_ciBus lock 1462306a36Sopenharmony_ci======== 1562306a36Sopenharmony_ci 1662306a36Sopenharmony_ciSoundWire Bus lock is a mutex and is part of Bus data structure 1762306a36Sopenharmony_ci(sdw_bus) which is used for every Bus instance. This lock is used to 1862306a36Sopenharmony_ciserialize each of the following operations(s) within SoundWire Bus instance. 1962306a36Sopenharmony_ci 2062306a36Sopenharmony_ci - Addition and removal of Slave(s), changing Slave status. 2162306a36Sopenharmony_ci 2262306a36Sopenharmony_ci - Prepare, Enable, Disable and De-prepare stream operations. 2362306a36Sopenharmony_ci 2462306a36Sopenharmony_ci - Access of Stream data structure. 2562306a36Sopenharmony_ci 2662306a36Sopenharmony_ciMessage lock 2762306a36Sopenharmony_ci============ 2862306a36Sopenharmony_ci 2962306a36Sopenharmony_ciSoundWire message transfer lock. This mutex is part of 3062306a36Sopenharmony_ciBus data structure (sdw_bus). This lock is used to serialize the message 3162306a36Sopenharmony_citransfers (read/write) within a SoundWire Bus instance. 3262306a36Sopenharmony_ci 3362306a36Sopenharmony_ciBelow examples show how locks are acquired. 3462306a36Sopenharmony_ci 3562306a36Sopenharmony_ciExample 1 3662306a36Sopenharmony_ci--------- 3762306a36Sopenharmony_ci 3862306a36Sopenharmony_ciMessage transfer. 3962306a36Sopenharmony_ci 4062306a36Sopenharmony_ci 1. For every message transfer 4162306a36Sopenharmony_ci 4262306a36Sopenharmony_ci a. Acquire Message lock. 4362306a36Sopenharmony_ci 4462306a36Sopenharmony_ci b. Transfer message (Read/Write) to Slave1 or broadcast message on 4562306a36Sopenharmony_ci Bus in case of bank switch. 4662306a36Sopenharmony_ci 4762306a36Sopenharmony_ci c. Release Message lock 4862306a36Sopenharmony_ci 4962306a36Sopenharmony_ci :: 5062306a36Sopenharmony_ci 5162306a36Sopenharmony_ci +----------+ +---------+ 5262306a36Sopenharmony_ci | | | | 5362306a36Sopenharmony_ci | Bus | | Master | 5462306a36Sopenharmony_ci | | | Driver | 5562306a36Sopenharmony_ci | | | | 5662306a36Sopenharmony_ci +----+-----+ +----+----+ 5762306a36Sopenharmony_ci | | 5862306a36Sopenharmony_ci | bus->ops->xfer_msg() | 5962306a36Sopenharmony_ci <-------------------------------+ a. Acquire Message lock 6062306a36Sopenharmony_ci | | b. Transfer message 6162306a36Sopenharmony_ci | | 6262306a36Sopenharmony_ci +-------------------------------> c. Release Message lock 6362306a36Sopenharmony_ci | return success/error | d. Return success/error 6462306a36Sopenharmony_ci | | 6562306a36Sopenharmony_ci + + 6662306a36Sopenharmony_ci 6762306a36Sopenharmony_ciExample 2 6862306a36Sopenharmony_ci--------- 6962306a36Sopenharmony_ci 7062306a36Sopenharmony_ciPrepare operation. 7162306a36Sopenharmony_ci 7262306a36Sopenharmony_ci 1. Acquire lock for Bus instance associated with Master 1. 7362306a36Sopenharmony_ci 7462306a36Sopenharmony_ci 2. For every message transfer in Prepare operation 7562306a36Sopenharmony_ci 7662306a36Sopenharmony_ci a. Acquire Message lock. 7762306a36Sopenharmony_ci 7862306a36Sopenharmony_ci b. Transfer message (Read/Write) to Slave1 or broadcast message on 7962306a36Sopenharmony_ci Bus in case of bank switch. 8062306a36Sopenharmony_ci 8162306a36Sopenharmony_ci c. Release Message lock. 8262306a36Sopenharmony_ci 8362306a36Sopenharmony_ci 3. Release lock for Bus instance associated with Master 1 :: 8462306a36Sopenharmony_ci 8562306a36Sopenharmony_ci +----------+ +---------+ 8662306a36Sopenharmony_ci | | | | 8762306a36Sopenharmony_ci | Bus | | Master | 8862306a36Sopenharmony_ci | | | Driver | 8962306a36Sopenharmony_ci | | | | 9062306a36Sopenharmony_ci +----+-----+ +----+----+ 9162306a36Sopenharmony_ci | | 9262306a36Sopenharmony_ci | sdw_prepare_stream() | 9362306a36Sopenharmony_ci <-------------------------------+ 1. Acquire bus lock 9462306a36Sopenharmony_ci | | 2. Perform stream prepare 9562306a36Sopenharmony_ci | | 9662306a36Sopenharmony_ci | | 9762306a36Sopenharmony_ci | bus->ops->xfer_msg() | 9862306a36Sopenharmony_ci <-------------------------------+ a. Acquire Message lock 9962306a36Sopenharmony_ci | | b. Transfer message 10062306a36Sopenharmony_ci | | 10162306a36Sopenharmony_ci +-------------------------------> c. Release Message lock 10262306a36Sopenharmony_ci | return success/error | d. Return success/error 10362306a36Sopenharmony_ci | | 10462306a36Sopenharmony_ci | | 10562306a36Sopenharmony_ci | return success/error | 3. Release bus lock 10662306a36Sopenharmony_ci +-------------------------------> 4. Return success/error 10762306a36Sopenharmony_ci | | 10862306a36Sopenharmony_ci + + 109