Documentation/driver-api/soundwire/summary.rst

   1 ===========================
   2 SoundWire Subsystem Summary
   3 ===========================
   4
   5 SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
   6 SoundWire is used for transporting data typically related to audio
   7 functions. SoundWire interface is optimized to integrate audio devices in
   8 mobile or mobile inspired systems.
   9
  10 SoundWire is a 2-pin multi-drop interface with data and clock line. It
  11 facilitates development of low cost, efficient, high performance systems.
  12 Broad level key features of SoundWire interface include:
  13
  14  (1) Transporting all of payload data channels, control information, and setup
  15      commands over a single two-pin interface.
  16
  17  (2) Lower clock frequency, and hence lower power consumption, by use of DDR
  18      (Dual Data Rate) data transmission.
  19
  20  (3) Clock scaling and optional multiple data lanes to give wide flexibility
  21      in data rate to match system requirements.
  22
  23  (4) Device status monitoring, including interrupt-style alerts to the Master.
  24
  25 The SoundWire protocol supports up to eleven Slave interfaces. All the
  26 interfaces share the common Bus containing data and clock line. Each of the
  27 Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio
  28 transport. Data Port0 is dedicated to transport of Bulk control information,
  29 each of the audio Data Ports (1..14) can support up to 8 Channels in
  30 transmit or receiving mode (typically fixed direction but configurable
  31 direction is enabled by the specification).  Bandwidth restrictions to
  32 ~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be
  33 transmitted simultaneously.
  34
  35 Below figure shows an example of connectivity between a SoundWire Master and
  36 two Slave devices. ::
  37
  38         +---------------+                                       +---------------+
  39         |               |                       Clock Signal    |               |
  40         |    Master     |-------+-------------------------------|    Slave      |
  41         |   Interface   |       |               Data Signal     |  Interface 1  |
  42         |               |-------|-------+-----------------------|               |
  43         +---------------+       |       |                       +---------------+
  44                                 |       |
  45                                 |       |
  46                                 |       |
  47                              +--+-------+--+
  48                              |             |
  49                              |   Slave     |
  50                              | Interface 2 |
  51                              |             |
  52                              +-------------+
  53
  54
  55 Terminology
  56 ===========
  57
  58 The MIPI SoundWire specification uses the term 'device' to refer to a Master
  59 or Slave interface, which of course can be confusing. In this summary and
  60 code we use the term interface only to refer to the hardware. We follow the
  61 Linux device model by mapping each Slave interface connected on the bus as a
  62 device managed by a specific driver. The Linux SoundWire subsystem provides
  63 a framework to implement a SoundWire Slave driver with an API allowing
  64 3rd-party vendors to enable implementation-defined functionality while
  65 common setup/configuration tasks are handled by the bus.
  66
  67 Bus:
  68 Implements SoundWire Linux Bus which handles the SoundWire protocol.
  69 Programs all the MIPI-defined Slave registers. Represents a SoundWire
  70 Master. Multiple instances of Bus may be present in a system.
  71
  72 Slave:
  73 Registers as SoundWire Slave device (Linux Device). Multiple Slave devices
  74 can register to a Bus instance.
  75
  76 Slave driver:
  77 Driver controlling the Slave device. MIPI-specified registers are controlled
  78 directly by the Bus (and transmitted through the Master driver/interface).
  79 Any implementation-defined Slave register is controlled by Slave driver. In
  80 practice, it is expected that the Slave driver relies on regmap and does not
  81 request direct register access.
  82
  83 Programming interfaces (SoundWire Master interface Driver)
  84 ==========================================================
  85
  86 SoundWire Bus supports programming interfaces for the SoundWire Master
  87 implementation and SoundWire Slave devices. All the code uses the "sdw"
  88 prefix commonly used by SoC designers and 3rd party vendors.
  89
  90 Each of the SoundWire Master interfaces needs to be registered to the Bus.
  91 Bus implements API to read standard Master MIPI properties and also provides
  92 callback in Master ops for Master driver to implement its own functions that
  93 provides capabilities information. DT support is not implemented at this
  94 time but should be trivial to add since capabilities are enabled with the
  95 ``device_property_`` API.
  96
  97 The Master interface along with the Master interface capabilities are
  98 registered based on board file, DT or ACPI.
  99
 100 Following is the Bus API to register the SoundWire Bus:
 101
 102 .. code-block:: c
 103
 104         int sdw_bus_master_add(struct sdw_bus *bus,
 105                                 struct device *parent,
 106                                 struct fwnode_handle)
 107         {
 108                 sdw_master_device_add(bus, parent, fwnode);
 109
 110                 mutex_init(&bus->lock);
 111                 INIT_LIST_HEAD(&bus->slaves);
 112
 113                 /* Check ACPI for Slave devices */
 114                 sdw_acpi_find_slaves(bus);
 115
 116                 /* Check DT for Slave devices */
 117                 sdw_of_find_slaves(bus);
 118
 119                 return 0;
 120         }
 121
 122 This will initialize sdw_bus object for Master device. "sdw_master_ops" and
 123 "sdw_master_port_ops" callback functions are provided to the Bus.
 124
 125 "sdw_master_ops" is used by Bus to control the Bus in the hardware specific
 126 way. It includes Bus control functions such as sending the SoundWire
 127 read/write messages on Bus, setting up clock frequency & Stream
 128 Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
 129 hardware details of the Master from the Bus.
 130
 131 "sdw_master_port_ops" is used by Bus to setup the Port parameters of the
 132 Master interface Port. Master interface Port register map is not defined by
 133 MIPI specification, so Bus calls the "sdw_master_port_ops" callback
 134 function to do Port operations like "Port Prepare", "Port Transport params
 135 set", "Port enable and disable". The implementation of the Master driver can
 136 then perform hardware-specific configurations.
 137
 138 Programming interfaces (SoundWire Slave Driver)
 139 ===============================================
 140
 141 The MIPI specification requires each Slave interface to expose a unique
 142 48-bit identifier, stored in 6 read-only dev_id registers. This dev_id
 143 identifier contains vendor and part information, as well as a field enabling
 144 to differentiate between identical components. An additional class field is
 145 currently unused. Slave driver is written for a specific vendor and part
 146 identifier, Bus enumerates the Slave device based on these two ids.
 147 Slave device and driver match is done based on these two ids . Probe
 148 of the Slave driver is called by Bus on successful match between device and
 149 driver id. A parent/child relationship is enforced between Master and Slave
 150 devices (the logical representation is aligned with the physical
 151 connectivity).
 152
 153 The information on Master/Slave dependencies is stored in platform data,
 154 board-file, ACPI or DT. The MIPI Software specification defines additional
 155 link_id parameters for controllers that have multiple Master interfaces. The
 156 dev_id registers are only unique in the scope of a link, and the link_id
 157 unique in the scope of a controller. Both dev_id and link_id are not
 158 necessarily unique at the system level but the parent/child information is
 159 used to avoid ambiguity.
 160
 161 .. code-block:: c
 162
 163         static const struct sdw_device_id slave_id[] = {
 164                 SDW_SLAVE_ENTRY(0x025d, 0x700, 0),
 165                 {},
 166         };
 167         MODULE_DEVICE_TABLE(sdw, slave_id);
 168
 169         static struct sdw_driver slave_sdw_driver = {
 170                 .driver = {
 171                            .name = "slave_xxx",
 172                            .pm = &slave_runtime_pm,
 173                            },
 174                 .probe = slave_sdw_probe,
 175                 .remove = slave_sdw_remove,
 176                 .ops = &slave_slave_ops,
 177                 .id_table = slave_id,
 178         };
 179
 180
 181 For capabilities, Bus implements API to read standard Slave MIPI properties
 182 and also provides callback in Slave ops for Slave driver to implement own
 183 function that provides capabilities information. Bus needs to know a set of
 184 Slave capabilities to program Slave registers and to control the Bus
 185 reconfigurations.
 186
 187 Future enhancements to be done
 188 ==============================
 189
 190  (1) Bulk Register Access (BRA) transfers.
 191
 192
 193  (2) Multiple data lane support.
 194
 195 Links
 196 =====
 197
 198 SoundWire MIPI specification 1.1 is available at:
 199 https://members.mipi.org/wg/All-Members/document/70290
 200
 201 SoundWire MIPI DisCo (Discovery and Configuration) specification is
 202 available at:
 203 https://www.mipi.org/specifications/mipi-disco-soundwire
 204
 205 (publicly accessible with registration or directly accessible to MIPI
 206 members)
 207
 208 MIPI Alliance Manufacturer ID Page: mid.mipi.org