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

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

[Matias Ezequiel Vara Larsen]

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


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[Matias Ezequiel Vara Larsen]

On Thu, Nov 30, 2023 at 11:58 AM Matias Ezequiel Vara Larsen
<mvaralar@redhat.com> 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}
> --

Hello Anton,

I apologize for asking again, but could you please add your R-b to
this patch? you have already reviewed the RFC.

Thanks.


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[Anton Yakovlev]

Hello Matias,

On 20.02.2024 18:11, Matias Ezequiel Vara Larsen wrote:
> On Thu, Nov 30, 2023 at 11:58 AM Matias Ezequiel Vara Larsen
> <mvaralar@redhat.com> 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}
>> --
> 
> Hello Anton,
> 
> I apologize for asking again, but could you please add your R-b to
> this patch? you have already reviewed the RFC.

But, as you said, it already contains my R-b. I just can't imagine how
to do it again. :)

I think this patch is already ok.


Kind regards,

> 
> Thanks.
> 
> 
> This publicly archived list offers a means to provide input to the
> OASIS Virtual I/O Device (VIRTIO) TC.
> 
> In order to verify user consent to the Feedback License terms and
> to minimize spam in the list archive, subscription is required
> before posting.
> 
> Subscribe: virtio-comment-subscribe@lists.oasis-open.org
> Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
> List help: virtio-comment-help@lists.oasis-open.org
> List archive: https://lists.oasis-open.org/archives/virtio-comment/
> Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
> List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
> Committee: https://www.oasis-open.org/committees/virtio/
> Join OASIS: https://www.oasis-open.org/join/
> 

-- 
Anton Yakovlev
Senior Software Engineer

OpenSynergy GmbH
Rotherstr. 20, 10245 Berlin

Phone: +49 30 60 98 54 0
E-Mail: anton.yakovlev@opensynergy.com

www.opensynergy.com

Handelsregister/Commercial Registry: Amtsgericht Charlottenburg, HRB 108616B
Geschäftsführer/Managing Director: Regis Adjamah

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[Matias Ezequiel Vara Larsen]

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


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[Cornelia Huck]

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.)


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

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

[Matias Ezequiel Vara Larsen]

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