[RFC 01/14] SoundWire: Add SoundWire bus driver documentation

[Hardik Shah <hardik.t.shah@intel.com>]

This patch adds summary documentation of SoundWire bus driver support in
Linux.

Signed-off-by: Hardik Shah <hardik.t.shah@intel.com>
Signed-off-by: Sanyog Kale <sanyog.r.kale@intel.com>
Reviewed-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
---
 Documentation/sound/alsa/sdw/summary.txt |  253 ++++++++++++++++++++++++++++++
 1 file changed, 253 insertions(+)
 create mode 100644 Documentation/sound/alsa/sdw/summary.txt

diff --git a/Documentation/sound/alsa/sdw/summary.txt b/Documentation/sound/alsa/sdw/summary.txt
new file mode 100644
index 0000000..dc62817
--- /dev/null
+++ b/Documentation/sound/alsa/sdw/summary.txt
@@ -0,0 +1,253 @@
+SoundWire
+===========
+
+SoundWire is a new interface ratified in 2015 by the MIPI Alliance.
+SoundWire is used for transporting data typically related to audio
+functions. SoundWire interface is optimized to integrate audio devices
+in mobile or mobile inspired systems.
+
+SoundWire is a 2-Pin interface with data and clock line. It facilitates
+development of low cost, efficient, high performance systems. Broad
+level key features of SoundWire interface include:
+
+1. Transporting all of payload data channels, control information, and
+setup commands over a single two-pin interface.
+2. Lower clock frequency, and hence lower power consumption, by use of
+DDR (Dual Data Rate) data transmission.
+3. Clock scaling and optional multiple data lanes to give wide
+flexibility in data rate to match system requirements.
+4. Device status monitoring, including interrupt-style alerts to the
+Master.
+
+The SoundWire protocol supports up to eleven Slave interfaces. All the
+interfaces share the common bus containing data and clock line. Each of
+the Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated
+to audio transport. Data Port0 is dedicated to transport of Bulk control
+information, each of the audio Data Ports (1..14) can support up to 8
+Channels in transmit or receiving mode (typically fixed direction but
+configurable direction is enabled by the specification). Bandwidth
+restrictions to ~19.2..24.576Mbits/s don't however allow for 11*13*8
+channels to be transmitted simultaneously.
+
+Below figure shows the SoundWire Master and Slave devices sample
+connectivity.
+
+|---------------|                       Clock Signal    |---------------|
+|    Master     |-------|-------------------------------|    Slave      |
+|   Interface   |       |               Data Signal     |   Interface   |
+|               |-------|-------|-----------------------|       1       |
+|---------------|       |       |                       |---------------|
+                        |       |
+                        |       |
+                        |       |
+                     |---------------|
+                     |    Slave      |
+                     |   Interface   |
+                     |       2       |
+                     |---------------|
+
+Terminology
+=============
+
+Following is the terminology used in Linux kernel driver. SoundWire
+Master interfaces registers as SoundWire Master device and Slave
+interfaces as SoundWire Slave device.
+
+Bus:
+Similar to I2C/AC97 bus driver, implements Linux bus for SoundWire
+handles the SoundWire protocol and manages bus. Programs all the MIPI
+defined Slave registers.
+
+Master:
+Registers as SoundWire Master device (Linux Device). Similar to
+i2c_adapter. One bus instance is created for every Master interface
+registered to the bus driver.
+
+Slave:
+Registers as SoundWire Slave device (Linux Device). Similar to
+i2c_client.  Multiple Slave interfaces can register to same bus.
+
+Master driver:
+Driver controlling the Master device. Registers a set of ops to abstract
+Master registers away, so that the bus driver can control the bus in a
+hardware-agnostic manner.
+
+Slave driver:
+Driver controlling the Slave device. MIPI-specified registers are
+controlled directly by the bus driver (and transmitted through the
+Master driver/interface). Any implementation-defined Slave register is
+controlled by Slave driver. In practice, it is expected that the Slave
+driver relies on regmap and does not request direct register access.
+
+
+Programming interfaces (SoundWire Master interface Driver)
+==========================================================
+
+SoundWire bus driver supports programming interfaces for the SoundWire
+Master and SoundWire Slave devices. All the code uses the "sdw" prefix
+commonly used by SOC designers and 3rd party vendors.
+
+Each of the SoundWire Master interface needs to be registered to the Bus
+driver.  Master interface capabilities also needs to be registered to
+bus driver since there is no discovery mechanism as a part of SoundWire
+protocol.
+
+The Master interface along with the Master interface capabilities are
+registered based on board file, DT or ACPI.
+
+Following is the API to register the SoundWire Master device.
+
+static int my_sdw_register_master()
+{
+	struct sdw_master master;
+	struct sdw_master_capabilities *m_cap;
+
+	m_cap = &master.mstr_capabilities;
+
+	/*
+	 * Fill the Master device capability, this is required
+	 * by bus driver to handle bus configurations.
+	 */
+	m_cap->highphy_capable = false;
+	m_cap->monitor_handover_supported = false;
+	m_cap->sdw_dp0_supported = 1;
+	m_cap->num_data_ports = INTEL_SDW_MAX_PORTS;
+
+	return snd_sdw_master_add(&master);
+}
+
+Master driver gets registered for controlling the Master device. It
+provides the callback functions to the bus driver to control the bus in
+device specific way. Device and Driver binds according to the standard
+Linux device-driver bind model. Master driver is registered from the
+driver init code. Below code shows the sample Master driver
+registration.
+
+static struct sdw_master_driver intel_sdw_mstr_driver = {
+	.driver_type = SDW_DRIVER_TYPE_MASTER,
+	.driver = {
+		.name   = "intel_sdw_mstr",
+		.pm     = &intel_sdw_pm_ops,
+	},
+
+	.probe          = intel_sdw_probe,
+	.remove         = intel_sdw_remove,
+	.mstr_ops       = &intel_sdw_master_ops,
+	.mstr_port_ops = &intel_sdw_master_port_ops,
+};
+
+static int __init intel_sdw_init(void) {
+	return snd_sdw_master_register_driver(&intel_sdw_mstr_driver);
+}
+
+As shown above Master driver registers itself with  bus using
+"sdw_mstr_driver_register" API, It registers using set of "mstr_ops" and
+"mstr_port_ops" callback functions to the bus driver.
+
+"mstr_ops" is used by bus driver to control the bus in the hardware
+specific way. It includes bus control functions such as sending the
+SoundWire read/write messages on bus. The Bus driver also defines the
+clock frequency and frameshape allocation needed by active stream and
+configuration messages that need to be transmitted over the bus, to
+maximize the bandwidth needed while minimizing the power. The "mstr_ops"
+structure abstracts the hardware details of the Master from the bus
+driver for setting up of the clock frequency and frameshape.
+
+"mstr_port_ops" is used by bus driver to setup the Port parameters of
+the Master interface Port. Master interface Port register map is not
+defined by MIPI specification, so bus driver calls the "mstr_port_ops"
+call back function to do Port operations like "Port Prepare", "Port
+Transport params set", "Port enable and disable". The implementation of
+the Master driver can then perform hardware-specific configurations.
+
+Programming interfaces (SoundWire Slave Driver)
+===============================================
+
+The MIPI specification requires each Slave interface to expose a unique
+48-bit identifier, stored in 6 read only dev_id registers. This dev_id
+identifier contains vendor and part information, as well as a field
+enabling to differentiate between identical components. An additional
+class field is currently unused.  Slave driver is written for the
+specific 48-bit identifier, Bus driver enumerates the Slave device based
+on in 48-bit identifier. Slave device and driver match is done based on
+this 48-bit identifier. Probe of the Slave driver is called by bus on
+successful match between device and driver id. A parent/child
+relationship is enforced between Slave and Master devices (the logical
+representation is aligned with the physical connectivity).
+
+The information on Master/Slave dependencies is stored in platform data,
+board-file, ACPI or DT. The MIPI Software specification defines an
+additional link_id parameters for controllers that have multiple Master
+interfaces. The dev_id registers are only unique in the scope of a link,
+and the link_ID unique in the scope of a controller. Both dev_id and
+link_id are not necessarily unique at the system level but the
+parent/child information is used to avoid ambiguity.
+
+
+static const struct sdw_slave_id intel_id[] = {
+	{"0b:00:f9:84:01:02", 0},
+	{},
+};
+
+MODULE_DEVICE_TABLE(sdw, intel_id);
+
+static struct sdw_slave_driver intel_sdw_driver = {
+	.driver_type = SDW_DRIVER_TYPE_SLAVE,
+	.driver = {
+		.name = "intel",
+	},
+	.probe = intel_sdw_probe,
+	.remove = intel_sdw_remove,
+	.id_table = intel_id,
+};
+
+module_sdw_slave_driver(intel_sdw_driver);
+
+Slave driver needs to register the capabilities (number of ports,
+formats supported, etc) of the Slave device to the bus driver after
+registration.  This is the first call to be called by Slave driver on
+probe. Bus driver needs to know a set of Slave capabilities to program
+Slave registers and to control the bus reconfigurations.
+
+Below code shows the sample for it. Bus drivers programs the MIPI
+defined registers of the Slave.
+
+static int slave_register_sdw_capabilities(struct sdw_slave *sdw,
+                                 const struct sdw_slave_id *sdw_id)
+{
+	struct sdw_slv_capabilities cap;
+	struct sdw_slv_dpn_capabilities *dpn_cap = NULL;
+	struct port_audio_mode_properties *prop = NULL;
+	int i, j;
+
+	cap.wake_up_unavailable = true;
+	cap.test_mode_supported = false;
+	cap.clock_stop1_mode_supported = false;
+	cap.simplified_clock_stop_prepare = false;
+	cap.highphy_capable = true;
+	cap.paging_supported = false;
+	cap.bank_delay_support = false;
+	cap.port_15_read_behavior = 0;
+	cap.sdw_dp0_supported = false;
+	cap.num_of_sdw_ports = 3;
+	[...] additional configuration.
+
+		return snd_sdw_slave_register_caps(sdw, &cap);
+
+}
+
+Future enhancements to be done:
+===============================
+
+1. Currently BRA transfers is not supported.
+2. Bus driver supports only Single Data lane Slaves and Masters
+interfaces.
+
+Links:
+=====
+
+SoundWire MIPI specification 1.1 is available at:
+https://members.mipi.org/wg/All-Members/document/70290
+
+SoundWire MIPI DisCo (Discovery and Configuration) specification is in
+press.
-- 
1.7.9.5