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

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

[Matias Ezequiel Vara Larsen]

This RFC 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 rfc replaces those usages
with the wording 'data buffer'.

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: [RFC PATCH] virtio-sound: use 'data buffer' instead of 'buffer'

[Matias Ezequiel Vara Larsen]

Ping Anton.

Thanks.

On Thu, Aug 10, 2023 at 10:49 AM Matias Ezequiel Vara Larsen
<mvaralar@redhat.com> wrote:
>
> This RFC 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 rfc replaces those usages
> with the wording 'data buffer'.
>
> 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/

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

[Anton Yakovlev]

Thanks Matias!


On 07.11.2023 19:44, Matias Ezequiel Vara Larsen wrote:
> Ping Anton.
> 
> Thanks.
> 
> On Thu, Aug 10, 2023 at 10:49 AM Matias Ezequiel Vara Larsen
> <mvaralar@redhat.com> wrote:
>>
>> This RFC 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 rfc replaces those usages
>> with the wording 'data buffer'.
>>
>> Signed-off-by: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>

Reviewed-by: Anton Yakovlev <anton.yakovlev@opensynergy.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://ddec1-0-en-ctp.trendmicro.com:443/wis/clicktime/v1/query?url=https%3a%2f%2flists.oasis%2dopen.org%2farchives%2fvirtio%2dcomment%2f&umid=712cc7d1-89c4-4fe6-ba4d-f837c9bfbb70&auth=53c7c7de28b92dfd96e93d9dd61a23e634d2fbec-33f7fa8186adb3787c19caba063f9091b97a976c
> Feedback License: https://ddec1-0-en-ctp.trendmicro.com:443/wis/clicktime/v1/query?url=https%3a%2f%2fwww.oasis%2dopen.org%2fwho%2fipr%2ffeedback%5flicense.pdf&umid=712cc7d1-89c4-4fe6-ba4d-f837c9bfbb70&auth=53c7c7de28b92dfd96e93d9dd61a23e634d2fbec-7528091485193ee258a34724f10aefeb711a1a79
> List Guidelines: https://ddec1-0-en-ctp.trendmicro.com:443/wis/clicktime/v1/query?url=https%3a%2f%2fwww.oasis%2dopen.org%2fpolicies%2dguidelines%2fmailing%2dlists&umid=712cc7d1-89c4-4fe6-ba4d-f837c9bfbb70&auth=53c7c7de28b92dfd96e93d9dd61a23e634d2fbec-53e9d4d56cab5dcc2902e23b5f29901dda274296
> Committee: https://ddec1-0-en-ctp.trendmicro.com:443/wis/clicktime/v1/query?url=https%3a%2f%2fwww.oasis%2dopen.org%2fcommittees%2fvirtio%2f&umid=712cc7d1-89c4-4fe6-ba4d-f837c9bfbb70&auth=53c7c7de28b92dfd96e93d9dd61a23e634d2fbec-0e7cd0c69d4809fe2835e5f487ed63a1bd8a23bb
> Join OASIS: https://ddec1-0-en-ctp.trendmicro.com:443/wis/clicktime/v1/query?url=https%3a%2f%2fwww.oasis%2dopen.org%2fjoin%2f&umid=712cc7d1-89c4-4fe6-ba4d-f837c9bfbb70&auth=53c7c7de28b92dfd96e93d9dd61a23e634d2fbec-df0d1d72483e28fb192468a5196ca3b61101c75e
> 

-- 
Anton Yakovlev
Senior Software Engineer

OpenSynergy GmbH
Rotherstr. 20, 10245 Berlin

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/