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

[Cornelia Huck <cohuck@redhat.com>]

On Tue, Feb 27 2024, Matias Ezequiel Vara Larsen <mvaralar@redhat.com> wrote:

> 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

Hi Matias,

unfortunately, this will have to wait until after the OASIS
infrastructure migration has finished (and we have dealt with any
fallout.)