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