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