Re: [RFC PATCH] virtio-snd: improve PCM command lifecycle description

[Matias Ezequiel Vara Larsen <mvaralar@redhat.com>]

Ping Anton.

Matias

On Wed, Jul 12, 2023 at 10:37âAM Matias Ezequiel Vara Larsen
<mvaralar@redhat.com> wrote:
>
> The PCM command lifecycle can be described as a state-machine in which
> the switching between states is triggered by commands. This commit
> explicitly presents the different states and the commands that are
> allowed in a given state. This commit leaves to the implementation the
> decision the state reached depending on the command.
>
> Signed-off-by: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>
> ---
>  device-types/sound/description.tex | 26 +++++++++++++++++++-------
>  1 file changed, 19 insertions(+), 7 deletions(-)
>
> diff --git a/device-types/sound/description.tex b/device-types/sound/description.tex
> index 54c9c8e..55e93af 100644
> --- a/device-types/sound/description.tex
> +++ b/device-types/sound/description.tex
> @@ -397,9 +397,21 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev
>  \item[\field{stream_id}] specifies a PCM stream identifier from 0 to \field{streams} - 1.
>  \end{description}
>
> -\paragraph{PCM Command Lifecycle}
> +\paragraph{PCM Command Lifecycle State Machine}
>
> -A PCM stream has the following command lifecycle:
> +A PCM stream can be represented by a state-machine made up of the following
> +states:
> +\begin{description}
> +\item SET PARAMETERS
> +\item PREPARE
> +\item START
> +\item STOP
> +\item RELEASE
> +\end{description}
> +
> +A command triggers the transition between these states. To what state to switch
> +depends on the implementation. Depending on the state, only certain commands
> +are valid. An error may occur if an invalid command is triggered.
>
>  \begin{enumerate}
>  \item SET PARAMETERS
> @@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev
>  The driver negotiates the stream parameters (format, transport, etc) with
>  the device.
>
> -Possible valid transitions: set parameters, prepare.
> +Possible valid commands: set parameters, prepare.
>
>  \item PREPARE
>
>  The device prepares the stream (allocates resources, etc).
>
> -Possible valid transitions: set parameters, prepare, start, release.
> +Possible valid commands: set parameters, prepare, start, release.
>
>  \item Output only: the driver transfers data for pre-buffing.
>
> @@ -421,7 +433,7 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev
>
>  The device starts the stream (unmute, putting into running state, etc).
>
> -Possible valid transitions: stop.
> +Possible valid commands: stop.
>
>  \item The driver transfers data to/from the stream.
>
> @@ -429,13 +441,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev
>
>  The device stops the stream (mute, putting into non-running state, etc).
>
> -Possible valid transitions: start, release.
> +Possible valid commands: start, release.
>
>  \item RELEASE
>
>  The device releases the stream (frees resources, etc).
>
> -Possible valid transitions: set parameters, prepare.
> +Possible valid commands: set parameters, prepare.
>
>  \end{enumerate}
>
> --
> 2.41.0
>