docs/06_Component_Documentation/08_Instrument_Cluster_Sound_Management.md

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