diff options
| -rw-r--r-- | Documentation/drivers/index.md | 1 | ||||
| -rw-r--r-- | Documentation/drivers/soundwire.md | 496 |
2 files changed, 497 insertions, 0 deletions
diff --git a/Documentation/drivers/index.md b/Documentation/drivers/index.md index 807ed85ed6..e215c6ab11 100644 --- a/Documentation/drivers/index.md +++ b/Documentation/drivers/index.md @@ -6,3 +6,4 @@ they allow to easily reuse existing code accross platforms. * [IPMI KCS](ipmi_kcs.md) * [SMMSTORE](smmstore.md) +* [SoundWire](soundwire.md) diff --git a/Documentation/drivers/soundwire.md b/Documentation/drivers/soundwire.md new file mode 100644 index 0000000000..9c48b75b37 --- /dev/null +++ b/Documentation/drivers/soundwire.md @@ -0,0 +1,496 @@ +# 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/device/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 +``` |