1 ===========================
2 SoundWire Subsystem Summary
3 ===========================
4
5 SoundWire is a new interface ratified in 2015
6 SoundWire is used for transporting data typica
7 functions. SoundWire interface is optimized to
8 mobile or mobile inspired systems.
9
10 SoundWire is a 2-pin multi-drop interface with
11 facilitates development of low cost, efficient
12 Broad level key features of SoundWire interfac
13
14 (1) Transporting all of payload data channels
15 commands over a single two-pin interface.
16
17 (2) Lower clock frequency, and hence lower po
18 (Dual Data Rate) data transmission.
19
20 (3) Clock scaling and optional multiple data
21 in data rate to match system requirements
22
23 (4) Device status monitoring, including inter
24
25 The SoundWire protocol supports up to eleven S
26 interfaces share the common Bus containing dat
27 Slaves can support up to 14 Data Ports. 13 Dat
28 transport. Data Port0 is dedicated to transpor
29 each of the audio Data Ports (1..14) can suppo
30 transmit or receiving mode (typically fixed di
31 direction is enabled by the specification). B
32 ~19.2..24.576Mbits/s don't however allow for 1
33 transmitted simultaneously.
34
35 Below figure shows an example of connectivity
36 two Slave devices. ::
37
38 +---------------+
39 | |
40 | Master |-------+-------------
41 | Interface | |
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
59 or Slave interface, which of course can be con
60 code we use the term interface only to refer t
61 Linux device model by mapping each Slave inter
62 device managed by a specific driver. The Linux
63 a framework to implement a SoundWire Slave dri
64 3rd-party vendors to enable implementation-def
65 common setup/configuration tasks are handled b
66
67 Bus:
68 Implements SoundWire Linux Bus which handles t
69 Programs all the MIPI-defined Slave registers.
70 Master. Multiple instances of Bus may be prese
71
72 Slave:
73 Registers as SoundWire Slave device (Linux Dev
74 can register to a Bus instance.
75
76 Slave driver:
77 Driver controlling the Slave device. MIPI-spec
78 directly by the Bus (and transmitted through t
79 Any implementation-defined Slave register is c
80 practice, it is expected that the Slave driver
81 request direct register access.
82
83 Programming interfaces (SoundWire Master inter
84 ==============================================
85
86 SoundWire Bus supports programming interfaces
87 implementation and SoundWire Slave devices. Al
88 prefix commonly used by SoC designers and 3rd
89
90 Each of the SoundWire Master interfaces needs
91 Bus implements API to read standard Master MIP
92 callback in Master ops for Master driver to im
93 provides capabilities information. DT support
94 time but should be trivial to add since capabi
95 ``device_property_`` API.
96
97 The Master interface along with the Master int
98 registered based on board file, DT or ACPI.
99
100 Following is the Bus API to register the Sound
101
102 .. code-block:: c
103
104 int sdw_bus_master_add(struct sdw_bus
105 struct device
106 struct fwnode_
107 {
108 sdw_master_device_add(bus, par
109
110 mutex_init(&bus->lock);
111 INIT_LIST_HEAD(&bus->slaves);
112
113 /* Check ACPI for Slave device
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
123 "sdw_master_port_ops" callback functions are p
124
125 "sdw_master_ops" is used by Bus to control the
126 way. It includes Bus control functions such as
127 read/write messages on Bus, setting up clock f
128 Synchronization Point (SSP). The "sdw_master_o
129 hardware details of the Master from the Bus.
130
131 "sdw_master_port_ops" is used by Bus to setup
132 Master interface Port. Master interface Port r
133 MIPI specification, so Bus calls the "sdw_mast
134 function to do Port operations like "Port Prep
135 set", "Port enable and disable". The implement
136 then perform hardware-specific configurations.
137
138 Programming interfaces (SoundWire Slave Driver
139 ==============================================
140
141 The MIPI specification requires each Slave int
142 48-bit identifier, stored in 6 read-only dev_i
143 identifier contains vendor and part informatio
144 to differentiate between identical components.
145 currently unused. Slave driver is written for
146 identifier, Bus enumerates the Slave device ba
147 Slave device and driver match is done based on
148 of the Slave driver is called by Bus on succes
149 driver id. A parent/child relationship is enfo
150 devices (the logical representation is aligned
151 connectivity).
152
153 The information on Master/Slave dependencies i
154 board-file, ACPI or DT. The MIPI Software spec
155 link_id parameters for controllers that have m
156 dev_id registers are only unique in the scope
157 unique in the scope of a controller. Both dev_
158 necessarily unique at the system level but the
159 used to avoid ambiguity.
160
161 .. code-block:: c
162
163 static const struct sdw_device_id slav
164 SDW_SLAVE_ENTRY(0x025d, 0x700,
165 {},
166 };
167 MODULE_DEVICE_TABLE(sdw, slave_id);
168
169 static struct sdw_driver slave_sdw_dri
170 .driver = {
171 .name = "slave_xxx"
172 .pm = &slave_runtim
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 s
182 and also provides callback in Slave ops for Sl
183 function that provides capabilities informatio
184 Slave capabilities to program Slave registers
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
199 https://members.mipi.org/wg/All-Members/docume
200
201 SoundWire MIPI DisCo (Discovery and Configurat
202 available at:
203 https://www.mipi.org/specifications/mipi-disco
204
205 (publicly accessible with registration or dire
206 members)
207
208 MIPI Alliance Manufacturer ID Page: mid.mipi.o
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.