Documentation / driver-api / soundwire / locking.rst


Based on kernel version 5.9. Page generated on 2020-10-14 09:35 EST.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
=================
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
	     |                               |
	     +                               +