C struct specifications.

Explicitly specify that our C struct specifications are without padding,
and add some definitions for our integer data types.

[ Rusty - added /* comments */ and removed redundant old le* explanation ]

Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@212 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652

2 files changed, 35 insertions, 3 deletions

diff --git a/content.tex b/content.tex
index 2eb0b26..37850c8 100644
--- a/content.tex
+++ b/content.tex
@@ -12,9 +12,6 @@ device consists of the following parts:
 \item One or more virtqueues
 \end{itemize}
 
-Unless explicitly specified otherwise, all multi-byte fields are little-endian.
-To reinforce this the examples use typenames like "le16" instead of "uint16_t".
-
 \section{Device Status Field}\label{sec:Basic Facilities of a Virtio Device / Device Status Field}
 
 The driver MUST update the Device Status field in the order below to
@@ -349,6 +346,7 @@ Drivers MUST NOT add a descriptor chain over than $2^{32}$ bytes long in total;
 this implies that loops in the descriptor chain are forbidden!
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct vring_desc {
         /* Address (guest-physical). */
         le64 addr;
@@ -409,6 +407,7 @@ the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the de
 \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct vring_avail {
 #define VRING_AVAIL_F_NO_INTERRUPT      1
         le16 flags;
@@ -445,6 +444,7 @@ entirely.
 \subsection{The Virtqueue Used Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct vring_used {
 #define VRING_USED_F_NO_NOTIFY  1
         le16 flags;
@@ -453,6 +453,7 @@ struct vring_used {
         le16 avail_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
 };
 
+/* Note: LEGACY version was not little endian! */
 /* le32 is used here for ids for padding reasons. */
 struct vring_used_elem {
         /* Index of start of used descriptor chain. */
@@ -2452,6 +2453,7 @@ and transmitq0..transmitqN respectively;
 is negotiated.  Legal values for this field are 1 to 0x8000.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_net_config {
         u8 mac[6];
         le16 status;
@@ -2538,6 +2540,7 @@ placed in the receiveq0..receiveqN. In each case, the packet
 itself is preceeded by a header:
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_net_hdr {
 #define VIRTIO_NET_HDR_F_NEEDS_CSUM    1
         u8 flags;
@@ -2865,6 +2868,7 @@ queue incoming packets into one of the multiple receiveq0..receiveqN
 depending on the packet flow.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_net_ctrl_mq {
         le16 virtqueue_pairs;
 };
@@ -3001,6 +3005,7 @@ present. The availability of the others all depend on various feature
 bits as indicated above.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_blk_config {
         le64 capacity;
         le32 size_max;
@@ -3258,6 +3263,7 @@ data and outgoing characters are placed in the transmit queue.
   acknowledging the feature.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_console_config {
         le16 cols;
         le16 rows;
@@ -3335,6 +3341,7 @@ when a port is closed or hot-unplugged.
   buffer and the events associated are:
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_console_control {
         le32 id;    /* Port number */
         le16 event; /* The kind of control event */
@@ -3524,6 +3531,7 @@ as follows:
   compatibility, unsupported statistics should be omitted.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_balloon_stat {
 #define VIRTIO_BALLOON_S_SWAP_IN  0
 #define VIRTIO_BALLOON_S_SWAP_OUT 1
@@ -3615,6 +3623,7 @@ targets that receive and process the requests.
   and cdb_size are writable by the driver.
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_scsi_config {
         le32 num_queues;
         le32 seg_max;
@@ -3699,6 +3708,7 @@ consumed with no order constraints.
 Requests have the following format:
 
 \begin{lstlisting}
+/* Note: LEGACY version was not little endian! */
 struct virtio_scsi_req_cmd {
         // Read-only
         u8 lun[8];
@@ -3859,6 +3869,7 @@ The following commands are defined:
 #define VIRTIO_SCSI_T_TMF_QUERY_TASK           6
 #define VIRTIO_SCSI_T_TMF_QUERY_TASK_SET       7
 
+/* Note: LEGACY version was not little endian! */
 struct virtio_scsi_ctrl_tmf
 {
         // Read-only part
diff --git a/introduction.tex b/introduction.tex
index 5d57f78..83b01f0 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -44,5 +44,26 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 	\phantomsection\label{intro:S390 Common I/O}\textbf{[S390 Common I/O]} & ESA/390 Common I/O-Device and Self-Description, \newline IBM Publication SA22-7204\\
 \end{longtable}
 
+\section{Structure Specifications}
+
+Many device and driver in-memory structure layouts are documented using
+the C struct syntax. All structures are assumed to be without additional
+padding. To stress this, cases where common C compilers are known to insert
+extra padding within structures are tagged using the GNU C
+__attribute__((packed))  syntax.
+
+For the integer data types used in the structure definitions, the following
+conventions are used:
+
+\begin{description}
+\item[u8, u16, u32, u64] An unsigned integer of the specified length in bits.
+
+\item[le16, le32, le64] An unsigned integer of the specified length in bits,
+in little-endian byte order.
+
+\item[be16, be32, be64] An unsigned integer of the specified length in bits,
+in big-endian byte order.
+\end{description}
+
 \newpage