[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [RFC] snd: Add virtio sound device specification
From: Anton Yakovlev <Anton.Yakovlev@opensynergy.com> The virtio sound device is an extendable virtual audio device. It provides playback and capture PCM streams to a guest. The device is implemented as a collection of a device-specific functions that provide dedicated audio-related functionality. At the moment it supports the following: 1. Base function (generic device management); 2. PCM function (a playback/capture PCM stream). Signed-off-by: Anton Yakovlev <Anton.Yakovlev@opensynergy.com> Signed-off-by: Mikhail Golubev <Mikhail.Golubev@opensynergy.com> --- content.tex | 1 + virtio-sound.tex | 432 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 433 insertions(+) create mode 100644 virtio-sound.tex diff --git a/content.tex b/content.tex index ee0d7c9..6a7f9a3 100644 --- a/content.tex +++ b/content.tex @@ -5677,6 +5677,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device \input{virtio-input.tex} \input{virtio-crypto.tex} \input{virtio-vsock.tex} +\input{virtio-sound.tex} \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} diff --git a/virtio-sound.tex b/virtio-sound.tex new file mode 100644 index 0000000..4039d64 --- /dev/null +++ b/virtio-sound.tex @@ -0,0 +1,432 @@ +\section{Sound Device}\label{sec:Device Types / Sound Device} + +The virtio sound card is an extendable virtual audio device. It provides its +functionality in a form of functions that can be configured and managed in an +independent way. + +\subsection{Device ID}\label{sec:Device Types / Sound Device / Device ID} + +25 + +\subsection{Virtqueues}\label{sec:Device Types / Sound Device / Virtqueues} + +Depending on provided functionality, a device can use one or more virtqueues +described in a configuration space. A virtqueue assigned to the base function +is mandatory and referred as a control queue. + +\subsection{Feature bits}\label{sec:Device Types / Sound Device / Feature bits} + +There are currently no feature bits defined for this device. + +\subsection{Device configuration layout}\label{sec:Device Types / Sound Device / Device configuration layout} + +Configuration space provides information about available virtqueues and their +assignments to enabled functions using following layout structure and definitions: + +\begin{lstlisting} +enum { + /* function identifiers for virtqueue assignments */ + VIRTIO_SND_FN_BASE = 0, + VIRTIO_SND_FN_PCM +}; + +struct virtio_snd_queue_info { + /* VIRTIO_SND_FN_* */ + le16 function; + /* a function device id */ + u8 device_id; + /* a function subdevice id */ + u8 subdevice_id; +}; + +struct virtio_snd_config { + /* maximum # of available virtqueues */ + le32 nqueues; +}; +\end{lstlisting} + +The \field{nqueues} field contains a maximum amount of available virtqueues and +is followed by an \field{nqueues}-sized array of \field{struct virtio_snd_queue_info} +structures. \field{struct virtio_snd_queue_info} with index \field{i} describes +a device function assigned to a virtqueue with index \field{i}. \field{device_id} +and \field{subdevice_id} fields are used to distinguish different instances of +the same function type. + +\subsection{Device Initialization}\label{sec:Device Types / Sound Device / Device Initialization} + +\begin{enumerate} +\item Initialize all available virtqueues. +\item Retrieve a device configuration. +\item Initialize all functions enabled in the device configuration. +\end{enumerate} + +A device configuration is represented with a set of descriptors having +a fixed header using the following layout structure and definitions: + +\begin{lstlisting} +enum { + /* the PCM function descriptor types */ + VIRTIO_SND_DESC_PCM = 0, + VIRTIO_SND_DESC_PCM_STREAM +}; + +struct virtio_snd_desc { + u8 length; + u8 type; + + u16 padding; +}; +\end{lstlisting} + +The fixed header \field{struct virtio_snd_desc} in each +descriptor includes the following fields: + +\begin{description} +\item[\field{length}] specifies the total number of bytes in the descriptor. +\item[\field{type}] identifies the descriptor type (VIRTIO_SND_DESC_*). +\end{description} + +With the exception of the base function, all implemented functions MUST add +their descriptors in configuration only if a particular function (or part of +its functionality) is enabled in the device. + +\subsection{Device Operation}\label{sec:Device Types / Sound Device / Device Operation} + +All control messages are placed into a single control queue. + +All requests and responses on the queue consist of or are preceded by +a header using the following layout structure and definitions: + +\begin{lstlisting} +enum { + /* the base function request types */ + VIRTIO_SND_R_BASE_GET_CFG = 0, + + /* the PCM function request types */ + VIRTIO_SND_R_PCM_SET_FORMAT = 0x0100, + VIRTIO_SND_R_PCM_PREPARE, + VIRTIO_SND_R_PCM_START, + VIRTIO_SND_R_PCM_STOP, + VIRTIO_SND_R_PCM_PAUSE, + VIRTIO_SND_R_PCM_UNPAUSE, + VIRTIO_SND_R_PCM_QUERY_CHMAP, + VIRTIO_SND_R_PCM_USE_CHMAP, + + /* response status codes */ + VIRTIO_SND_S_OK = 0x8000, + VIRTIO_SND_S_ENOTSUPPORTED, + VIRTIO_SND_S_EINVALID, + VIRTIO_SND_S_EIO +}; + +struct virtio_snd_hdr { + le32 code; +}; +\end{lstlisting} + +The generic header \field{struct virtio_snd_hdr} contains the only field: + +\begin{description} +\item[\field{code}] specifies a type of the driver request +(VIRTIO_SND_R_*) or a device response status code (VIRTIO_SND_S_*). +\end{description} + +\subsubsection{Device Operation: Base function} + +The base function is responsible for operations having a scope of or that +can affect the entire device. + +\begin{description} + +\item[VIRTIO_SND_R_BASE_GET_CFG] +Retrieve the current device configuration, response is \field{struct virtio_snd_base_configuration} +containing a set of function descriptors. + +\begin{lstlisting} +/* a maximum possible configuration data size (in bytes) */ +#define VIRTIO_SND_BASE_CFG_MAX_SIZE 1024 + +/* a response containing device configuration */ +struct virtio_snd_base_configuration { + struct virtio_snd_hdr hdr; + /* size in bytes of configuration data */ + le32 length; + /* configuration data */ + u8 data[VIRTIO_SND_BASE_CFG_MAX_SIZE]; +}; +\end{lstlisting} + +\end{description} + +\subsubsection{Device Operation: PCM function} + +The PCM function provides up to one playback and up to one capture PCM stream. +If the device supports more than one PCM stream of the same type, it MUST +provide them as separate PCM functions. + +The function puts a PCM function descriptor to a device configuration. The descriptor +is followed by up to two PCM stream descriptors. The data is stored according to +the following layout structure and definitions: + +\begin{lstlisting} +/* supported PCM stream types */ +enum { + VIRTIO_SND_PCM_T_PLAYBACK = 0, + VIRTIO_SND_PCM_T_CAPTURE +}; + +/* supported PCM sample formats */ +enum { + VIRTIO_SND_PCM_FMT_S8 = 0, + VIRTIO_SND_PCM_FMT_U8, + VIRTIO_SND_PCM_FMT_S16, + VIRTIO_SND_PCM_FMT_U16, + VIRTIO_SND_PCM_FMT_S32, + VIRTIO_SND_PCM_FMT_U32, + VIRTIO_SND_PCM_FMT_FLOAT, + VIRTIO_SND_PCM_FMT_FLOAT64 +}; + +/* supported PCM frame rates */ +enum { + VIRTIO_SND_PCM_RATE_8000 = 0, + VIRTIO_SND_PCM_RATE_11025, + VIRTIO_SND_PCM_RATE_16000, + VIRTIO_SND_PCM_RATE_22050, + VIRTIO_SND_PCM_RATE_32000, + VIRTIO_SND_PCM_RATE_44100, + VIRTIO_SND_PCM_RATE_48000, + VIRTIO_SND_PCM_RATE_64000, + VIRTIO_SND_PCM_RATE_88200, + VIRTIO_SND_PCM_RATE_96000, + VIRTIO_SND_PCM_RATE_176400, + VIRTIO_SND_PCM_RATE_192000 +}; + +/* PCM function descriptor */ +struct virtio_snd_pcm_desc { + /* sizeof(struct virtio_snd_pcm_desc) */ + u8 length; + /* VIRTIO_SND_DESC_PCM */ + u8 type; + /* a PCM function ID (assigned by the device) */ + u8 pcm_id; + /* # of PCM stream descriptors in the configuration (one per supported + * PCM stream type) + */ + u8 nstreams; +}; + +/* PCM stream descriptor */ +struct virtio_snd_pcm_stream_desc { + /* sizeof(struct virtio_snd_pcm_stream_desc) */ + u8 length; + /* VIRTIO_SND_DESC_PCM_STREAM */ + u8 type; + /* a PCM stream type (VIRTIO_SND_PCM_T_*) */ + u8 stream_type; + /* # of supported channel maps */ + u8 nchmaps; + /* minimum # of supported channels */ + le16 channels_min; + /* maximum # of supported channels */ + le16 channels_max; + /* supported sample format bit mask (1 << VIRTIO_SND_PCM_FMT_*) */ + le32 formats; + /* supported frame rate bit mask (1 << VIRTIO_SND_PCM_RATE_*) */ + le32 rates; +}; +\end{lstlisting} + +The function assumes the following command lifecycle: + +\begin{enumerate} +\item Set format +\item Prepare +\item Playback: transfer data for prebuffing. +\item Start +\item Transfer data to/from the PCM device. +\begin{enumerate} + \item Pause + \item Unpause +\end{enumerate} +\item Stop +\end{enumerate} + +PCM control requests have or consist of a fixed header with the following +layout structure: + +\begin{lstlisting} +struct virtio_snd_pcm_hdr { + /* a PCM request type (VIRTIO_SND_R_PCM_*) */ + struct virtio_snd_hdr hdr; + /* a PCM identifier (assigned in configuration) */ + u8 pcm_id; + /* a PCM stream type (VIRTIO_SND_PCM_T_*) */ + u8 stream_type; + + u16 padding; +}; +\end{lstlisting} + +\begin{description} + +\item[VIRTIO_SND_R_PCM_SET_FORMAT] +Set selected PCM format. + +\begin{lstlisting} +struct virtio_snd_pcm_set_format { + struct virtio_snd_pcm_hdr hdr; + /* # of channels */ + le16 channels; + /* a PCM sample format (VIRTIO_SND_PCM_FMT_*) */ + le16 format; + /* a PCM frame rate (VIRTIO_SND_PCM_RATE_*) */ + le16 rate; + + u16 padding; +}; +\end{lstlisting} + +\item[VIRTIO_SND_R_PCM_PREPARE] +Prepare the PCM device. + +\item[VIRTIO_SND_R_PCM_START] +Start the PCM device. + +\item[VIRTIO_SND_R_PCM_STOP] +Stop the PCM device. + +\item[VIRTIO_SND_R_PCM_PAUSE] +Set the PCM device on pause. + +\item[VIRTIO_SND_R_PCM_UNPAUSE] +Unset the PCM device from pause. + +\item[VIRTIO_SND_R_PCM_QUERY_CHMAP] +Query PCM channel map information. + +The function reports an amount of available channel maps in the PCM stream +configuration descriptor. The driver can enumerate these using the following +request and response layout structure and definitions: + +\begin{lstlisting} +enum { + /* All channels have fixed channel positions */ + VIRTIO_SND_PCM_CHMAP_FIXED = 0, + /* All channels are swappable (e.g. {FL/FR/RL/RR} -> {RR/RL/FR/FL}) */ + VIRTIO_SND_PCM_CHMAP_VARIABLE, + /* Only pair-wise channels are swappable (e.g. {FL/FR/RL/RR} -> {RL/RR/FL/FR}) */ + VIRTIO_SND_PCM_CHMAP_PAIRED +}; + +/* Standard channel position definitions */ +enum { + VIRTIO_SND_PCM_CH_NONE = 0, /* undefined */ + VIRTIO_SND_PCM_CH_NA, /* silent */ + VIRTIO_SND_PCM_CH_MONO, /* mono stream */ + VIRTIO_SND_PCM_CH_FL, /* front left */ + VIRTIO_SND_PCM_CH_FR, /* front right */ + VIRTIO_SND_PCM_CH_RL, /* rear left */ + VIRTIO_SND_PCM_CH_RR, /* rear right */ + VIRTIO_SND_PCM_CH_FC, /* front center */ + VIRTIO_SND_PCM_CH_LFE, /* low frequency (LFE) */ + VIRTIO_SND_PCM_CH_SL, /* side left */ + VIRTIO_SND_PCM_CH_SR, /* side right */ + VIRTIO_SND_PCM_CH_RC, /* rear center */ + VIRTIO_SND_PCM_CH_FLC, /* front left center */ + VIRTIO_SND_PCM_CH_FRC, /* front right center */ + VIRTIO_SND_PCM_CH_RLC, /* rear left center */ + VIRTIO_SND_PCM_CH_RRC, /* rear right center */ + VIRTIO_SND_PCM_CH_FLW, /* front left wide */ + VIRTIO_SND_PCM_CH_FRW, /* front right wide */ + VIRTIO_SND_PCM_CH_FLH, /* front left high */ + VIRTIO_SND_PCM_CH_FCH, /* front center high */ + VIRTIO_SND_PCM_CH_FRH, /* front right high */ + VIRTIO_SND_PCM_CH_TC, /* top center */ + VIRTIO_SND_PCM_CH_TFL, /* top front left */ + VIRTIO_SND_PCM_CH_TFR, /* top front right */ + VIRTIO_SND_PCM_CH_TFC, /* top front center */ + VIRTIO_SND_PCM_CH_TRL, /* top rear left */ + VIRTIO_SND_PCM_CH_TRR, /* top rear right */ + VIRTIO_SND_PCM_CH_TRC, /* top rear center */ + VIRTIO_SND_PCM_CH_TFLC, /* top front left center */ + VIRTIO_SND_PCM_CH_TFRC, /* top front right center */ + VIRTIO_SND_PCM_CH_TSL, /* top side left */ + VIRTIO_SND_PCM_CH_TSR, /* top side right */ + VIRTIO_SND_PCM_CH_LLFE, /* left LFE */ + VIRTIO_SND_PCM_CH_RLFE, /* right LFE */ + VIRTIO_SND_PCM_CH_BC, /* bottom center */ + VIRTIO_SND_PCM_CH_BLC, /* bottom left center */ + VIRTIO_SND_PCM_CH_BRC /* bottom right center */ +}; + +#define VIRTIO_SND_PCM_CH_MAX 256 + +struct virtio_snd_pcm_query_chmap { + struct virtio_snd_hdr hdr; + /* a PCM identifier (assigned in configuration) */ + u8 pcm_id; + /* a PCM stream type (VIRTIO_SND_PCM_T_*) */ + u8 stream_type; + /* a PCM channel map identifier [0 .. virtio_snd_pcm_stream_desc::nchmaps - 1] */ + u8 chmap_id; + + u8 padding; +}; + +/* a response containing PCM channel map information */ +struct virtio_snd_pcm_chmap_info { + /* a response status code (VIRTIO_SND_S_*) */ + struct virtio_snd_hdr hdr; + /* unused */ + u8 pcm_id; + /* a PCM channel map type (VIRTIO_SND_PCM_CHMAP_*) */ + u8 type; + /* # of valid entries in the positions array */ + le16 nchannels; + /* PCM channel positions */ + u8 positions[VIRTIO_SND_PCM_CH_MAX]; +}; +\end{lstlisting} + +\item[VIRTIO_SND_R_PCM_USE_CHMAP] +Use modified PCM channel map. + +In case of a channel map has swappable positions, the driver can set a modified +channel map using the same \field{struct virtio_snd_pcm_chmap_info} structure as +request. + +\begin{lstlisting} +/* a request containing PCM channel map information */ +struct virtio_snd_pcm_chmap_info { + /* VIRTIO_SND_R_PCM_USE_CHMAP */ + struct virtio_snd_hdr hdr; + /* a PCM identifier (assigned in configuration) */ + u8 pcm_id; + /* a PCM stream type (VIRTIO_SND_PCM_T_*) */ + u8 type; + /* # of valid entries in the positions array */ + le16 nchannels; + /* PCM channel positions */ + u8 positions[VIRTIO_SND_PCM_CH_MAX]; +}; +\end{lstlisting} + +\end{description} + +All IO requests are placed into a single virtqueue assigned for PCM data +transport. Each request is of form: + +\begin{lstlisting} +struct virtio_snd_pcm_xfer { + /* a PCM stream type (VIRTIO_SND_PCM_T_*) */ + u8 stream_type; + /* a PCM frame buffer */ + u8 data[]; + /* VIRTIO_SND_S_* */ + le32 status; +}; +\end{lstlisting} + +The device returns an actual amount of bytes read from/written to data buffer. -- 2.22.1 Please mind our privacy notice<https://www.opensynergy.com/datenschutzerklaerung/privacy-notice-for-business-partners-pursuant-to-article-13-of-the-general-data-protection-regulation-gdpr/> pursuant to Art. 13 GDPR. // Unsere Hinweise zum Datenschutz gem. Art. 13 DSGVO finden Sie hier.<https://www.opensynergy.com/de/datenschutzerklaerung/datenschutzhinweise-fuer-geschaeftspartner-gem-art-13-dsgvo/>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]