Re: [PATCH] virtio-sound: use 'data buffer' instead of 'buffer'

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

On Thu, Nov 30, 2023 at 11:58:37AM +0100, Matias Ezequiel Vara Larsen wrote:
> This commit replaces the wording 'buffer' with 'data buffer' when
> referring to the payload of PCM messages. The virtio specification
> defines the word buffer as a set of zero or more device-readable
> physically-contiguous elements followed by zero or more
> physically-contiguous device-writable elements. In the virtio-sound
> section, the word is used only for the data or payload in a request. In
> this case, the data buffer is sent together with a header, i.e.,
> device-readable, and the status, i.e., device-writable. To not get
> confused with the main definition, this commit replaces those usages
> with the wording 'data buffer'.
> 
> Reviewed-by: Anton Yakovlev <anton.yakovlev@opensynergy.com>
> Signed-off-by: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>
> ---
>  device-types/sound/description.tex | 26 +++++++++++++-------------
>  1 file changed, 13 insertions(+), 13 deletions(-)
> 
> diff --git a/device-types/sound/description.tex b/device-types/sound/description.tex
> index 54c9c8e..97151fa 100644
> --- a/device-types/sound/description.tex
> +++ b/device-types/sound/description.tex
> @@ -667,8 +667,8 @@ \subsubsection{PCM Notifications}
>  
>  \subsubsection{PCM I/O Messages}\label{sec:Device Types / Sound Device / Device Operation / PCM IO Messages}
>  
> -An I/O message consists of the header part, followed by the buffer, and then
> -the status part.
> +An I/O message consists of a buffer that contains a header part, followed by
> +the data buffer, and then the status part.
>  
>  \begin{lstlisting}
>  /* an I/O header */
> @@ -697,20 +697,20 @@ \subsubsection{PCM I/O Messages}\label{sec:Device Types / Sound Device / Device
>  \item[\field{latency_bytes}] indicates the current device latency.
>  \end{description}
>  
> -Since all buffers in the queue (with one exception) should be of the size
> +Since all data buffers in the queue (with one exception) should be of the size
>  \field{period_bytes}, the completion of such an I/O request can be considered an
>  elapsed period notification.
>  
>  \paragraph{Output Stream}
>  
> -In case of an output stream, the header is followed by a device-readable buffer
> -containing PCM frames for writing to the device. All messages are placed into
> -the tx queue.
> +In case of an output stream, the header is followed by a device-readable data
> +buffer containing PCM frames for writing to the device. All messages are placed
> +into the tx queue.
>  
>  \devicenormative{\subparagraph}{Output Stream}{Device Types / Sound Device / Device Operation / PCM Output Stream}
>  
>  \begin{itemize}
> -\item The device MUST NOT complete the I/O request until the buffer is totally
> +\item The device MUST NOT complete the I/O request until the data buffer is totally
>  consumed.
>  \end{itemize}
>  
> @@ -718,13 +718,13 @@ \subsubsection{PCM I/O Messages}\label{sec:Device Types / Sound Device / Device
>  
>  \begin{itemize}
>  \item The driver SHOULD populate the tx queue with \field{period_bytes} sized
> -buffers. The only exception is the end of the stream.
> -\item The driver MUST NOT place device-writable buffers into the tx queue.
> +data buffers. The only exception is the end of the stream.
> +\item The driver MUST NOT place device-writable data buffers into the tx queue.
>  \end{itemize}
>  
>  \paragraph{Input Stream}
>  
> -In case of an input stream, the header is followed by a device-writable buffer
> +In case of an input stream, the header is followed by a device-writable data buffer
>  being populated with PCM frames from the device. All messages are placed into
>  the rx queue.
>  
> @@ -735,7 +735,7 @@ \subsubsection{PCM I/O Messages}\label{sec:Device Types / Sound Device / Device
>  \devicenormative{\subparagraph}{Input Stream}{Device Types / Sound Device / Device Operation / PCM Input Stream}
>  
>  \begin{itemize}
> -\item The device MUST NOT complete the I/O request until the buffer is full.
> +\item The device MUST NOT complete the I/O request until the data buffer is full.
>  The only exception is the end of the stream.
>  \end{itemize}
>  
> @@ -743,8 +743,8 @@ \subsubsection{PCM I/O Messages}\label{sec:Device Types / Sound Device / Device
>  
>  \begin{itemize}
>  \item The driver SHOULD populate the rx queue with \field{period_bytes} sized
> -empty buffers before starting the stream.
> -\item The driver MUST NOT place device-readable buffers into the rx queue.
> +empty data buffers before starting the stream.
> +\item The driver MUST NOT place device-readable data buffers into the rx queue.
>  \end{itemize}
>  
>  \subsubsection{Channel Map Control Messages}\label{sec:Device Types / Sound Device / Device Operation / Channel Map Control Messages}
> -- 
> 2.41.0
> 
Dear TC,

I'd like to request a vote on solving issue 190.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/190

Matias