v4.19.13 snapshot.
diff --git a/Documentation/driver-api/soundwire/error_handling.rst b/Documentation/driver-api/soundwire/error_handling.rst
new file mode 100644
index 0000000..aa3a0a2
--- /dev/null
+++ b/Documentation/driver-api/soundwire/error_handling.rst
@@ -0,0 +1,65 @@
+========================
+SoundWire Error Handling
+========================
+
+The SoundWire PHY was designed with care and errors on the bus are going to
+be very unlikely, and if they happen it should be limited to single bit
+errors. Examples of this design can be found in the synchronization
+mechanism (sync loss after two errors) and short CRCs used for the Bulk
+Register Access.
+
+The errors can be detected with multiple mechanisms:
+
+1. Bus clash or parity errors: This mechanism relies on low-level detectors
+ that are independent of the payload and usages, and they cover both control
+ and audio data. The current implementation only logs such errors.
+ Improvements could be invalidating an entire programming sequence and
+ restarting from a known position. In the case of such errors outside of a
+ control/command sequence, there is no concealment or recovery for audio
+ data enabled by the SoundWire protocol, the location of the error will also
+ impact its audibility (most-significant bits will be more impacted in PCM),
+ and after a number of such errors are detected the bus might be reset. Note
+ that bus clashes due to programming errors (two streams using the same bit
+ slots) or electrical issues during the transmit/receive transition cannot
+ be distinguished, although a recurring bus clash when audio is enabled is a
+ indication of a bus allocation issue. The interrupt mechanism can also help
+ identify Slaves which detected a Bus Clash or a Parity Error, but they may
+ not be responsible for the errors so resetting them individually is not a
+ viable recovery strategy.
+
+2. Command status: Each command is associated with a status, which only
+ covers transmission of the data between devices. The ACK status indicates
+ that the command was received and will be executed by the end of the
+ current frame. A NAK indicates that the command was in error and will not
+ be applied. In case of a bad programming (command sent to non-existent
+ Slave or to a non-implemented register) or electrical issue, no response
+ signals the command was ignored. Some Master implementations allow for a
+ command to be retransmitted several times. If the retransmission fails,
+ backtracking and restarting the entire programming sequence might be a
+ solution. Alternatively some implementations might directly issue a bus
+ reset and re-enumerate all devices.
+
+3. Timeouts: In a number of cases such as ChannelPrepare or
+ ClockStopPrepare, the bus driver is supposed to poll a register field until
+ it transitions to a NotFinished value of zero. The MIPI SoundWire spec 1.1
+ does not define timeouts but the MIPI SoundWire DisCo document adds
+ recommendation on timeouts. If such configurations do not complete, the
+ driver will return a -ETIMEOUT. Such timeouts are symptoms of a faulty
+ Slave device and are likely impossible to recover from.
+
+Errors during global reconfiguration sequences are extremely difficult to
+handle:
+
+1. BankSwitch: An error during the last command issuing a BankSwitch is
+ difficult to backtrack from. Retransmitting the Bank Switch command may be
+ possible in a single segment setup, but this can lead to synchronization
+ problems when enabling multiple bus segments (a command with side effects
+ such as frame reconfiguration would be handled at different times). A global
+ hard-reset might be the best solution.
+
+Note that SoundWire does not provide a mechanism to detect illegal values
+written in valid registers. In a number of cases the standard even mentions
+that the Slave might behave in implementation-defined ways. The bus
+implementation does not provide a recovery mechanism for such errors, Slave
+or Master driver implementers are responsible for writing valid values in
+valid registers and implement additional range checking if needed.
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
new file mode 100644
index 0000000..6db0260
--- /dev/null
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -0,0 +1,18 @@
+=======================
+SoundWire Documentation
+=======================
+
+.. toctree::
+ :maxdepth: 1
+
+ summary
+ stream
+ error_handling
+ locking
+
+.. only:: subproject
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/driver-api/soundwire/locking.rst b/Documentation/driver-api/soundwire/locking.rst
new file mode 100644
index 0000000..253f735
--- /dev/null
+++ b/Documentation/driver-api/soundwire/locking.rst
@@ -0,0 +1,106 @@
+=================
+SoundWire Locking
+=================
+
+This document explains locking mechanism of the SoundWire Bus. Bus uses
+following locks in order to avoid race conditions in Bus operations on
+shared resources.
+
+ - Bus lock
+
+ - Message lock
+
+Bus lock
+========
+
+SoundWire Bus lock is a mutex and is part of Bus data structure
+(sdw_bus) which is used for every Bus instance. This lock is used to
+serialize each of the following operations(s) within SoundWire Bus instance.
+
+ - Addition and removal of Slave(s), changing Slave status.
+
+ - Prepare, Enable, Disable and De-prepare stream operations.
+
+ - Access of Stream data structure.
+
+Message lock
+============
+
+SoundWire message transfer lock. This mutex is part of
+Bus data structure (sdw_bus). This lock is used to serialize the message
+transfers (read/write) within a SoundWire Bus instance.
+
+Below examples show how locks are acquired.
+
+Example 1
+---------
+
+Message transfer.
+
+ 1. For every message transfer
+
+ a. Acquire Message lock.
+
+ b. Transfer message (Read/Write) to Slave1 or broadcast message on
+ Bus in case of bank switch.
+
+ c. Release Message lock ::
+
+ +----------+ +---------+
+ | | | |
+ | Bus | | Master |
+ | | | Driver |
+ | | | |
+ +----+-----+ +----+----+
+ | |
+ | bus->ops->xfer_msg() |
+ <-------------------------------+ a. Acquire Message lock
+ | | b. Transfer message
+ | |
+ +-------------------------------> c. Release Message lock
+ | return success/error | d. Return success/error
+ | |
+ + +
+
+Example 2
+---------
+
+Prepare operation.
+
+ 1. Acquire lock for Bus instance associated with Master 1.
+
+ 2. For every message transfer in Prepare operation
+
+ a. Acquire Message lock.
+
+ b. Transfer message (Read/Write) to Slave1 or broadcast message on
+ Bus in case of bank switch.
+
+ c. Release Message lock.
+
+ 3. Release lock for Bus instance associated with Master 1 ::
+
+ +----------+ +---------+
+ | | | |
+ | Bus | | Master |
+ | | | Driver |
+ | | | |
+ +----+-----+ +----+----+
+ | |
+ | sdw_prepare_stream() |
+ <-------------------------------+ 1. Acquire bus lock
+ | | 2. Perform stream prepare
+ | |
+ | |
+ | bus->ops->xfer_msg() |
+ <-------------------------------+ a. Acquire Message lock
+ | | b. Transfer message
+ | |
+ +-------------------------------> c. Release Message lock
+ | return success/error | d. Return success/error
+ | |
+ | |
+ | return success/error | 3. Release bus lock
+ +-------------------------------> 4. Return success/error
+ | |
+ + +
diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst
new file mode 100644
index 0000000..29121aa
--- /dev/null
+++ b/Documentation/driver-api/soundwire/stream.rst
@@ -0,0 +1,372 @@
+=========================
+Audio Stream in SoundWire
+=========================
+
+An audio stream is a logical or virtual connection created between
+
+ (1) System memory buffer(s) and Codec(s)
+
+ (2) DSP memory buffer(s) and Codec(s)
+
+ (3) FIFO(s) and Codec(s)
+
+ (4) Codec(s) and Codec(s)
+
+which is typically driven by a DMA(s) channel through the data link. An
+audio stream contains one or more channels of data. All channels within
+stream must have same sample rate and same sample size.
+
+Assume a stream with two channels (Left & Right) is opened using SoundWire
+interface. Below are some ways a stream can be represented in SoundWire.
+
+Stream Sample in memory (System memory, DSP memory or FIFOs) ::
+
+ -------------------------
+ | L | R | L | R | L | R |
+ -------------------------
+
+Example 1: Stereo Stream with L and R channels is rendered from Master to
+Slave. Both Master and Slave is using single port. ::
+
+ +---------------+ Clock Signal +---------------+
+ | Master +----------------------------------+ Slave |
+ | Interface | | Interface |
+ | | | 1 |
+ | | Data Signal | |
+ | L + R +----------------------------------+ L + R |
+ | (Data) | Data Direction | (Data) |
+ +---------------+ +-----------------------> +---------------+
+
+
+Example 2: Stereo Stream with L and R channels is captured from Slave to
+Master. Both Master and Slave is using single port. ::
+
+
+ +---------------+ Clock Signal +---------------+
+ | Master +----------------------------------+ Slave |
+ | Interface | | Interface |
+ | | | 1 |
+ | | Data Signal | |
+ | L + R +----------------------------------+ L + R |
+ | (Data) | Data Direction | (Data) |
+ +---------------+ <-----------------------+ +---------------+
+
+
+Example 3: Stereo Stream with L and R channels is rendered by Master. Each
+of the L and R channel is received by two different Slaves. Master and both
+Slaves are using single port. ::
+
+ +---------------+ Clock Signal +---------------+
+ | Master +---------+------------------------+ Slave |
+ | Interface | | | Interface |
+ | | | | 1 |
+ | | | Data Signal | |
+ | L + R +---+------------------------------+ L |
+ | (Data) | | | Data Direction | (Data) |
+ +---------------+ | | +-------------> +---------------+
+ | |
+ | |
+ | | +---------------+
+ | +----------------------> | Slave |
+ | | Interface |
+ | | 2 |
+ | | |
+ +----------------------------> | R |
+ | (Data) |
+ +---------------+
+
+
+Example 4: Stereo Stream with L and R channel is rendered by two different
+Ports of the Master and is received by only single Port of the Slave
+interface. ::
+
+ +--------------------+
+ | |
+ | +--------------+ +----------------+
+ | | || | |
+ | | Data Port || L Channel | |
+ | | 1 |------------+ | |
+ | | L Channel || | +-----+----+ |
+ | | (Data) || | L + R Channel || Data | |
+ | Master +----------+ | +---+---------> || Port | |
+ | Interface | | || 1 | |
+ | +--------------+ | || | |
+ | | || | +----------+ |
+ | | Data Port |------------+ | |
+ | | 2 || R Channel | Slave |
+ | | R Channel || | Interface |
+ | | (Data) || | 1 |
+ | +--------------+ Clock Signal | L + R |
+ | +---------------------------> | (Data) |
+ +--------------------+ | |
+ +----------------+
+
+SoundWire Stream Management flow
+================================
+
+Stream definitions
+------------------
+
+ (1) Current stream: This is classified as the stream on which operation has
+ to be performed like prepare, enable, disable, de-prepare etc.
+
+ (2) Active stream: This is classified as the stream which is already active
+ on Bus other than current stream. There can be multiple active streams
+ on the Bus.
+
+SoundWire Bus manages stream operations for each stream getting
+rendered/captured on the SoundWire Bus. This section explains Bus operations
+done for each of the stream allocated/released on Bus. Following are the
+stream states maintained by the Bus for each of the audio stream.
+
+
+SoundWire stream states
+-----------------------
+
+Below shows the SoundWire stream states and state transition diagram. ::
+
+ +-----------+ +------------+ +----------+ +----------+
+ | ALLOCATED +---->| CONFIGURED +---->| PREPARED +---->| ENABLED |
+ | STATE | | STATE | | STATE | | STATE |
+ +-----------+ +------------+ +----------+ +----+-----+
+ ^
+ |
+ |
+ v
+ +----------+ +------------+ +----+-----+
+ | RELEASED |<----------+ DEPREPARED |<-------+ DISABLED |
+ | STATE | | STATE | | STATE |
+ +----------+ +------------+ +----------+
+
+NOTE: State transition between prepare and deprepare is supported in Spec
+but not in the software (subsystem)
+
+NOTE2: Stream state transition checks need to be handled by caller
+framework, for example ALSA/ASoC. No checks for stream transition exist in
+SoundWire subsystem.
+
+Stream State Operations
+-----------------------
+
+Below section explains the operations done by the Bus on Master(s) and
+Slave(s) as part of stream state transitions.
+
+SDW_STREAM_ALLOCATED
+~~~~~~~~~~~~~~~~~~~~
+
+Allocation state for stream. This is the entry state
+of the stream. Operations performed before entering in this state:
+
+ (1) A stream runtime is allocated for the stream. This stream
+ runtime is used as a reference for all the operations performed
+ on the stream.
+
+ (2) The resources required for holding stream runtime information are
+ allocated and initialized. This holds all stream related information
+ such as stream type (PCM/PDM) and parameters, Master and Slave
+ interface associated with the stream, stream state etc.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_ALLOCATED``.
+
+Bus implements below API for allocate a stream which needs to be called once
+per stream. From ASoC DPCM framework, this stream state maybe linked to
+.startup() operation.
+
+ .. code-block:: c
+ int sdw_alloc_stream(char * stream_name);
+
+
+SDW_STREAM_CONFIGURED
+~~~~~~~~~~~~~~~~~~~~~
+
+Configuration state of stream. Operations performed before entering in
+this state:
+
+ (1) The resources allocated for stream information in SDW_STREAM_ALLOCATED
+ state are updated here. This includes stream parameters, Master(s)
+ and Slave(s) runtime information associated with current stream.
+
+ (2) All the Master(s) and Slave(s) associated with current stream provide
+ the port information to Bus which includes port numbers allocated by
+ Master(s) and Slave(s) for current stream and their channel mask.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_CONFIGURED``.
+
+Bus implements below APIs for CONFIG state which needs to be called by
+the respective Master(s) and Slave(s) associated with stream. These APIs can
+only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
+framework, this stream state is linked to .hw_params() operation.
+
+ .. code-block:: c
+ int sdw_stream_add_master(struct sdw_bus * bus,
+ struct sdw_stream_config * stream_config,
+ struct sdw_ports_config * ports_config,
+ struct sdw_stream_runtime * stream);
+
+ int sdw_stream_add_slave(struct sdw_slave * slave,
+ struct sdw_stream_config * stream_config,
+ struct sdw_ports_config * ports_config,
+ struct sdw_stream_runtime * stream);
+
+
+SDW_STREAM_PREPARED
+~~~~~~~~~~~~~~~~~~~
+
+Prepare state of stream. Operations performed before entering in this state:
+
+ (1) Bus parameters such as bandwidth, frame shape, clock frequency,
+ are computed based on current stream as well as already active
+ stream(s) on Bus. Re-computation is required to accommodate current
+ stream on the Bus.
+
+ (2) Transport and port parameters of all Master(s) and Slave(s) port(s) are
+ computed for the current as well as already active stream based on frame
+ shape and clock frequency computed in step 1.
+
+ (3) Computed Bus and transport parameters are programmed in Master(s) and
+ Slave(s) registers. The banked registers programming is done on the
+ alternate bank (bank currently unused). Port(s) are enabled for the
+ already active stream(s) on the alternate bank (bank currently unused).
+ This is done in order to not disrupt already active stream(s).
+
+ (4) Once all the values are programmed, Bus initiates switch to alternate
+ bank where all new values programmed gets into effect.
+
+ (5) Ports of Master(s) and Slave(s) for current stream are prepared by
+ programming PrepareCtrl register.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_PREPARED``.
+
+Bus implements below API for PREPARE state which needs to be called once per
+stream. From ASoC DPCM framework, this stream state is linked to
+.prepare() operation.
+
+ .. code-block:: c
+ int sdw_prepare_stream(struct sdw_stream_runtime * stream);
+
+
+SDW_STREAM_ENABLED
+~~~~~~~~~~~~~~~~~~
+
+Enable state of stream. The data port(s) are enabled upon entering this state.
+Operations performed before entering in this state:
+
+ (1) All the values computed in SDW_STREAM_PREPARED state are programmed
+ in alternate bank (bank currently unused). It includes programming of
+ already active stream(s) as well.
+
+ (2) All the Master(s) and Slave(s) port(s) for the current stream are
+ enabled on alternate bank (bank currently unused) by programming
+ ChannelEn register.
+
+ (3) Once all the values are programmed, Bus initiates switch to alternate
+ bank where all new values programmed gets into effect and port(s)
+ associated with current stream are enabled.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_ENABLED``.
+
+Bus implements below API for ENABLE state which needs to be called once per
+stream. From ASoC DPCM framework, this stream state is linked to
+.trigger() start operation.
+
+ .. code-block:: c
+ int sdw_enable_stream(struct sdw_stream_runtime * stream);
+
+SDW_STREAM_DISABLED
+~~~~~~~~~~~~~~~~~~~
+
+Disable state of stream. The data port(s) are disabled upon exiting this state.
+Operations performed before entering in this state:
+
+ (1) All the Master(s) and Slave(s) port(s) for the current stream are
+ disabled on alternate bank (bank currently unused) by programming
+ ChannelEn register.
+
+ (2) All the current configuration of Bus and active stream(s) are programmed
+ into alternate bank (bank currently unused).
+
+ (3) Once all the values are programmed, Bus initiates switch to alternate
+ bank where all new values programmed gets into effect and port(s) associated
+ with current stream are disabled.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_DISABLED``.
+
+Bus implements below API for DISABLED state which needs to be called once
+per stream. From ASoC DPCM framework, this stream state is linked to
+.trigger() stop operation.
+
+ .. code-block:: c
+ int sdw_disable_stream(struct sdw_stream_runtime * stream);
+
+
+SDW_STREAM_DEPREPARED
+~~~~~~~~~~~~~~~~~~~~~
+
+De-prepare state of stream. Operations performed before entering in this
+state:
+
+ (1) All the port(s) of Master(s) and Slave(s) for current stream are
+ de-prepared by programming PrepareCtrl register.
+
+ (2) The payload bandwidth of current stream is reduced from the total
+ bandwidth requirement of bus and new parameters calculated and
+ applied by performing bank switch etc.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_DEPREPARED``.
+
+Bus implements below API for DEPREPARED state which needs to be called once
+per stream. From ASoC DPCM framework, this stream state is linked to
+.trigger() stop operation.
+
+ .. code-block:: c
+ int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
+
+
+SDW_STREAM_RELEASED
+~~~~~~~~~~~~~~~~~~~
+
+Release state of stream. Operations performed before entering in this state:
+
+ (1) Release port resources for all Master(s) and Slave(s) port(s)
+ associated with current stream.
+
+ (2) Release Master(s) and Slave(s) runtime resources associated with
+ current stream.
+
+ (3) Release stream runtime resources associated with current stream.
+
+After all above operations are successful, stream state is set to
+``SDW_STREAM_RELEASED``.
+
+Bus implements below APIs for RELEASE state which needs to be called by
+all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
+framework, this stream state is linked to .hw_free() operation.
+
+ .. code-block:: c
+ int sdw_stream_remove_master(struct sdw_bus * bus,
+ struct sdw_stream_runtime * stream);
+ int sdw_stream_remove_slave(struct sdw_slave * slave,
+ struct sdw_stream_runtime * stream);
+
+
+The .shutdown() ASoC DPCM operation calls below Bus API to release
+stream assigned as part of ALLOCATED state.
+
+In .shutdown() the data structure maintaining stream state are freed up.
+
+ .. code-block:: c
+ void sdw_release_stream(struct sdw_stream_runtime * stream);
+
+Not Supported
+=============
+
+1. A single port with multiple channels supported cannot be used between two
+streams or across stream. For example a port with 4 channels cannot be used
+to handle 2 independent stereo streams even though it's possible in theory
+in SoundWire.
diff --git a/Documentation/driver-api/soundwire/summary.rst b/Documentation/driver-api/soundwire/summary.rst
new file mode 100644
index 0000000..8193125
--- /dev/null
+++ b/Documentation/driver-api/soundwire/summary.rst
@@ -0,0 +1,207 @@
+===========================
+SoundWire Subsystem Summary
+===========================
+
+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 multi-drop 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 an example of connectivity between a SoundWire Master and
+two Slave devices. ::
+
+ +---------------+ +---------------+
+ | | Clock Signal | |
+ | Master |-------+-------------------------------| Slave |
+ | Interface | | Data Signal | Interface 1 |
+ | |-------|-------+-----------------------| |
+ +---------------+ | | +---------------+
+ | |
+ | |
+ | |
+ +--+-------+--+
+ | |
+ | Slave |
+ | Interface 2 |
+ | |
+ +-------------+
+
+
+Terminology
+===========
+
+The MIPI SoundWire specification uses the term 'device' to refer to a Master
+or Slave interface, which of course can be confusing. In this summary and
+code we use the term interface only to refer to the hardware. We follow the
+Linux device model by mapping each Slave interface connected on the bus as a
+device managed by a specific driver. The Linux SoundWire subsystem provides
+a framework to implement a SoundWire Slave driver with an API allowing
+3rd-party vendors to enable implementation-defined functionality while
+common setup/configuration tasks are handled by the bus.
+
+Bus:
+Implements SoundWire Linux Bus which handles the SoundWire protocol.
+Programs all the MIPI-defined Slave registers. Represents a SoundWire
+Master. Multiple instances of Bus may be present in a system.
+
+Slave:
+Registers as SoundWire Slave device (Linux Device). Multiple Slave devices
+can register to a Bus instance.
+
+Slave driver:
+Driver controlling the Slave device. MIPI-specified registers are controlled
+directly by the Bus (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 supports programming interfaces for the SoundWire Master
+implementation 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 interfaces needs to be registered to the Bus.
+Bus implements API to read standard Master MIPI properties and also provides
+callback in Master ops for Master driver to implement its own functions that
+provides capabilities information. DT support is not implemented at this
+time but should be trivial to add since capabilities are enabled with the
+``device_property_`` API.
+
+The Master interface along with the Master interface capabilities are
+registered based on board file, DT or ACPI.
+
+Following is the Bus API to register the SoundWire Bus:
+
+.. code-block:: c
+
+ int sdw_add_bus_master(struct sdw_bus *bus)
+ {
+ if (!bus->dev)
+ return -ENODEV;
+
+ mutex_init(&bus->lock);
+ INIT_LIST_HEAD(&bus->slaves);
+
+ /* Check ACPI for Slave devices */
+ sdw_acpi_find_slaves(bus);
+
+ /* Check DT for Slave devices */
+ sdw_of_find_slaves(bus);
+
+ return 0;
+ }
+
+This will initialize sdw_bus object for Master device. "sdw_master_ops" and
+"sdw_master_port_ops" callback functions are provided to the Bus.
+
+"sdw_master_ops" is used by Bus to control the Bus in the hardware specific
+way. It includes Bus control functions such as sending the SoundWire
+read/write messages on Bus, setting up clock frequency & Stream
+Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the
+hardware details of the Master from the Bus.
+
+"sdw_master_port_ops" is used by Bus to setup the Port parameters of the
+Master interface Port. Master interface Port register map is not defined by
+MIPI specification, so Bus calls the "sdw_master_port_ops" callback
+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 a specific vendor and part
+identifier, Bus enumerates the Slave device based on these two ids.
+Slave device and driver match is done based on these two ids . Probe
+of the Slave driver is called by Bus on successful match between device and
+driver id. A parent/child relationship is enforced between Master and Slave
+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 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.
+
+.. code-block:: c
+
+ static const struct sdw_device_id slave_id[] = {
+ SDW_SLAVE_ENTRY(0x025d, 0x700, 0),
+ {},
+ };
+ MODULE_DEVICE_TABLE(sdw, slave_id);
+
+ static struct sdw_driver slave_sdw_driver = {
+ .driver = {
+ .name = "slave_xxx",
+ .pm = &slave_runtime_pm,
+ },
+ .probe = slave_sdw_probe,
+ .remove = slave_sdw_remove,
+ .ops = &slave_slave_ops,
+ .id_table = slave_id,
+ };
+
+
+For capabilities, Bus implements API to read standard Slave MIPI properties
+and also provides callback in Slave ops for Slave driver to implement own
+function that provides capabilities information. Bus needs to know a set of
+Slave capabilities to program Slave registers and to control the Bus
+reconfigurations.
+
+Future enhancements to be done
+==============================
+
+ (1) Bulk Register Access (BRA) transfers.
+
+
+ (2) Multiple data lane support.
+
+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
+available at:
+https://www.mipi.org/specifications/mipi-disco-soundwire
+
+(publicly accessible with registration or directly accessible to MIPI
+members)
+
+MIPI Alliance Manufacturer ID Page: mid.mipi.org