From: Matias Ezequiel Vara Larsen <mvaralar@redhat.com>
To: virtio-comment@lists.oasis-open.org
Cc: anton.yakovlev@opensynergy.com
Subject: [virtio-comment] [RFC PATCH] virtio-sound: use 'data buffer' instead of 'buffer'
Date: Thu, 10 Aug 2023 10:48:59 +0200 [thread overview]
Message-ID: <ZNSke4Vs0jUSr3Jb@fedora> (raw)
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/
next reply other threads:[~2023-08-10 8:50 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-08-10 8:48 Matias Ezequiel Vara Larsen [this message]
2023-11-07 10:44 ` [virtio-comment] Re: [RFC PATCH] virtio-sound: use 'data buffer' instead of 'buffer' Matias Ezequiel Vara Larsen
2023-11-30 2:10 ` Anton Yakovlev
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZNSke4Vs0jUSr3Jb@fedora \
--to=mvaralar@redhat.com \
--cc=anton.yakovlev@opensynergy.com \
--cc=virtio-comment@lists.oasis-open.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).