Documentation/driver-api/soundwire/locking.rst

   1 =================
   2 SoundWire Locking
   3 =================
   4
   5 This document explains locking mechanism of the SoundWire Bus. Bus uses
   6 following locks in order to avoid race conditions in Bus operations on
   7 shared resources.
   8
   9   - Bus lock
  10
  11   - Message lock
  12
  13 Bus lock
  14 ========
  15
  16 SoundWire 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
  18 serialize 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
  26 Message lock
  27 ============
  28
  29 SoundWire message transfer lock. This mutex is part of
  30 Bus data structure (sdw_bus). This lock is used to serialize the message
  31 transfers (read/write) within a SoundWire Bus instance.
  32
  33 Below examples show how locks are acquired.
  34
  35 Example 1
  36 ---------
  37
  38 Message 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
  67 Example 2
  68 ---------
  69
  70 Prepare 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              +                               +