driver-api/soundwire/summary.rst

10 SoundWire is a 2-pin multi-drop interface with data and clock line. It
15      commands over a single two-pin interface.
23  (4) Device status monitoring, including interrupt-style alerts to the Master.
26 interfaces share the common Bus containing data and clock line. Each of the
38         +---------------+                                       +---------------+
40         |    Master     |-------+-------------------------------|    Slave      |
42         |               |-------|-------+-----------------------|               |
43         +---------------+       |       |                       +---------------+
47                              +--+-------+--+
52                              +-------------+
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
64 3rd-party vendors to enable implementation-defined functionality while
65 common setup/configuration tasks are handled by the bus.
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.
74 can register to a Bus instance.
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
86 SoundWire Bus supports programming interfaces for the SoundWire Master
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
100 Following is the Bus API to register the SoundWire Bus:
102 .. code-block:: c
104 	int sdw_bus_master_add(struct sdw_bus *bus,
108 		sdw_master_device_add(bus, parent, fwnode);
110 		mutex_init(&bus->lock);
111 		INIT_LIST_HEAD(&bus->slaves);
114 		sdw_acpi_find_slaves(bus);
117 		sdw_of_find_slaves(bus);
123 "sdw_master_port_ops" callback functions are provided to the Bus.
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
129 hardware details of the Master from the Bus.
131 "sdw_master_port_ops" is used by Bus to setup the Port parameters of the
133 MIPI specification, so Bus calls the "sdw_master_port_ops" callback
136 then perform hardware-specific configurations.
142 48-bit identifier, stored in 6 read-only dev_id registers. This dev_id
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.
148 of the Slave driver is called by Bus on successful match between device and
154 board-file, ACPI or DT. The MIPI Software specification defines additional
161 .. code-block:: c
181 For capabilities, Bus implements API to read standard Slave MIPI properties
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
199 https://members.mipi.org/wg/All-Members/document/70290
203 https://www.mipi.org/specifications/mipi-disco-soundwire