| 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 |
Links |
| 188 |
===== |
| 189 |
|
| 190 |
SoundWire MIPI specification 1.1 is available at: |
| 191 |
https://members.mipi.org/wg/All-Members/document/70290 |
| 192 |
|
| 193 |
SoundWire MIPI DisCo (Discovery and Configuration) specification is |
| 194 |
available at: |
| 195 |
https://www.mipi.org/specifications/mipi-disco-soundwire |
| 196 |
|
| 197 |
(publicly accessible with registration or directly accessible to MIPI |
| 198 |
members) |
| 199 |
|
| 200 |
MIPI Alliance Manufacturer ID Page: mid.mipi.org |