tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: Add SoundWire summary
SoundWire is a new Linux bus which implements a new MIPI bus protocol
'SoundWire'. The summary of SoundWire bus and API is documented in the
'summary' file.
Signed-off-by: Sanyog Kale <sanyog.r.kale@intel.com>
Signed-off-by: Hardik T Shah <hardik.t.shah@intel.com>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Acked-By: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Vinod Koul <vinod.koul@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Sanyog Kale
and committed by
Greg Kroah-Hartman
8ecf4264
09ca389c
+223
+1
Documentation/driver-api/index.rst
+1
Documentation/driver-api/index.rst
+15
Documentation/driver-api/soundwire/index.rst
+15
Documentation/driver-api/soundwire/index.rst
+207
Documentation/driver-api/soundwire/summary.rst
+207
Documentation/driver-api/soundwire/summary.rst
···
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_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
+
121
+
This 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
125
+
way. It includes Bus control functions such as sending the SoundWire
126
+
read/write messages on Bus, setting up clock frequency & Stream
127
+
Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
128
+
hardware details of the Master from the Bus.
129
+
130
+
"sdw_master_port_ops" is used by Bus to setup the Port parameters of the
131
+
Master interface Port. Master interface Port register map is not defined by
132
+
MIPI specification, so Bus calls the "sdw_master_port_ops" callback
133
+
function to do Port operations like "Port Prepare", "Port Transport params
134
+
set", "Port enable and disable". The implementation of the Master driver can
135
+
then perform hardware-specific configurations.
136
+
137
+
Programming interfaces (SoundWire Slave Driver)
138
+
===============================================
139
+
140
+
The MIPI specification requires each Slave interface to expose a unique
141
+
48-bit identifier, stored in 6 read-only dev_id registers. This dev_id
142
+
identifier contains vendor and part information, as well as a field enabling
143
+
to differentiate between identical components. An additional class field is
144
+
currently unused. Slave driver is written for a specific vendor and part
145
+
identifier, Bus enumerates the Slave device based on these two ids.
146
+
Slave device and driver match is done based on these two ids . Probe
147
+
of the Slave driver is called by Bus on successful match between device and
148
+
driver id. A parent/child relationship is enforced between Master and Slave
149
+
devices (the logical representation is aligned with the physical
150
+
connectivity).
151
+
152
+
The information on Master/Slave dependencies is stored in platform data,
153
+
board-file, ACPI or DT. The MIPI Software specification defines additional
154
+
link_id parameters for controllers that have multiple Master interfaces. The
155
+
dev_id registers are only unique in the scope of a link, and the link_id
156
+
unique in the scope of a controller. Both dev_id and link_id are not
157
+
necessarily unique at the system level but the parent/child information is
158
+
used 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
+
180
+
For capabilities, Bus implements API to read standard Slave MIPI properties
181
+
and also provides callback in Slave ops for Slave driver to implement own
182
+
function that provides capabilities information. Bus needs to know a set of
183
+
Slave capabilities to program Slave registers and to control the Bus
184
+
reconfigurations.
185
+
186
+
Future enhancements to be done
187
+
==============================
188
+
189
+
(1) Bulk Register Access (BRA) transfers.
190
+
191
+
192
+
(2) Multiple data lane support.
193
+
194
+
Links
195
+
=====
196
+
197
+
SoundWire MIPI specification 1.1 is available at:
198
+
https://members.mipi.org/wg/All-Members/document/70290
199
+
200
+
SoundWire MIPI DisCo (Discovery and Configuration) specification is
201
+
available at:
202
+
https://www.mipi.org/specifications/mipi-disco-soundwire
203
+
204
+
(publicly accessible with registration or directly accessible to MIPI
205
+
members)
206
+
207
+
MIPI Alliance Manufacturer ID Page: mid.mipi.org