docs/5_Component_Documentation/9_ic-sound-manager.md

   1 # Instrument Cluster Sound Management
   2
   3 ## Introduction
   4
   5 This document describes the design of the software setup which enables the integration
   6 of AGL’s sound system with applications running in the Instrument Cluster domain.
   7 This software setup is specific to the case where a single system is used to implement
   8 both the Instrument Cluster and some other domain of the vehicle, typically the
   9 In-Vehicle-Infotainment domain, using container technology to separate them.
  10
  11 Applications running in the Instrument Cluster need a way to safely play important
  12 sounds to alert the driver of conditions that need the driver’s attention. At the same
  13 time, in a containerized environment that serves multiple vehicle domains, applications
  14 running in other containers may be using the sound hardware to play less important sounds,
  15 such as music, which conflicts with the IC’s need to play sound on the same hardware.
  16
  17 The solution developed here, for safety reasons, relies on the operating system and the
  18 hardware itself to allow the IC applications to stream sounds to the speakers using a
  19 dedicated device handle, while applications from other domains are all routed through a
  20 sound server that runs on the host container and operates on a different sound device handle.
  21
  22 However, to achieve good inter-operation, there is need for additional software mechanisms
  23 that will work in combination with this hardware-based solution. First of all, it is necessary
  24 to have a mechanism that allows IC applications to pause all sounds that are being routed via
  25 the sound server while there is an important IC sound playing and resume them afterwards.
  26 This is so that other domain applications can be informed of this temporary pause and offer
  27 the appropriate user experience. Secondly, it is desirable to have separation of duties
  28 between the host and the other domain’s (non-IC) container. It should be the responsibility
  29 of the other domain’s container to implement the sound system policy, so that the host does
  30 not need to be aware of the exact applications that are running on this container.
  31
  32 ## Requirements
  33
  34 - Single system shared between IC and at least one secondary domain (IVI, other ...)
  35
  36 - The domains are separated using containers
  37
  38 - All the containers, including the host, are running a variant of AGL
  39
  40 - The host OS and the secondary domain container use PipeWire and WirePlumber
  41   to implement the sound system
  42
  43 - The sound hardware offers, on the Linux kernel driver side, a separate ALSA
  44   device for sounds that belong to the IC and a separate ALSA device for other sounds
  45
  46 ## Architectural design
  47
  48 ![Architecture overview](images/ic-sound-manager/architecture.png)
  49
  50 The core of the sound system consists of the PipeWire daemon, which is responsible for routing
  51 audio between the kernel and applications running in the “Other Container”.
  52
  53 The PipeWire session is orchestrated by a secondary daemon, WirePlumber. WirePlumber is
  54 designed in such a way so that it can have multiple instances, for task separation.
  55 One instance shall be running in the host container and it shall be responsible for
  56 managing the devices that PipeWire handles as well as the security isolation between
  57 different applications and different containers. At least one more instance shall be
  58 running in the “Other Container” and be responsible for implementing policy mechanisms
  59 related to the applications that are running in that container.
  60
  61 Further WirePlumber instances are possible to run as well. For instance, it may be desirable
  62 to have another “policy” instance in a third container that implements another vehicle system
  63 and shares the main PipeWire daemon from the host. Additionally, the “Other Container” may
  64 be running a separate WirePlumber instance to manage bluetooth audio devices, which shall be
  65 the responsibility of that container instead of the host.
  66
  67 To implement communication between the IC and the host, a third daemon is used: pipewire-ic-ipc.
  68 This daemon listens on a UNIX domain socket for messages from the IC applications and offers
  69 them the ability to pause or resume sounds that are being routed via PipeWire.
  70
  71 Finally, IC applications are given a library (icipc library) that allows them to send messages
  72 to pipewire-ic-ipc on the host. This library is minimal and has no external dependencies,
  73 for safety reasons.
  74
  75 For sound playback, IC applications are expected to use the ALSA API directly and communicate
  76 with the dedicated ALSA device that is meant for IC sounds. Arbitration of this device between
  77 different IC applications is out of scope for this document and it is assumed to be a solved
  78 problem.
  79
  80 ### PipeWire-IC-IPC
  81
  82 This component acts as the server-side component for the UNIX socket that is used for
  83 communication between the IC applications and the host. It is implemented as a pipewire module,
  84 therefore it needs the `/usr/bin/pipewire` process in order to be launched. Launching happens
  85 with a special configuration file (`pipewire-ic-ipc.conf`) which instructs this PipeWire process
  86 to be launched as a client (`core.daemon = false`) and to load only `module-ic-ipc` together
  87 with `module-protocol-native`. The latter enables communication with the daemon instance of
  88 PipeWire (`core.daemon = true`), which implements the sound server.
  89
  90 ![PipeWire-IC-IPC Processes](images/ic-sound-manager/pipewire-ic-ipc-processes.png)
  91
  92 ### icipc library
  93
  94 The IC Application is given a library (‘libicipc’) that implements the client side of
  95 pipewire-ic-ipc. This library allows sending two commands:
  96
  97 - SUSPEND
  98   - Asks WirePlumber (via PipeWire) to cork applications and mute the ALSA device used by PipeWire
  99 - RESUME
 100   - Reverts the effects of SUSPEND
 101
 102 IC Applications are expected to send the SUSPEND command before starting playback of a sound
 103 to their dedicated ALSA device. The RESUME command should be sent after playback of this IC
 104 sound has finished.
 105
 106 It should be noted that the RESUME command is also issued automatically when the IC application
 107 disconnects from the pipewire-ic-ipc UNIX socket.
 108
 109 If multiple IC application issue SUSPEND to the pipewire-ic-ipc server, then only the first
 110 SUSPEND generates actions for WirePlumber. The rest are counted and the pipewire-ic-ipc
 111 server expects an equal number of RESUME commands before generating resume actions for
 112 WirePlumber.
 113
 114 The implementation of the SUSPEND/RESUME mechanism uses PipeWire’s metadata to signal
 115 WirePlumber. PipeWire-IC-IPC will look for the “default” metadata object in PipeWire’s list
 116 of objects and will write the “suspend.playback” key with a value of “true” on id 0.
 117 The metadata change is then notified to all clients. WirePlumber, being a client, gets
 118 notified of this change and takes actions. All actions are defined in Lua scripts.
 119
 120 ![PipeWire-IC-IPC Calls](images/ic-sound-manager/pipewire-ic-ipc-calls.png)