Documentation/drivers/soundwire.md

# SoundWire Implementation in coreboot

## Introduction

SoundWire is an audio interface specification from the MIPI Alliance.

- Low complexity
- Low power
- Low latency
- Two pins (clock and data)
- Multi-drop capable
- Multiple audio streams
- Embedded control/command channel

The main *SoundWire Specification* is at version 1.2 and can be downloaded from
<https://mipi.org> but it is unfortunately only available to MIPI Alliance members.

There is a separate *SoundWire Discovery and Configuration (DisCo) Specification* which
is at version 1.0 and is available for non-members after providing name and email at
<https://resources.mipi.org/disco_soundwire>.

The coreboot implementation is based on the SoundWire DisCo Specification which defines
object hierarchy and properties for providing topology and configuration information to
OS kernel drivers via ACPI or DeviceTree.

SoundWire itself is architecture independent and the coreboot basic definition is also not
specific to any to any SoC.  The examples in this document use ACPI to generate properties,
but the same structures and properties would be needed in a DeviceTree implementation.

## Bus

The SoundWire bus commonly consists of two pins:

* Clock: A common clock signal distributed from the master to all of the slaves.
* Data: A shared data signal that can be driven by any of the devices, and has a defined
value when no device is driving it.

While most designs have one data lane it is possible for a multi-lane device to have up
to 8 data lanes and thus would have more than two pins.

A SoundWire bus consists of one master device, up to 11 slave devices, and an optional
monitor interface for debug.

SoundWire is an enumerable bus, but not a discoverable one.  That means it is required
for firmware to provide details about the connected devices to the OS.

### Controller

A SoundWire controller contains one or more master devices.  The handling of multiple
masters is left up to the implementation, they may share a clock or be operated
independently or entirely in tandem.  The master devices connected to a controller are
also referred to as links.

In coreboot the controller device is provided by the SoC or an add-in PCI card.

### Master

A SoundWire master (or link) device is responsible for clock and data handling, bus
management, and bit slot allocation.

In coreboot the definition of the master device is left up to the controller and the
mainboard should only need to know the controller's SoundWire topology (number of masters)
to configure `devicetree.cb`.

It may however be expected to provide some additional SoC-specific configuration data to
the controller, such as an input clock rate or a list of available masters that cannot
be determined at run time.

### Slave

SoundWire slave devices are connected to a master and respond to the two-wire control
information on the SoundWire bus.  There can be up to 11 slave devices on a bus and they
are capable of interrupting and waking the host.

Slave devices may also have master links which can be connected to other slave devices.
It is also possible for a multi-lane slave device to have multiple data lanes connected
to different combinations of master and slave devices.

In coreboot the slave device is defined by a codec driver which should be found in the
source tree at `src/drivers/soundwire`.

The mainboard provides:

* Master link that this slave device is connected to.
* Unique ID that this codec responds to on the SoundWire bus.
* Multi-lane mapping. (optional)

The codec driver provides:

* Slave device properties.
* Audio Mode properties including bus frequencies and sampling rates.
* Data Port 1-14 properties such as word lengths, interrupt support, channels.
* Data Port 0 and Bulk Register Access properties. (optional)

### Monitor

A SoundWire monitor device is defined that allows for test equipment to snoop the bus and
take over and issue commands.  The monitor interface is not defined for coreboot.

### Example SoundWire Bus

```
+---------------+                                       +---------------+
|               |                       Clock Signal    |               |
|    Master     |-------+-------------------------------|    Slave      |
|   Interface   |       |               Data Signal     |  Interface 1  |
|               |-------|-------+-----------------------|               |
+---------------+       |       |                       +---------------+
                        |       |
                        |       |
                        |       |
                     +--+-------+--+
                     |             |
                     |   Slave     |
                     | Interface 2 |
                     |             |
                     +-------------+
```

## coreboot

The coreboot implementation of SoundWire integrates with the device model and takes
advantage of the hierarchical nature of `devicetree.cb` to populate the topology.

