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