---------- Forwarded message --------- From: Hao Chen <chenhaosjtu...@google.com> Date: Mon, Jun 14, 2021 at 4:26 PM Subject: [PATCH v1] Add virtio audio policy device specification To: <chenhaosjtu...@google.com>
This patch includes a new device for coordinating audio among mutliple VMs. Signed-off-by: Hao Chen <chenhaosjtu...@google.com> --- conformance.tex | 18 +++++ content.tex | 1 + virtio-audio-policy.tex | 171 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 190 insertions(+) create mode 100644 virtio-audio-policy.tex diff --git a/conformance.tex b/conformance.tex index a164cbb..bca4cf3 100644 --- a/conformance.tex +++ b/conformance.tex @@ -31,6 +31,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance}, \ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance} or \ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}. +\ref{sec:Conformance / Driver Conformance / Audio Policy Driver Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -54,6 +55,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Device Conformance / Memory Device Conformance}, \ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance} or \ref{sec:Conformance / Device Conformance / SCMI Device Conformance}. +\ref{sec:Conformance / Device Conformance / Audio Policy Device Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -288,6 +290,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Device Types / SCMI Device / Device Operation / Setting Up eventq Buffers} \end{itemize} +\conformance{\subsection}{Audio Policy Driver Conformance}\label{sec:Conformance / Driver Conformance / Audio Policy Driver Conformance} + +An audio policy driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / Audio Policy / Device Operation} +\end{itemize} + \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} A device MUST conform to the following normative statements: @@ -527,6 +537,14 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Device Types / SCMI Device / Device Operation / Shared Memory Operation} \end{itemize} +\conformance{\subsection}{Audio Policy Device Conformance}\label{sec:Conformance / Device Conformance / Audio Policy Device Conformance} + +An audio policy device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / Audio Policy / Device Operation} +\end{itemize} + \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or non-transitional, see \ref{intro:Legacy diff --git a/content.tex b/content.tex index 9232d5c..54f9934 100644 --- a/content.tex +++ b/content.tex @@ -6568,6 +6568,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device \input{virtio-mem.tex} \input{virtio-i2c.tex} \input{virtio-scmi.tex} +\input{virtio-audio-policy.tex} \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} diff --git a/virtio-audio-policy.tex b/virtio-audio-policy.tex new file mode 100644 index 0000000..4acca40 --- /dev/null +++ b/virtio-audio-policy.tex @@ -0,0 +1,171 @@ +\section{Audio Policy}\label{sec:Device Types / Audio Policy} + +When there are multiple guest VMs playing sounds, they may want to cooperate +with each other. For example, a VM is playing something very critical and want +to mute everyone else; or it is OK for other to lower the volume ("duck") but +keep playing; or it is OK to playing concurrently with other sounds. They can +cooperate via audio policy device. The driver notifies the device when the +guest VM is playing, and the device will notify other VMs. The driver can also +suggest the device to mute or duck some audio devices based on the information +it received from the device. + +\subsection{Device ID}\label{sec:Device Types / Audio Policy / Device ID} + +39 + +\subsection{Virtqueues}\label{sec:Device Types / Audio Policy / Virtqueues} + +\begin{description} +\item[0] eventq +\item[1] requestq +\item[2] infoq +\end{description} + +\subsection{Feature Bits}\label{sec:Device Types / Audio Policy / Feature Bits} + +None currently defined. + +\subsection{Device Configuration Layout}\label{sec:Device Types / Audio Policy / Device Configuration Layout} + +None currently defined. + +\subsection{Device Initialization} + +The driver requests for the known audio device information. + +The driver send VIRTIO_AUDIO_POLICY_RESET to the device. + +Populate eventq with empty buffers for receiving. + +\subsection{Device Operation}\label{sec:Device Types / Audio Policy / Device Operation} + +All requests from the driver go to requestq, with the following format: + +\begin{lstlisting} +enum { + VIRTIO_AUDIO_POLICY_AUDIO_DEVICE_INFO = 1, + VIRTIO_AUDIO_POLICY_AUDIO_FOCUS_EVENT, + VIRTIO_AUDIO_POLICY_VOLUME_CONTROL, + VIRTIO_AUDIO_POLICY_FOCUS_INFO, + VIRTIO_AUDIO_POLICY_RESET, +}; + +struct virtio_audio_policy_hdr { + le32 code; +}; + +/* Same structure for request and response */ +struct virtio_audio_policy_message { + struct virtio_audio_policy_hdr hdr; + u8 payload[]; +}; +\end{lstlisting} + +\subsubsection{Get Audio Device Information}\label{sec:Device Types / Audio Policy / Device Operation / Get Audio Device Information} + +To get the supported audio device information, the driver sends +\field{VIRTIO_AUDIO_POLICY_AUDIO_DEVICE_INFO} without payload to the driver. +The device sends the virtio_audio_policy_message back to the eventq with the +same header, followed by device information structures: + +\begin{lstlisting} +struct virtio_audio_policy_audio_device_info { + char name[128]; + le32 zone_id; +}; +\end{lstlisting} + +\subsubsection{Audio Focus Updates}\label{sec:Device Types / Audio Policy / Device Operation / Audio Focus Updates} + +When the guest VM is playing sounds, it can inform host and other VMs to +grab their audio focus by sending requests with header +\field{VIRTIO_AUDIO_POLICY_AUDIO_FOCUS_EVENT}: + +\begin{lstlisting} +/** The bitwise combination of the virtio_audio_policy_focus_mode flags + * will be stored in \field{mode} in virtio_audio_policy_focus_info + */ +enum virtio_audio_policy_focus_mode { + /* start playing */ + VIRTIO_AUDIO_POLICY_M_START = 0x1, + + /* end playing */ + VIRTIO_AUDIO_POLICY_M_END = 0x2, + + /* transiently grab the focus */ + VIRTIO_AUDIO_POLICY_M_TRANSIENT = 0x4, + + /* need to play exclusively */ + VIRTIO_AUDIO_POLICY_M_EXCLUSIVE = 0x8, + + /* allow other sounds to duck */ + VIRTIO_AUDIO_POLICY_M_ALLOW_DUCK = 0x10, +} + +struct virtio_audio_policy_focus_info { + le32 zone_id; + le32 audio_usage; + le32 mode; +} + +struct virtio_audio_policy_focus_message { + struct virtio_audio_policy_hdr hdr; + struct virtio_audio_policy_focus_info[]; +}; +\end{lstlisting} + +while \field{zone_id} specifies where the sound is played; \field{audio_usage} +specifies the type of the sound (e.g., music or some high-prioritized emergency +sounds); \field{mode} is the bit-wise combination of +virtio_audio_policy_focus_mode. Note that the device will decide +where the message will be forwarded to. The receiving driver will see it +in the eventq. + +The device may query the drivers for the current focus status of the VM. The +query will appear on eventq with header VIRTIO_AUDIO_POLICY_FOCUS_INFO. The +driver should reply in infoq with virtio_audio_policy_focus_message. + +\subsubsection{Audio Volume Controls}\label{sec:Device Types / Audio Policy / Device Operation / Audio Volume Controls} + +When the driver decides to mute or duck some of its audio devices, it sends a +list of audio device names to the device, in the following format: + +\begin{lstlisting} +enum virtio_audio_policy_volume_control { + VIRTIO_AUDIO_POLICY_OP_MUTE = 1, + VIRTIO_AUDIO_POLICY_OP_DUCK, + VIRTIO_AUDIO_POLICY_OP_UNMUTE, + VIRTIO_AUDIO_POLICY_OP_UNDUCK, +} + +struct virtio_audio_policy_volume_control_request { + struct virtio_audio_policy_hdr hdr; + le32 op; + char audio_device_names[][128]; +} +\end{lstlisting} + +\subsubsection{Reset}\label{sec:Device Types / Audio Policy / Device Operation / Reset} + +When VIRTIO_AUDIO_POLICY_RESET is sent by the driver, the device must release +all the focus the driver gained by sending VIRTIO_AUDIO_POLICY_M_END messages +to other VMs. The device must also unmute and unduck all the devices muted +and/or ducked by this driver, unless they are also muted or ducked by others. +When VIRTIO_AUDIO_POLICY_RESET is sent by the device, the driver must end all +focuses started by the device. + +\drivernormative{\subsubsection}{Device Operation}{Device Types / Audio Policy / Device Operation} + +The driver MUST NOT send undefined headers. + +The driver MUST NOT put device-readable descriptors into the eventq. + +\devicenormative{\subsubsection}{Device Operation}{Device Types / Audio Policy / Device Operation} + +The device MUST send the driver the information of all audio devices it can mute or duck +when VIRTIO_AUDIO_POLICY_AUDIO_DEVICE_INFO is received. The device MUST ignore +the device names requested by the driver if they are not on the list sent to +the driver. + +The device MUST send VIRTIO_AUDIO_POLICY_RESET to the drivers when the device +recovered from failure. -- 2.32.0.272.g935e593368-goog --------------------------------------------------------------------- To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org