Skip to contentSkip to conversation

vsock: add documentation about len header field

PATCH Superseded Laura Loghin 3 participants 5 messages Mar 22, 2022 – Apr 7, 2022

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 vsock: add documentation about len header field

---
 virtio-vsock.tex | 5 +++++
 1 file changed, 5 insertions(+)
virtio-vsock.tex +5 -0
index d79984d..e32cad8 100644
@@ -107,6 +107,11 @@ \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op
 #define VIRTIO_VSOCK_OP_CREDIT_REQUEST 7
 \end{lstlisting}
 
+\field{len} is the size of the payload, in bytes. However, the driver may
+provide buffer(s) for the payload that have a total size longer than
+\field{len}. If that is the case, only the first \field{len} bytes MUST be
+used for the actual data.
+
 \subsubsection{Virtqueue Flow Control}\label{sec:Device Types / Socket Device / Device Operation / Virtqueue Flow Control}
 
 The tx virtqueue carries packets initiated by applications and replies to
Signature · 23 lines
2.17.1




Amazon Development Center (Romania) S.R.L. registered office: 27A Sf. Lazar Street, UBC5, floor 2, Iasi, Iasi County, 700045, Romania. Registered in Romania. Registration number J22/2621/2005.


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

Hi Laura,

Quoted 11 lines · Laura Loghin
---
 virtio-vsock.tex | 5 +++++
 1 file changed, 5 insertions(+)
virtio-vsock.tex +0 -0
index d79984d..e32cad8 100644

virtio-vsock.tex \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op · line 114

Quoted 8 lines
virtio-vsock.tex +5 -0
@@ -107,6 +107,11 @@ \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op
 #define VIRTIO_VSOCK_OP_CREDIT_REQUEST 7
 \end{lstlisting}
 
+\field{len} is the size of the payload, in bytes. However, the driver may
+provide buffer(s) for the payload that have a total size longer than
+\field{len}. If that is the case, only the first \field{len} bytes MUST be
+used for the actual data.
+

IIUC MUST and friends are for normative sections, so I would remove the last sentence.

Thanks,
Stefano

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/

#2 lore raw
Quoted 20 lines · Stefano Garzarella

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you can confirm the sender and know the content is safe.

Hi Laura,

Quoted 13 lines · Laura Loghin
---
  virtio-vsock.tex | 5 +++++
  1 file changed, 5 insertions(+)
virtio-vsock.tex +0 -0
index d79984d..e32cad8 100644
@@ -107,6 +107,11 @@ \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op
  #define VIRTIO_VSOCK_OP_CREDIT_REQUEST 7
  \end{lstlisting}
 
Quoted 7 lines

virtio-vsock.tex \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op · line 114

Quoted 5 lines
virtio-vsock.tex +5 -0
+\field{len} is the size of the payload, in bytes. However, the driver may
+provide buffer(s) for the payload that have a total size longer than
+\field{len}. If that is the case, only the first \field{len} bytes MUST be
+used for the actual data.
+

IIUC MUST and friends are for normative sections, so I would remove the last sentence.

You're right, I'll remove it. It should already be clear enough only the first len bytes need to be used for the payload.

Thanks,
Laura

Quoted 5 lines

Thanks,
Stefano

Amazon Development Center (Romania) S.R.L. registered office: 27A Sf. Lazar Street, UBC5, floor 2, Iasi, Iasi County, 700045, Romania. Registered in Romania. Registration number J22/2621/2005.

#3 lore raw
Quoted 29 lines · Laura Loghin
Quoted 20 lines · Stefano Garzarella

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you can confirm the sender and know the content is safe.

Hi Laura,

Quoted 13 lines · Laura Loghin
---
  virtio-vsock.tex | 5 +++++
  1 file changed, 5 insertions(+)
virtio-vsock.tex +0 -0
index d79984d..e32cad8 100644
@@ -107,6 +107,11 @@ \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op
  #define VIRTIO_VSOCK_OP_CREDIT_REQUEST 7
  \end{lstlisting}
 
Quoted 7 lines

virtio-vsock.tex \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op · line 114

Quoted 5 lines
virtio-vsock.tex +5 -0
+\field{len} is the size of the payload, in bytes. However, the driver may
+provide buffer(s) for the payload that have a total size longer than
+\field{len}. If that is the case, only the first \field{len} bytes MUST be
+used for the actual data.
+

IIUC MUST and friends are for normative sections, so I would remove the last sentence.

Quoted 2 lines

You're right, I'll remove it. It should already be clear enough only the first len bytes need to be used for the payload.

Another option would be

"However, the driver may provide buffer(s) for the payload that have a total size longer than \field{len}, in which case only the first \field{len} bytes will be used for the actual data."

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/

#4 lore raw
Quoted 34 lines · Cornelia Huck

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you can confirm the sender and know the content is safe.

Quoted 28 lines · Laura Loghin
Quoted 27 lines · Stefano Garzarella

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you can confirm the sender and know the content is safe.

Hi Laura,

Quoted 10 lines · Laura Loghin
---
   virtio-vsock.tex | 5 +++++
   1 file changed, 5 insertions(+)
virtio-vsock.tex +0 -0
index d79984d..e32cad8 100644

virtio-vsock.tex \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op · line 114

Quoted 8 lines
virtio-vsock.tex +5 -0
@@ -107,6 +107,11 @@ \subsection{Device Operation}\label{sec:Device Types / Socket Device / Device Op
   #define VIRTIO_VSOCK_OP_CREDIT_REQUEST 7
   \end{lstlisting}
 
+\field{len} is the size of the payload, in bytes. However, the driver may
+provide buffer(s) for the payload that have a total size longer than
+\field{len}. If that is the case, only the first \field{len} bytes MUST be
+used for the actual data.
+

IIUC MUST and friends are for normative sections, so I would remove the last sentence.

Quoted 8 lines
Quoted 2 lines

You're right, I'll remove it. It should already be clear enough only the first len bytes need to be used for the payload.

Another option would be

"However, the driver may provide buffer(s) for the payload that have a total size longer than \field{len}, in which case only the first \field{len} bytes will be used for the actual data."

Sounds better, thanks for the suggestion! Just sent a new version.

Laura

Amazon Development Center (Romania) S.R.L. registered office: 27A Sf. Lazar Street, UBC5, floor 2, Iasi, Iasi County, 700045, Romania. Registered in Romania. Registration number J22/2621/2005.