SoundWire Subsystem Summary

SoundWire interface 개요

SoundWire는 MIPI Alliance가 2015년에 ratify한 interface입니다. 주로 audio function과 관련된 data를 운반하며 mobile 또는 mobile-inspired system에 audio device를 통합하도록 최적화됐습니다.

SoundWire는 data line과 clock line으로 구성된 2-pin multi-drop interface이며 저비용, 고효율, 고성능 system 개발을 돕습니다.

주요 기능은 payload data channel, control information, setup command를 하나의 2-pin interface로 전송하는 것, DDR(Dual Data Rate) transmission으로 clock frequency와 power consumption을 낮추는 것, clock scaling과 optional multiple data lane으로 요구 data rate에 맞추는 것, interrupt-style alert를 포함한 device status monitoring입니다.

Protocol은 최대 11개의 Slave interface를 지원하며 모두 공통 data·clock Bus를 공유합니다. 각 Slave는 최대 14개 Data Port를 지원할 수 있습니다. 그중 13개는 audio transport 전용이고 Data Port0은 bulk control information 전용입니다.

Audio Data Port 1..14는 transmit 또는 receive mode에서 각각 최대 8 channel을 지원합니다. 방향은 보통 고정되지만 specification은 configurable direction도 허용합니다. 약 19.2..24.576 Mbit/s의 bandwidth 제한 때문에 11*13*8 channel을 동시에 전송할 수는 없습니다.

===========================
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.

Master와 두 Slave의 connectivity

예시 topology는 하나의 SoundWire Master interface와 두 Slave interface를 같은 multi-drop Bus에 연결합니다.

Master에서 나온 Clock Signal과 Data Signal은 Slave Interface 1로 이어지고 중간 branch를 통해 Slave Interface 2에도 공유됩니다.

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 |
                             |             |
                             +-------------+

Bus, Slave와 Slave driver

MIPI SoundWire specification은 Master 또는 Slave interface를 가리킬 때 `device`라는 용어를 사용하므로 혼동될 수 있습니다. 이 summary와 code에서는 hardware만 `interface`라고 부릅니다.

Linux device model에 따라 Bus에 연결된 각 Slave interface를 특정 driver가 관리하는 device로 mapping합니다. Linux SoundWire subsystem은 third-party vendor가 implementation-defined 기능을 구현할 수 있는 Slave driver API를 제공하고, 공통 setup과 configuration은 Bus가 처리합니다.

Bus는 SoundWire protocol을 처리하는 Linux Bus를 구현하고 MIPI가 정의한 모든 Slave register를 program하며 SoundWire Master를 나타냅니다. 한 system에 여러 Bus instance가 존재할 수 있습니다.

Slave는 SoundWire Slave device, 즉 Linux Device로 register하며 하나의 Bus instance에 여러 Slave device를 등록할 수 있습니다.

Slave driver는 Slave device를 제어합니다. MIPI-specified register는 Bus가 직접 제어하고 Master driver/interface를 통해 전송합니다. Implementation-defined Slave register는 Slave driver가 제어합니다. 실제 구현에서는 Slave driver가 regmap을 사용하고 direct register access를 요청하지 않을 것으로 예상합니다.

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.

Master interface 등록과 capability

SoundWire Bus는 Master implementation과 Slave device를 위한 programming interface를 지원합니다. SoC designer와 third-party vendor가 널리 쓰는 `sdw` prefix를 모든 code에 사용합니다.

각 SoundWire Master interface는 Bus에 register해야 합니다. Bus는 standard Master MIPI property를 읽는 API와 Master driver가 자체 capability information function을 구현하는 Master ops callback을 제공합니다.

현재 DT support는 구현되지 않았지만 capability가 `device_property_` API로 enable되므로 추가하기 어렵지 않습니다.

Master interface와 capability는 board file, DT 또는 ACPI를 기반으로 register합니다.

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:

sdw_bus_master_add와 Master ops

`sdw_bus_master_add()`는 Master device의 `sdw_bus` object를 initialize합니다. 내부에서 `sdw_master_device_add()`를 호출하고 `bus->lock` mutex와 `bus->slaves` list를 초기화한 다음 ACPI와 DT에서 Slave device를 찾습니다.

Bus에는 `sdw_master_ops`와 `sdw_master_port_ops` callback function이 제공됩니다.

`sdw_master_ops`는 hardware-specific 방식으로 Bus를 제어합니다. SoundWire read/write message 전송, clock frequency 설정, Stream Synchronization Point(SSP) 설정 같은 Bus control function을 포함하며 Master의 hardware detail을 Bus에서 abstract합니다.

`sdw_master_port_ops`는 Master interface port의 parameter를 설정합니다. Master port register map은 MIPI specification에 정의되지 않으므로 Bus가 callback을 호출해 Port Prepare, Port Transport parameter 설정, Port enable·disable을 수행하고 Master driver가 hardware-specific configuration을 적용합니다.

.. code-block:: c

        int sdw_bus_master_add(struct sdw_bus *bus,
                                struct device *parent,
                                struct fwnode_handle)
        {
                sdw_master_device_add(bus, parent, fwnode);

                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.

48-bit dev_id와 Slave matching

MIPI specification은 각 Slave interface가 6개의 read-only `dev_id` register에 저장된 unique 48-bit identifier를 노출하도록 요구합니다.

`dev_id`에는 vendor와 part information, 동일 component를 서로 구별하는 field가 들어갑니다. 추가 class field는 현재 사용하지 않습니다.

Slave driver는 특정 vendor와 part identifier에 맞춰 작성하며 Bus는 이 두 ID로 Slave device를 enumerate합니다. Device와 driver도 두 ID로 match하고 성공하면 Bus가 Slave driver의 probe를 호출합니다.

Master와 Slave device 사이에는 parent/child relationship을 강제해 logical representation을 physical connectivity와 일치시킵니다.

Master/Slave dependency는 platform data, board file, ACPI 또는 DT에 저장합니다. MIPI Software specification은 여러 Master interface를 가진 controller를 위해 `link_id` parameter를 추가로 정의합니다.

`dev_id` register는 link scope에서만 unique하고 `link_id`는 controller scope에서 unique합니다. 둘 다 system level에서 반드시 unique하지는 않지만 parent/child information을 사용해 ambiguity를 피합니다.

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.

Slave driver table과 capability

Slave driver는 `struct sdw_device_id` table에 `SDW_SLAVE_ENTRY(vendor, part, class)`를 등록하고 `MODULE_DEVICE_TABLE(sdw, slave_id)`로 module device table을 제공합니다.

`struct sdw_driver`에는 driver name과 runtime PM, `probe`, `remove`, Slave ops, `id_table`을 설정합니다. 원문 예시는 vendor `0x025d`, part `0x700`, class `0`을 사용합니다.

Capability 처리를 위해 Bus는 standard Slave MIPI property를 읽는 API를 구현하고, Slave driver가 자체 capability information function을 제공할 수 있도록 Slave ops callback을 노출합니다.

Bus는 Slave register를 program하고 Bus reconfiguration을 제어하기 위해 일정한 Slave capability 집합을 알아야 합니다.

.. 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.

SoundWire specification link

SoundWire MIPI specification 1.1은 MIPI member document page에서 제공합니다.

SoundWire MIPI DisCo, 즉 Discovery and Configuration specification은 MIPI specification page에서 제공하며 등록한 public user 또는 MIPI member가 접근할 수 있습니다.

MIPI Alliance Manufacturer ID는 `mid.mipi.org`에서 확인합니다.

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