Skip to contentSkip to conversation

virtio-sound: use 'data buffer' instead of 'buffer'

RFC PATCH In review Matias Ezequiel Vara Larsen 2 participants 3 messages Aug 10, 2023 – Nov 30, 2023

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 virtio-sound: use 'data buffer' instead of 'buffer'

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

---
 device-types/sound/description.tex | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)
device-types/sound/description.tex +13 -13
index 54c9c8e..97151fa 100644
@@ -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}
Signature · 18 lines
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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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/
#1 lore raw

Ping Anton.

Thanks.

Quoted 96 lines · 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'.

---
 device-types/sound/description.tex | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)
device-types/sound/description.tex +13 -14
index 54c9c8e..97151fa 100644
@@ -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}
--
Quoted 2 lines

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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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/

Reviewed-by
#2 lore raw

Thanks Matias!

Quoted 19 lines · Matias Ezequiel Vara Larsen

Ping Anton.

Thanks.

Quoted 13 lines · 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'.

Quoted 103 lines
Quoted 83 lines
---
  device-types/sound/description.tex | 26 +++++++++++++-------------
  1 file changed, 13 insertions(+), 13 deletions(-)
device-types/sound/description.tex +13 -14
index 54c9c8e..97151fa 100644
@@ -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}
--
Quoted 2 lines

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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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

Signature · 21 lines
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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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/