0001 ===========================
0002 SoundWire Subsystem Summary
0003 ===========================
0004
0005 SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
0006 SoundWire is used for transporting data typically related to audio
0007 functions. SoundWire interface is optimized to integrate audio devices in
0008 mobile or mobile inspired systems.
0009
0010 SoundWire is a 2-pin multi-drop interface with data and clock line. It
0011 facilitates development of low cost, efficient, high performance systems.
0012 Broad level key features of SoundWire interface include:
0013
0014 (1) Transporting all of payload data channels, control information, and setup
0015 commands over a single two-pin interface.
0016
0017 (2) Lower clock frequency, and hence lower power consumption, by use of DDR
0018 (Dual Data Rate) data transmission.
0019
0020 (3) Clock scaling and optional multiple data lanes to give wide flexibility
0021 in data rate to match system requirements.
0022
0023 (4) Device status monitoring, including interrupt-style alerts to the Master.
0024
0025 The SoundWire protocol supports up to eleven Slave interfaces. All the
0026 interfaces share the common Bus containing data and clock line. Each of the
0027 Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio
0028 transport. Data Port0 is dedicated to transport of Bulk control information,
0029 each of the audio Data Ports (1..14) can support up to 8 Channels in
0030 transmit or receiving mode (typically fixed direction but configurable
0031 direction is enabled by the specification). Bandwidth restrictions to
0032 ~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be
0033 transmitted simultaneously.
0034
0035 Below figure shows an example of connectivity between a SoundWire Master and
0036 two Slave devices. ::
0037
0038 +---------------+ +---------------+
0039 | | Clock Signal | |
0040 | Master |-------+-------------------------------| Slave |
0041 | Interface | | Data Signal | Interface 1 |
0042 | |-------|-------+-----------------------| |
0043 +---------------+ | | +---------------+
0044 | |
0045 | |
0046 | |
0047 +--+-------+--+
0048 | |
0049 | Slave |
0050 | Interface 2 |
0051 | |
0052 +-------------+
0053
0054
0055 Terminology
0056 ===========
0057
0058 The MIPI SoundWire specification uses the term 'device' to refer to a Master
0059 or Slave interface, which of course can be confusing. In this summary and
0060 code we use the term interface only to refer to the hardware. We follow the
0061 Linux device model by mapping each Slave interface connected on the bus as a
0062 device managed by a specific driver. The Linux SoundWire subsystem provides
0063 a framework to implement a SoundWire Slave driver with an API allowing
0064 3rd-party vendors to enable implementation-defined functionality while
0065 common setup/configuration tasks are handled by the bus.
0066
0067 Bus:
0068 Implements SoundWire Linux Bus which handles the SoundWire protocol.
0069 Programs all the MIPI-defined Slave registers. Represents a SoundWire
0070 Master. Multiple instances of Bus may be present in a system.
0071
0072 Slave:
0073 Registers as SoundWire Slave device (Linux Device). Multiple Slave devices
0074 can register to a Bus instance.
0075
0076 Slave driver:
0077 Driver controlling the Slave device. MIPI-specified registers are controlled
0078 directly by the Bus (and transmitted through the Master driver/interface).
0079 Any implementation-defined Slave register is controlled by Slave driver. In
0080 practice, it is expected that the Slave driver relies on regmap and does not
0081 request direct register access.
0082
0083 Programming interfaces (SoundWire Master interface Driver)
0084 ==========================================================
0085
0086 SoundWire Bus supports programming interfaces for the SoundWire Master
0087 implementation and SoundWire Slave devices. All the code uses the "sdw"
0088 prefix commonly used by SoC designers and 3rd party vendors.
0089
0090 Each of the SoundWire Master interfaces needs to be registered to the Bus.
0091 Bus implements API to read standard Master MIPI properties and also provides
0092 callback in Master ops for Master driver to implement its own functions that
0093 provides capabilities information. DT support is not implemented at this
0094 time but should be trivial to add since capabilities are enabled with the
0095 ``device_property_`` API.
0096
0097 The Master interface along with the Master interface capabilities are
0098 registered based on board file, DT or ACPI.
0099
0100 Following is the Bus API to register the SoundWire Bus:
0101
0102 .. code-block:: c
0103
0104 int sdw_bus_master_add(struct sdw_bus *bus,
0105 struct device *parent,
0106 struct fwnode_handle)
0107 {
0108 sdw_master_device_add(bus, parent, fwnode);
0109
0110 mutex_init(&bus->lock);
0111 INIT_LIST_HEAD(&bus->slaves);
0112
0113 /* Check ACPI for Slave devices */
0114 sdw_acpi_find_slaves(bus);
0115
0116 /* Check DT for Slave devices */
0117 sdw_of_find_slaves(bus);
0118
0119 return 0;
0120 }
0121
0122 This will initialize sdw_bus object for Master device. "sdw_master_ops" and
0123 "sdw_master_port_ops" callback functions are provided to the Bus.
0124
0125 "sdw_master_ops" is used by Bus to control the Bus in the hardware specific
0126 way. It includes Bus control functions such as sending the SoundWire
0127 read/write messages on Bus, setting up clock frequency & Stream
0128 Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
0129 hardware details of the Master from the Bus.
0130
0131 "sdw_master_port_ops" is used by Bus to setup the Port parameters of the
0132 Master interface Port. Master interface Port register map is not defined by
0133 MIPI specification, so Bus calls the "sdw_master_port_ops" callback
0134 function to do Port operations like "Port Prepare", "Port Transport params
0135 set", "Port enable and disable". The implementation of the Master driver can
0136 then perform hardware-specific configurations.
0137
0138 Programming interfaces (SoundWire Slave Driver)
0139 ===============================================
0140
0141 The MIPI specification requires each Slave interface to expose a unique
0142 48-bit identifier, stored in 6 read-only dev_id registers. This dev_id
0143 identifier contains vendor and part information, as well as a field enabling
0144 to differentiate between identical components. An additional class field is
0145 currently unused. Slave driver is written for a specific vendor and part
0146 identifier, Bus enumerates the Slave device based on these two ids.
0147 Slave device and driver match is done based on these two ids . Probe
0148 of the Slave driver is called by Bus on successful match between device and
0149 driver id. A parent/child relationship is enforced between Master and Slave
0150 devices (the logical representation is aligned with the physical
0151 connectivity).
0152
0153 The information on Master/Slave dependencies is stored in platform data,
0154 board-file, ACPI or DT. The MIPI Software specification defines additional
0155 link_id parameters for controllers that have multiple Master interfaces. The
0156 dev_id registers are only unique in the scope of a link, and the link_id
0157 unique in the scope of a controller. Both dev_id and link_id are not
0158 necessarily unique at the system level but the parent/child information is
0159 used to avoid ambiguity.
0160
0161 .. code-block:: c
0162
0163 static const struct sdw_device_id slave_id[] = {
0164 SDW_SLAVE_ENTRY(0x025d, 0x700, 0),
0165 {},
0166 };
0167 MODULE_DEVICE_TABLE(sdw, slave_id);
0168
0169 static struct sdw_driver slave_sdw_driver = {
0170 .driver = {
0171 .name = "slave_xxx",
0172 .pm = &slave_runtime_pm,
0173 },
0174 .probe = slave_sdw_probe,
0175 .remove = slave_sdw_remove,
0176 .ops = &slave_slave_ops,
0177 .id_table = slave_id,
0178 };
0179
0180
0181 For capabilities, Bus implements API to read standard Slave MIPI properties
0182 and also provides callback in Slave ops for Slave driver to implement own
0183 function that provides capabilities information. Bus needs to know a set of
0184 Slave capabilities to program Slave registers and to control the Bus
0185 reconfigurations.
0186
0187 Future enhancements to be done
0188 ==============================
0189
0190 (1) Bulk Register Access (BRA) transfers.
0191
0192
0193 (2) Multiple data lane support.
0194
0195 Links
0196 =====
0197
0198 SoundWire MIPI specification 1.1 is available at:
0199 https://members.mipi.org/wg/All-Members/document/70290
0200
0201 SoundWire MIPI DisCo (Discovery and Configuration) specification is
0202 available at:
0203 https://www.mipi.org/specifications/mipi-disco-soundwire
0204
0205 (publicly accessible with registration or directly accessible to MIPI
0206 members)
0207
0208 MIPI Alliance Manufacturer ID Page: mid.mipi.org