The architecture-independent SoundWire tables are defined at

    src/include/device/soundwire.h

Support for new devices comes in three forms:

1. New controller and master drivers.  The first implementation in coreboot is for an Intel
SoC but the SoundWire specification is in wide use on various ARM SoCs.

    Controller drivers can be implemented in `src/soc` or `src/drivers` and should
    strive to re-use code as much as possible between different SoC generations from the
    same vendor.

2. New codec drivers.  These should be implemented for each codec that is added which
supports SoundWire.  The properties vary between codecs and careful study of the data sheet
is necessary to ensure proper operation.

    Codec drivers should be implemented in `src/drivers/soundwire` as separate chip drivers.
    As every codec is different there may not be opportunities of code re-use except between
    similar codecs from the same vendor.

3. New mainboards with SoundWire support.  The mainboard will combine controllers and codecs
to form a topology that is described in `devicetree.cb`.  Some devices may need to provide
board-specific configuration information, and multi-lane devices will need to provide the
master/slave lane map.

## ACPI Implementation

The implementation for x86 devices relies on ACPI for providing device properties to the OS
kernel drivers.

The ACPI implementation can be found at

    src/acpi/soundwire.c

And used by including

    #include <acpi/acpi_soundwire.h>

### Controller

The controller driver should populate a `struct soundwire_controller`:

```c
/**
 * struct soundwire_controller - SoundWire controller properties.
 * @master_count: Number of masters present on this device.
 * @master_list: One entry for each master device.
 */
struct soundwire_controller {
	unsigned int master_list_count;
	struct soundwire_link master_list[SOUNDWIRE_MAX_DEV];
};
```

Once the detail of the master links are specified in the `master_list` variable, the controller
properties for the ACPI object can be generated:

```c
struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
soundwire_gen_controller(dsd, &soc_controller, NULL);
acpi_dp_write(dsd);
```

If the controller needs to generate custom properties for links it can provide a callback
function to `soundwire_gen_controller()` instead of passing NULL:

```c
static void controller_link_prop_cb(struct acpi_dp *dsd, unsigned int id,
                                    struct soundwire_controller *controller)
{
	acpi_dp_add_integer(dsd, "custom-link-property", 1);
}
```

### Codec

The codec driver should populate a *struct soundwire_codec* with necessary properties:

```c
/**
 * struct soundwire_codec - Contains all configuration for a SoundWire codec slave device.
 * @slave: Properties for slave device.
 * @audio_mode: Properties for Audio Mode for Data Ports 1-14.
 * @dpn: Properties for Data Ports 1-14.
 * @multilane: Properties for slave multilane device. (optional)
 * @dp0_bra_mode: Properties for Bulk Register Access mode for Data Port 0. (optional)
 * @dp0: Properties for Data Port 0 for Bulk Register Access. (optional)
 */
struct soundwire_codec {
	struct soundwire_slave *slave;
	struct soundwire_audio_mode *audio_mode[SOUNDWIRE_MAX_DEV];
	struct soundwire_dpn_entry dpn[SOUNDWIRE_MAX_DPN - SOUNDWIRE_MIN_DPN];
	struct soundwire_multilane *multilane;
	struct soundwire_bra_mode *dp0_bra_mode[SOUNDWIRE_MAX_DEV];
	struct soundwire_dp0 *dp0;
};
```

Many of these properties are optional, and depending on the codec will not be supported.

#### Slave Device Properties

These properties provide information about the codec device and what features it supports:

* Wake capability
* Clock stop behavior
* Clock and channel state machine behavior
* Features like register pages, broadcast read, bank delay, and high performance PHY

#### Multi-lane Slave Device Properties

Most slave devices have a single data pin and a single lane, but it is possible for up to
7 other lanes to be supported on a device.  These lanes can be connected to other master
links or to other slave devices.

If a codec supports this feature it must indicate that by providing an entry for
`struct soundwire_multilane` in the chip configuration.

