diff options
Diffstat (limited to 'docs/5_Component_Documentation/7_ic-sound-manager.md')
| -rw-r--r-- | docs/5_Component_Documentation/7_ic-sound-manager.md | 120 |
1 files changed, 0 insertions, 120 deletions
diff --git a/docs/5_Component_Documentation/7_ic-sound-manager.md b/docs/5_Component_Documentation/7_ic-sound-manager.md deleted file mode 100644 index 75e163e..0000000 --- a/docs/5_Component_Documentation/7_ic-sound-manager.md +++ /dev/null @@ -1,120 +0,0 @@ -# Instrument Cluster Sound Management - -## Introduction - -This document describes the design of the software setup which enables the integration -of AGL’s sound system with applications running in the Instrument Cluster domain. -This software setup is specific to the case where a single system is used to implement -both the Instrument Cluster and some other domain of the vehicle, typically the -In-Vehicle-Infotainment domain, using container technology to separate them. - -Applications running in the Instrument Cluster need a way to safely play important -sounds to alert the driver of conditions that need the driver’s attention. At the same -time, in a containerized environment that serves multiple vehicle domains, applications -running in other containers may be using the sound hardware to play less important sounds, -such as music, which conflicts with the IC’s need to play sound on the same hardware. - -The solution developed here, for safety reasons, relies on the operating system and the -hardware itself to allow the IC applications to stream sounds to the speakers using a -dedicated device handle, while applications from other domains are all routed through a -sound server that runs on the host container and operates on a different sound device handle. - -However, to achieve good inter-operation, there is need for additional software mechanisms -that will work in combination with this hardware-based solution. First of all, it is necessary -to have a mechanism that allows IC applications to pause all sounds that are being routed via -the sound server while there is an important IC sound playing and resume them afterwards. -This is so that other domain applications can be informed of this temporary pause and offer -the appropriate user experience. Secondly, it is desirable to have separation of duties -between the host and the other domain’s (non-IC) container. It should be the responsibility -of the other domain’s container to implement the sound system policy, so that the host does -not need to be aware of the exact applications that are running on this container. - -## Requirements - -- Single system shared between IC and at least one secondary domain (IVI, other ...) - -- The domains are separated using containers - -- All the containers, including the host, are running a variant of AGL - -- The host OS and the secondary domain container use PipeWire and WirePlumber - to implement the sound system - -- The sound hardware offers, on the Linux kernel driver side, a separate ALSA - device for sounds that belong to the IC and a separate ALSA device for other sounds - -## Architectural design - - - -The core of the sound system consists of the PipeWire daemon, which is responsible for routing -audio between the kernel and applications running in the “Other Container”. - -The PipeWire session is orchestrated by a secondary daemon, WirePlumber. WirePlumber is -designed in such a way so that it can have multiple instances, for task separation. -One instance shall be running in the host container and it shall be responsible for -managing the devices that PipeWire handles as well as the security isolation between -different applications and different containers. At least one more instance shall be -running in the “Other Container” and be responsible for implementing policy mechanisms -related to the applications that are running in that container. - -Further WirePlumber instances are possible to run as well. For instance, it may be desirable -to have another “policy” instance in a third container that implements another vehicle system -and shares the main PipeWire daemon from the host. Additionally, the “Other Container” may -be running a separate WirePlumber instance to manage bluetooth audio devices, which shall be -the responsibility of that container instead of the host. - -To implement communication between the IC and the host, a third daemon is used: pipewire-ic-ipc. -This daemon listens on a UNIX domain socket for messages from the IC applications and offers -them the ability to pause or resume sounds that are being routed via PipeWire. - -Finally, IC applications are given a library (icipc library) that allows them to send messages -to pipewire-ic-ipc on the host. This library is minimal and has no external dependencies, -for safety reasons. - -For sound playback, IC applications are expected to use the ALSA API directly and communicate -with the dedicated ALSA device that is meant for IC sounds. Arbitration of this device between -different IC applications is out of scope for this document and it is assumed to be a solved -problem. - -### PipeWire-IC-IPC - -This component acts as the server-side component for the UNIX socket that is used for -communication between the IC applications and the host. It is implemented as a pipewire module, -therefore it needs the `/usr/bin/pipewire` process in order to be launched. Launching happens -with a special configuration file (`pipewire-ic-ipc.conf`) which instructs this PipeWire process -to be launched as a client (`core.daemon = false`) and to load only `module-ic-ipc` together -with `module-protocol-native`. The latter enables communication with the daemon instance of -PipeWire (`core.daemon = true`), which implements the sound server. - - - -### icipc library - -The IC Application is given a library (‘libicipc’) that implements the client side of -pipewire-ic-ipc. This library allows sending two commands: - -- SUSPEND - - Asks WirePlumber (via PipeWire) to cork applications and mute the ALSA device used by PipeWire -- RESUME - - Reverts the effects of SUSPEND - -IC Applications are expected to send the SUSPEND command before starting playback of a sound -to their dedicated ALSA device. The RESUME command should be sent after playback of this IC -sound has finished. - -It should be noted that the RESUME command is also issued automatically when the IC application -disconnects from the pipewire-ic-ipc UNIX socket. - -If multiple IC application issue SUSPEND to the pipewire-ic-ipc server, then only the first -SUSPEND generates actions for WirePlumber. The rest are counted and the pipewire-ic-ipc -server expects an equal number of RESUME commands before generating resume actions for -WirePlumber. - -The implementation of the SUSPEND/RESUME mechanism uses PipeWire’s metadata to signal -WirePlumber. PipeWire-IC-IPC will look for the “default” metadata object in PipeWire’s list -of objects and will write the “suspend.playback” key with a value of “true” on id 0. -The metadata change is then notified to all clients. WirePlumber, being a client, gets -notified of this change and takes actions. All actions are defined in Lua scripts. - - |