locking.rst 3.4 KB

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