```c
/**
 * struct drivers_soundwire_example_config - Example codec configuration.
 * @multilane: Multi-lane slave configuration.
 */
struct drivers_soundwire_example_config {
	struct soundwire_multilane multilane;
};
```

The mainboard is required to provide the lane map in `devicetree.cb` for any codec that has
multiple lanes connected.  This includes the definition up to 7 entries that indicate which
lane number on the slave devices (array index starting at 1) maps to which other device:

```
chip drivers/soundwire/multilane_codec
	register "multilane.lane_mapping" = "{
		{
			# Slave Lane 1 maps to Master Lane 2
			.lane = 1,
			.direction = MASTER_LANE,
			.connection.master_lane = 2
		},
		{
			# Slave Lane 3 maps to Slave Link B
			.lane = 3,
			.direction = SLAVE_LINK,
			.connection.slave_link = 1
		}
	}"
	device generic 0.0 on end
end
```

#### Data Port 0 Properties

SoundWire Data Port 0 (DP0) is a special port used for control and status operation relating
to the whole device interface, and as a special data port for bulk read/write operations.

The properties for data port 0 are different from that of data ports 1-14 and are about the
control channel behavior and the overall bulk register mode.

Data port 0 is not required to be supported by the slave device.

#### Bulk Register Access Mode Properties

Bulk Register Access (BRA) is an optional mechanism for transporting higher bandwidth of
register operations than the typical command mechanism.  The BRA protocol is a particular
format of the data on the (optional) data port 0 connection between the master and slave.

The BRA protocol may have alignment or timing requirements that are directly related to the
bus frequencies.  As a result there may be several configurations listed, for symmetry with
the audio modes paired with data ports 1-14.

#### Data Port 1-14 Properties

Data ports 1-14 are typically dedicated to streaming audio payloads, and each data port can
have from 1 to 8 channels.  There are different levels of data ports, with some registers
being required and supported on all data ports and some optional registers only being used
on some data ports.

Data ports can have both a sink and a source component, and the codec may support one or
both of these on each port.

Similar to data port 0 the properties defined here describe the capabilities and supported
features of each data port, and they may be configured separately.  For example the Maxim
MAX98373 codec supports a 32bit source data port for speaker output, and a 16bit sink data
port for speaker sense data.

#### Audio Mode Properties

Each data port may be tied to one or more audio modes.  The audio mode describes the actual
audio capabilities of the codec, including supported frequencies and sample rates.  These
modes can be shared by multiple data ports and do not need to be duplicated.

For example:

```
static struct soundwire_audio_mode audio_mode = {
	.bus_frequency_max = 24 * MHz,
	.bus_frequency_min = 24 * KHz,
	.max_sampling_frequency = 192 * KHz,
	.min_sampling_frequency = 8 * KHz,
};
static struct soundwire_dpn codec_dp1 = {
    [...]
	.port_audio_mode_count = 1,
	.port_audio_mode_list = {0}
};
static struct soundwire_dpn codec_dp3 = {
    [...]
	.port_audio_mode_count = 1,
	.port_audio_mode_list = {0}
};
```

### Generating Codec Properties

Once the properties are known it can generate the ACPI code with:

```c
struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
soundwire_gen_codec(dsd, &soundwire_codec, NULL);
acpi_dp_write(dsd);
```

If the codec needs to generate custom properties for links it can provide a callback
function to `soundwire_gen_codec()` instead of passing NULL:

```c
static void codec_dp_prop_cb(struct acpi_dp *dsd, unsigned int id,
                             struct soundwire_codec *codec)
{
	acpi_dp_add_integer(dsd, "custom-dp-property", 1);
}
```

#### Codec Address

SoundWire slave devices use a SoundWire defined ACPI _ADR that requires a 64-bit integer
and uses the master link ID and slave device unique ID to form a unique address for the
device on this controller.

SoundWire addresses must be distinguishable from all other slave devices on the same master
link, so multiple instances of the same manufacturer and part on the same master link will
need different unique IDs.  The value is typically determined by strapping pins on the codec
chip and can be decoded for this table with the codec datasheet and board schematics.

