virtio-snd: improve PCM command lifecycle description
PATCH RESEND 1/1 virtio-snd: improve PCM command lifecycle description
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.
--- device-types/sound/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-)
device-types/sound/description.tex +19 -7
@@ -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}
Signature · 1 line
2.41.0
Quoted 22 lines · Matias Ezequiel Vara Larsen
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 <[email protected]>---
device-types/sound/description.tex | 26 +++++++++++++++++++-------1 file changed, 19 insertions(+), 7 deletions(-)device-types/sound/description.tex +0
-0@@ -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}
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 403
Quoted 3 lines
device-types/sound/description.tex +2
-1-A PCM stream has the following command lifecycle: +A PCM stream can be represented by a state-machine made up of the following +states:
I'm not clear about the difference between commands and states. Are they the same?
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 414
Quoted 12 lines
+\begin{description}
+\item SET PARAMETERS
+\item PREPARE
+\item START
+\item STOP
+\item RELEASE
+\end{description}device-types/sound/description.tex +4
-0+ +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.
Should we explain what the following list is?
Quoted 47 lines
\begin{enumerate}
\item SET PARAMETERSdevice-types/sound/description.tex +0
-0@@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe driver negotiates the stream parameters (format, transport, etc) with the device.
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.\item PREPARE
The device prepares the stream (allocates resources, etc).
device-types/sound/description.tex +1
-1-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.
device-types/sound/description.tex +0
-0@@ -421,7 +433,7 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe device starts the stream (unmute, putting into running state, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: stop. +Possible valid commands: stop.\item The driver transfers data to/from the stream.
device-types/sound/description.tex +0
-0@@ -429,13 +441,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe device stops the stream (mute, putting into non-running state, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: start, release. +Possible valid commands: start, release.\item RELEASE
The device releases the stream (frees resources, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.\end{enumerate}
Signature · 1 line
2.41.0
Quoted 23 lines · Stefano Garzarella
Quoted 22 lines · Matias Ezequiel Vara Larsen
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 <[email protected]>---
device-types/sound/description.tex | 26 +++++++++++++++++++-------1 file changed, 19 insertions(+), 7 deletions(-)device-types/sound/description.tex +0
-0@@ -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}
Quoted 7 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 403
Quoted 3 lines
device-types/sound/description.tex +2
-1-A PCM stream has the following command lifecycle: +A PCM stream can be represented by a state-machine made up of the following +states:I'm not clear about the difference between commands and states. Are they the same?
AFAIU, a command is a request that comes into the control queue, such as prepare, set_params, stop, start, etc. State refers to a stream's current state. A command triggers a transition over the stream's states. There is a set of valid commands that are allowed in each state. The specification does not make such a distinction. I wonder if this was done on purpose by the authors.
Quoted 6 lines
Quoted 6 lines
+\begin{description}
+\item SET PARAMETERS
+\item PREPARE
+\item START
+\item STOP
+\item RELEASE
Quoted 9 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 414
Quoted 6 lines
+\end{description}
device-types/sound/description.tex +4
-0+ +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.Should we explain what the following list is?
I think we should. The list is the states and the commands that are valid in a given state. The specification does not explain the state that is taken when a command is triggered. I though leaving that for the implementation.
Quoted 9 lines
device-types/sound/description.tex
Quoted 9 lines
\begin{enumerate}
\item SET PARAMETERSdevice-types/sound/description.tex +0
-0@@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe driver negotiates the stream parameters (format, transport, etc) with the device.
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.
For example, in the SET_PARAMETERS state, there are two valid commands:
set parameters and prepare. Any other command in this state would be invalid. If the frontend triggers the set_parameters command, the backend may decide to either keep the stream state in SET_PARAMETERS or switch to PREPARE.
In the spec they use the wording transition and I think they mean the valid next stream state. I changed this so now the spec specifies the valid commands in a given state thus leaving for the implementation the transition or the next state.
Thanks,
Quoted 39 lines
Quoted 38 lines
\item PREPARE
The device prepares the stream (allocates resources, etc).
device-types/sound/description.tex +1
-1-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.
device-types/sound/description.tex +0
-0@@ -421,7 +433,7 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe device starts the stream (unmute, putting into running state, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: stop. +Possible valid commands: stop.\item The driver transfers data to/from the stream.
device-types/sound/description.tex +0
-0@@ -429,13 +441,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe device stops the stream (mute, putting into non-running state, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: start, release. +Possible valid commands: start, release.\item RELEASE
The device releases the stream (frees resources, etc).
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.\end{enumerate}
Signature · 1 line
2.41.0
Quoted 32 lines · Matias Ezequiel Vara Larsen
Quoted 23 lines · Stefano Garzarella
Quoted 22 lines · Matias Ezequiel Vara Larsen
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 <[email protected]>---
device-types/sound/description.tex | 26 +++++++++++++++++++-------1 file changed, 19 insertions(+), 7 deletions(-)device-types/sound/description.tex +0
-0@@ -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}Quoted 7 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 403
Quoted 3 lines
device-types/sound/description.tex +2
-1-A PCM stream has the following command lifecycle: +A PCM stream can be represented by a state-machine made up of the following +states:I'm not clear about the difference between commands and states. Are they the same?
Quoted 6 lines
AFAIU, a command is a request that comes into the control queue, such as prepare,
set_params, stop, start, etc. State refers to a stream's current state. A command triggers a transition over the stream's states. There is a set of valid commands that are allowed in each state. The specification does not make such a distinction. I wonder if this was done on purpose by the authors.
Okay, so there is a 1:1 overlap between commands and states. Basically, the “stop” command has the action of moving the state from the current to the “stop” state, right?
Quoted 38 lines
Quoted 16 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 414
Quoted 13 lines
+\begin{description}
+\item SET PARAMETERS
+\item PREPARE
+\item START
+\item STOP
+\item RELEASE
+\end{description}device-types/sound/description.tex +4
-0+ +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.Should we explain what the following list is?
I think we should. The list is the states and the commands that are valid in a given state. The specification does not explain the state that is taken when a command is triggered. I though leaving that for the implementation.
Quoted 9 lines
device-types/sound/description.tex
Quoted 9 lines
\begin{enumerate}
\item SET PARAMETERSdevice-types/sound/description.tex +0
-0@@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe driver negotiates the stream parameters (format, transport, etc) with the device.
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.For example, in the
SET_PARAMETERSstate, there are two valid commands:
set parameters and prepare. Any other command in this state would be invalid. If the frontend triggers theset_parameterscommand, the backend may decide to either keep the stream state inSET_PARAMETERSor switch to PREPARE.
Quoted 4 lines
In the spec they use the wording
transitionand I think they mean the valid next stream state. I changed this so now the spec specifies the valid commands in a given state thus leaving for the implementation the transition or the next state.
Okay, perhaps we need to clarify that commands and states are in a 1:1 relationship and that a command indicates the state to which to move.
Thanks,
Stefano
This sounds like it is unnecessarily overthought, semantically there's only one command, "change state to" and it has a payload of "the new desired state to transition to"
Quoted 41 lines · Stefano Garzarella
Quoted 32 lines · Matias Ezequiel Vara Larsen
Quoted 23 lines · Stefano Garzarella
Quoted 22 lines · Matias Ezequiel Vara Larsen
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 <[email protected]>---
device-types/sound/description.tex | 26 +++++++++++++++++++-------1 file changed, 19 insertions(+), 7 deletions(-)device-types/sound/description.tex +0
-0@@ -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}Quoted 7 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 403
Quoted 3 lines
device-types/sound/description.tex +2
-1-A PCM stream has the following command lifecycle: +A PCM stream can be represented by a state-machine made up of the following +states:I'm not clear about the difference between commands and states. Are they the same?
Quoted 6 lines
AFAIU, a command is a request that comes into the control queue, such as prepare,
set_params, stop, start, etc. State refers to a stream's current state. A command triggers a transition over the stream's states. There is a set of valid commands that are allowed in each state. The specification does not make such a distinction. I wonder if this was done on purpose by the authors.
Quoted 46 lines
Okay, so there is a 1:1 overlap between commands and states. Basically, the “stop” command has the action of moving the state from the current to the “stop” state, right?
Quoted 42 lines
Quoted 16 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 414
Quoted 13 lines
+\begin{description}
+\item SET PARAMETERS
+\item PREPARE
+\item START
+\item STOP
+\item RELEASE
+\end{description}device-types/sound/description.tex +4
-0+ +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.Should we explain what the following list is?
I think we should. The list is the states and the commands that are valid in a given state. The specification does not explain the state that is taken when a command is triggered. I though leaving that for the implementation.
Quoted 9 lines
device-types/sound/description.tex
Quoted 9 lines
\begin{enumerate}
\item SET PARAMETERSdevice-types/sound/description.tex +0
-0@@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe driver negotiates the stream parameters (format, transport, etc) with the device.
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.For example, in the
SET_PARAMETERSstate, there are two valid commands:
set parameters and prepare. Any other command in this state would be invalid. If the frontend triggers theset_parameterscommand, the backend may decide to either keep the stream state inSET_PARAMETERSor switch to PREPARE.In the spec they use the wording
transitionand I think they mean the valid next stream state. I changed this so now the spec specifies the valid commands in a given state thus leaving for the implementation the transition or the next state.
Transition is standard sequential logic terminology. In a finite state machine you can just say that a state has next states; they are not "valid", they are just the only ones existing.
What can be valid or not is the transition.
Signature · 2 lines
Manos Pitsidianakis Emulation and Virtualization Engineer at Linaro Ltd
Quoted 40 lines · Stefano Garzarella
Quoted 32 lines · Matias Ezequiel Vara Larsen
Quoted 23 lines · Stefano Garzarella
Quoted 22 lines · Matias Ezequiel Vara Larsen
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 <[email protected]>---
device-types/sound/description.tex | 26 +++++++++++++++++++-------1 file changed, 19 insertions(+), 7 deletions(-)device-types/sound/description.tex +0
-0@@ -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}Quoted 7 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 403
Quoted 3 lines
device-types/sound/description.tex +2
-1-A PCM stream has the following command lifecycle: +A PCM stream can be represented by a state-machine made up of the following +states:I'm not clear about the difference between commands and states. Are they the same?
Quoted 6 lines
AFAIU, a command is a request that comes into the control queue, such as prepare,
set_params, stop, start, etc. State refers to a stream's current state. A command triggers a transition over the stream's states. There is a set of valid commands that are allowed in each state. The specification does not make such a distinction. I wonder if this was done on purpose by the authors.
Quoted 4 lines
Okay, so there is a 1:1 overlap between commands and states. Basically, the “stop” command has the action of moving the state from the current to the “stop” state, right?
Right
Quoted 38 lines
Quoted 38 lines
Quoted 16 lines
device-types/sound/description.tex \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev · line 414
Quoted 13 lines
+\begin{description}
+\item SET PARAMETERS
+\item PREPARE
+\item START
+\item STOP
+\item RELEASE
+\end{description}device-types/sound/description.tex +4
-0+ +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.Should we explain what the following list is?
I think we should. The list is the states and the commands that are valid in a given state. The specification does not explain the state that is taken when a command is triggered. I though leaving that for the implementation.
Quoted 9 lines
device-types/sound/description.tex
Quoted 9 lines
\begin{enumerate}
\item SET PARAMETERSdevice-types/sound/description.tex +0
-0@@ -407,13 +419,13 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / DevThe driver negotiates the stream parameters (format, transport, etc) with the device.
device-types/sound/description.tex +1
-1-Possible valid transitions: set parameters, prepare. +Possible valid commands: set parameters, prepare.For example, in the
SET_PARAMETERSstate, there are two valid commands:
set parameters and prepare. Any other command in this state would be invalid. If the frontend triggers theset_parameterscommand, the backend may decide to either keep the stream state inSET_PARAMETERSor switch to PREPARE.
Quoted 8 lines
Quoted 4 lines
In the spec they use the wording
transitionand I think they mean the valid next stream state. I changed this so now the spec specifies the valid commands in a given state thus leaving for the implementation the transition or the next state.Okay, perhaps we need to clarify that commands and states are in a 1:1 relationship and that a command indicates the state to which to move.
Yes, I think that may help to clarify the spec.
When the spec defines the following statement in PREPARE:
"Possible valid transitions: set parameters, prepare, start, release."
This would mean that, if current state is PREPARE and the "set parameters" command is issued, the transition to the SET PARAMETERS state would be taken. In my opinion, since the spec talks about a "possible valid transition", the implementation may decide to either transit to the SET PARAMETERS state or stay in PREPARE since both where valid.
Honestly, I do not know if these comments help to clarify the spec.
Matias