[PATCH 1/1] Clarify padding in structures

[Cornelia Huck <cornelia.huck@de.ibm.com>]

Explicitly specify that our C struct specifications are without padding,
and add some definitions for our integer data types. Also note what the
__packed__ annotation signifies.

Remove __packed__ annotation from all ccw structures that don't need it,
and make the length requirements explicit for those that do.

This resolves VIRTIO-56.

Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>
---
 content.tex      |   14 +++++++++-----
 introduction.tex |   21 +++++++++++++++++++++
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/content.tex b/content.tex
index e8a2445..a3e8188 100644
--- a/content.tex
+++ b/content.tex
@@ -1994,7 +1994,7 @@ about a queue. It uses the following structure for communicating:
 	struct vq_config_block {
 		be16 index;
 		be16 max_num;
-	} __attribute__ ((packed));
+	};
 \end{lstlisting}
 
 The requested number of buffers for queue index is returned in
@@ -2012,7 +2012,7 @@ structure is
 		be16 num;
 		be64 avail;
 		be64 used;
-	} __attribute__ ((packed));
+	};
 \end{lstlisting}
 
 desc, avail and used contain the guest addresses for the descriptor table,
@@ -2031,7 +2031,7 @@ CCW_CMD_SET_VQ uses the following communication block:
 		be32 align;
 		be16 index;
 		be16 num;
-	} __attribute__ ((packed));
+	};
 \end{lstlisting}
 
 queue contains the guest address for queue index, num the number of buffers
@@ -2079,12 +2079,13 @@ communication block:
 	struct virtio_feature_desc {
 		le32 features;
 		u8 index;
-	} __attribute__ ((packed));
+	} __attribute__((packed));
 \end{lstlisting}
 
 features are the 32 bits of features currently accessed, while
 index describes which of the feature bit values is to be
-accessed.
+accessed. No padding is added at the end of the structure, it is
+exactly 5 bytes in length.
 
 The guest obtains the device's device feature set via the
 CCW_CMD_READ_FEAT command. The device stores the features at index
@@ -2181,6 +2182,9 @@ significant bit in the first byte is assigned the bit number 0.
 isc contains the I/O interruption subclass to be used for the adapter
 I/O interrupt. It may be different from the isc used by the proxy
 virtio-ccw device's subchannel.
+No padding is added at the end of the structure, it is exactly 25 bytes
+in length.
+
 
 If the driver has already set up classic queue indicators via the
 CCW_CMD_SET_IND command, the device MUST post a unit check with
diff --git a/introduction.tex b/introduction.tex
index 5d57f78..2830f30 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 unsigend 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
 
-- 
1.7.9.5