```c
/**
 * struct soundwire_address - SoundWire ACPI Device Address Encoding.
 * @version: SoundWire specification version from &enum soundwire_version.
 * @link_id: Zero-based SoundWire Link Number.
 * @unique_id: Unique ID for multiple devices.
 * @manufacturer_id: Manufacturer ID from include/mipi/ids.h.
 * @part_id: Vendor defined part ID.
 * @class: MIPI class encoding in &enum mipi_class.
 */
struct soundwire_address {
	enum soundwire_version version;
	uint8_t link_id;
	uint8_t unique_id;
	uint16_t manufacturer_id;
	uint16_t part_id;
	enum mipi_class class;
};
```

This ACPI address can be generated by calling the provided acpigen function:

    acpigen_write_ADR_soundwire_device(const struct soundwire_address *sdw);

### Mainboard

The mainboard needs to select appropriate drivers in `Kconfig` and define the topology in
`devicetree.cb` with the controllers and codecs that exist on the board.

The topology uses the **generic** device to describe SoundWire:

```c
struct generic_path {
	unsigned int id;       /* SoundWire Master Link ID */
	unsigned int subid;    /* SoundWire Slave Unique ID */
};
```

This allows devices to be specified in `devicetree.cb` with the necessary information to
generate ACPI address and device properties.

```
chip drivers/intel/soundwire
	# SoundWire Controller 0
	device generic 0 on
		chip drivers/soundwire/codec1
			# SoundWire Link 0 ID 0
			device generic 0.0 on end
		end
		chip drivers/soundwire/codec2
			# SoundWire Link 1 ID 2
			device generic 1.2 on end
		end
	end
end
```

## Volteer Example

This is an example of an Intel Tiger Lake reference board using SoundWire Link 0 for the
headphone codec connection, and Link 1 for connecting two speaker amps for stereo speakers.

The mainboard can be found at

    src/mainboard/google/volteer

```
  +------------------+         +-------------------+
  |                  |         | Headphone Codec   |
  | Intel Tiger Lake |    +--->| Realtek ALC5682   |
  |    SoundWire     |    |    |       ID 1        |
  |    Controller    |    |    +-------------------+
  |                  |    |
  |           Link 0 +----+    +-------------------+
  |                  |         | Left Speaker Amp  |
  |           Link 1 +----+--->| Maxim MAX98373    |
  |                  |    |    |       ID 3        |
  |           Link 2 |    |    +-------------------+
  |                  |    |
  |           Link 3 |    |    +-------------------+
  |                  |    |    | Right Speaker Amp |
  +------------------+    +--->| Maxim MAX98373    |
                               |       ID 7        |
                               +-------------------+
```

This implementation requires a controller driver for the Intel Tigerlake SoC and a codec
driver for the Realtek and Maxim chips.  If those drivers did not already exist they would
need to be added and reviewed separately before adding the support to the mainboard.

The volteer example requires some `Kconfig` options to be selected:

```
config BOARD_GOOGLE_BASEBOARD_VOLTEER
	select DRIVERS_INTEL_SOUNDWIRE
	select DRIVERS_SOUNDWIRE_ALC5682
	select DRIVERS_SOUNDWIRE_MAX98373
```

And the following `devicetree.cb` entries to define this topology:

```
device pci 1f.3 on
	chip drivers/intel/soundwire
		# SoundWire Controller 0
		device generic 0 on
			chip drivers/soundwire/alc5682
				# SoundWire Link 0 ID 1
				register "desc" = ""Headphone Jack""
				device generic 0.1 on end
			end
			chip drivers/soundwire/max98373
				# SoundWire Link 0 ID 1
				register "desc" = ""Left Speaker Amp""
				device generic 1.3 on end
			end
			chip drivers/soundwire/max98373
				# SoundWire Link 1 ID 7
				register "desc" = ""Right Speaker Amp""
				device generic 1.7 on end
			end
		end
	end
end
```