packed ring layout spec

index ca6d2d9..4261913 100644
@@ -300,9 +300,9 @@ To help with these optimizations, when VIRTIO_F_NOTIFICATION_DATA
 has been negotiated, driver notifications to the device include
 the following information:
 
-\begin{itemize}
-\item VQ number
-\item Offset
+\begin{description}
+\item [VQ number]
+\item [Offset]
       Within the ring where the next available ring entry
       will be written.
       Without VIRTIO_F_RING_PACKED this refers to the

@@ -311,15 +311,16 @@ the following information:
       (in units of descritor entries)
       within the descriptor ring where the next available
       descriptor will be written.
-\item Wrap Counter
+\item [Wrap Counter]
       With VIRTIO_F_RING_PACKED this is the wrap counter
       referring to the next available descriptor.
       Without VIRTIO_F_RING_PACKED this is the most significant bit
       of the available index.
-\end{itemize}
+\end{description}
 
 Note that driver can trigger multiple notifications even without
-making any more changes to the ring. These would then have
+making any more changes to the ring. When VIRTIO_F_NOTIFICATION_DATA
+has been negotiated, these notifications would then have
 identical \field{Offset} and \field{Wrap Counter} values.
 
 \input{split-ring.tex}

@@ -1363,11 +1364,14 @@ When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
 the driver notifies the device by writing the following
 32-bit value to the Queue Notify address:
 \begin{lstlisting}
-__le16 vqn;
-__le16 next_off : 15;
-u8    next_wrap : 1;
+le32 vqn : 16,
+     next_off : 15,
+     next_wrap : 1;
 \end{lstlisting}
 
+See \ref{sec:Virtqueues / Driver notifications}~\nameref{sec:Virtqueues / Driver notifications}
+for the definition of the components.
+
 See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} for how to calculate the
 Queue Notify address.
 

@@ -1607,10 +1611,12 @@ All register values are organized as Little Endian.
     the value written is the queue index.
 
     When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
-    the value is calculated as follows:
-    $
-    u32 notification\_data = vqn | (next\_off << 16) | (next\_wrap << 31);
-    $
+    the value has the following format:
+
+    \lstinputlisting{notifications.c}
+
+    See \ref{sec:Virtqueues / Driver notifications}~\nameref{sec:Virtqueues / Driver notifications}
+    for the definition of the components.
   }
   \hline 
   \mmioreg{InterruptStatus}{Interrupt status}{0x60}{R}{%

@@ -2459,12 +2465,11 @@ When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
 the \field{Notification data} includes the Virtqueue number.
 
 When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
-the \field{Notification data} is calculated as follows:
-
-\begin{lstlisting}
-u32 notification_data = vqn | (next_off << 16) | (next_wrap << 31);
-\end{lstlisting}
+the value has the following format:
+\lstinputlisting{notifications.c}
 
+See \ref{sec:Virtqueues / Driver notifications}~\nameref{sec:Virtqueues / Driver notifications}
+for the definition of the components.
 
 \devicenormative{\paragraph}{Guest->Host Notification}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
 The device MUST ignore bits 0-31 (counting from the left) of GPR2.

index 979881e..d0b770e 100644
@@ -157,5 +157,23 @@ in little-endian byte order.
 in big-endian byte order.
 \end{description}
 
+When documenting sub-byte data fields, C-like bitfield notation
+is used. Fields within an integer are always listed in order,
+from the least significant to the most significant bit.
+
+For example:
+\begin{lstlisting}
+be16 A : 15,
+     B : 1;
+\end{lstlisting}
+documents the value A stored in the low 15 bit of a 16 bit
+integer and the value B stored in the high bit of the 16 bit
+integer, the integer in turn using the big-endian byte order.
+
+Note that this notation typically matches the way bitfields are
+packed by C compilers on little-endian architectures but not the
+way bitfields are packed by C compilers on big-endian
+architectures.
+
 \newpage
 

241 lines not on this page · raw message

index 5572958..df278fe 100644
@@ -23,7 +23,7 @@ Each virtqueue consists of three parts:
 where each part is physically-contiguous in guest memory,
 and has different alignment requirements.
 
-The memory aligment and size requirements, in bytes, of each part of the
+The memory alignment and size requirements, in bytes, of each part of the
 virtqueue are summarized in the following table:
 
 \begin{tabular}{|l|l|l|}