[PATCH 1/1] ccw: ccw payload description

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

Move the ccw payload description to tables, instead of using
C structures with gcc extensions or textual descriptions.

Reported-by: Thomas Huth <thuth@linux.vnet.ibm.com>
Suggested-by: Thomas Huth <thuth@linux.vnet.ibm.com>
Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com>
---
 content.tex |  178 ++++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 114 insertions(+), 64 deletions(-)

diff --git a/content.tex b/content.tex
index 7091bf4..efc8035 100644
--- a/content.tex
+++ b/content.tex
@@ -1830,8 +1830,8 @@ virtio support is mainly a question of supporting a new control
 unit type.
 
 As the S/390 is a big endian machine, the data structures transmitted
-via channel commands are big-endian: this is made clear by use of
-the types be16, be32 and be64.
+via channel commands are big-endian in the general case; deviations
+are marked.
 
 \subsection{Basic Concepts}\label{sec:Virtio Transport Options / Virtio over channel I/O / Basic Concepts}
 
@@ -1916,16 +1916,17 @@ CCW_CMD_SET_VIRTIO_REV is issued by the driver to set the revision of
 the virtio-ccw transport it intends to drive the device with. It uses the
 following communication structure:
 
-\begin{lstlisting}
-	struct virtio_rev_info {
-	       __u16 revision;
-	       __u16 length;
-	       __u8 data[];
-	};
-\end{lstlisting}
-
-revision contains the desired revision id, length the length of the
-data portion and data revision-dependent additional desired options.
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 2 & big & revision & desired revision id \\
+\hline
+2 & 2 & big & length & length of data portion \\
+\hline
+4 & <length> & big & data & revision-dependent additional desired options \\
+\hline
+\end{tabular}
 
 The following values are supported:
 
@@ -1988,12 +1989,15 @@ implies that the device MUST reject any command not valid for revision
 CCW_CMD_READ_VQ_CONF is issued by the driver to obtain information
 about a queue. It uses the following structure for communicating:
 
-\begin{lstlisting}
-	struct vq_config_block {
-		be16 index;
-		be16 max_num;
-	} __attribute__ ((packed));
-\end{lstlisting}
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 2 & big & index & queue index for which the configuration is requested \\
+\hline
+2 & 4 & big & max_num & number of buffers for queue \\
+\hline
+\end{tabular}
 
 The requested number of buffers for queue index is returned in
 max_num.
@@ -2002,16 +2006,23 @@ Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the
 device about the location used for its queue. The transmitted
 structure is
 
-\begin{lstlisting}
-	struct vq_info_block {
-		be64 desc;
-		be32 res0;
-		be16 index;
-		be16 num;
-		be64 avail;
-		be64 used;
-	} __attribute__ ((packed));
-\end{lstlisting}
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 8 & big & desc & guest address for descriptor table \\
+\hline
+8 & 4 & n/a & res0 & reserved \\
+\hline
+12 & 2 & big & index & queue index information is set for \\
+\hline
+14 & 2 & big & num & number of allocated virtqueue buffers \\
+\hline
+16 & 8 & big & avail & guest address for available ring \\
+\hline
+24 & 8 & big & used & guest address for used ring \\
+\hline
+\end{tabular}
 
 desc, avail and used contain the guest addresses for the descriptor table,
 available ring and used ring for queue index, respectively. The actual
@@ -2023,17 +2034,19 @@ res0 is reserved and MUST be ignored by the device.
 For a legacy driver or for a driver that selected revision 0,
 CCW_CMD_SET_VQ uses the following communication block:
 
-\begin{lstlisting}
-	struct vq_info_block_legacy {
-		be64 queue;
-		be32 align;
-		be16 index;
-		be16 num;
-	} __attribute__ ((packed));
-\end{lstlisting}
-
-queue contains the guest address for queue index, num the number of buffers
-and align the alignment.
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 8 & big & queue & guest address for virtqueue \\
+\hline
+8 & 4 & big & align & alignment of virtqueue \\
+\hline
+12 & 2 & big & index & queue index information is set for \\
+\hline
+14 & 2 & big & num & number of allocated virtqueue buffers \\
+\hline
+\end{tabular}
 
 \subsubsection{Virtqueue Layout}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Virtqueue Layout}
 
@@ -2062,8 +2075,15 @@ The calculation for total size is as follows:
 
 The driver changes the status of a device via the
 CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status
-value.
+value:
 
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 1 & n/a & status & device status \\
+\hline
+\end{tabular}
 \subsubsection{Handling Device Features}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Handling Device Features}
 
 Feature bits are arranged in an array of 32 bit values, making
@@ -2073,16 +2093,15 @@ little-endian byte order.
 The CCW commands dealing with features use the following
 communication block:
 
-\begin{lstlisting}
-	struct virtio_feature_desc {
-		le32 features;
-		u8 index;
-	} __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.
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 4 & little & features & 32 bit value of features accessed \\
+\hline
+4 & 1 & n/a & index & index of the 32 bit value \\
+\hline
+\end{tabular}
 
 The guest obtains the device's device feature set via the
 CCW_CMD_READ_FEAT command. The device stores the features at index
@@ -2097,6 +2116,17 @@ combination.
 The device's configuration space is located in host memory. It is
 the same size as the standard PCI configuration space.
 
+The configuration-related CCW commands use the following communication
+area:
+
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & config space size & big & config & configuration space \\
+\hline
+\end{tabular}
+
 To obtain information from the configuration space, the driver
 uses CCW_CMD_READ_CONF, specifying the guest memory for the device
 to write to.
@@ -2128,9 +2158,16 @@ Indicators for notification via classic I/O interrupts are contained
 in a 64 bit value per virtio-ccw proxy device.
 
 To communicate the location of the indicator bits for host->guest
-notification, the driver uses the CCW_CMD_SET_IND command,
-pointing to a location containing the guest address of the
-indicators in a 64 bit value.
+notification, the driver uses the CCW_CMD_SET_IND command with the
+following communication block:
+
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 8 & big & indicators & guest address of indicators \\
+\hline
+\end{tabular}
 
 If the driver has already set up two-staged queue indicators via the
 CCW_CMD_SET_IND_ADAPTER command, the device MUST post a unit check
@@ -2143,8 +2180,15 @@ contained in a 64 bit value per virtio-ccw proxy device.
 
 To communicate the location of the indicator bits used in the
 configuration change host->guest notification, the driver issues the
-CCW_CMD_SET_CONF_IND command, pointing to a location containing the
-guest address of the indicators in a 64 bit value.
+CCW_CMD_SET_CONF_IND command with the following communication block:
+
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 8 & big & indicators & guest address of indicators \\
+\hline
+\end{tabular}
 
 \paragraph{Setting Up Two-Stage Queue Indicators}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Setting Up Indicators / Setting Up Two-Stage Queue Indicators}
 
@@ -2161,14 +2205,19 @@ To communicate the location of the summary and queue indicator bits,
 the driver uses the CCW_CMD_SET_IND_ADAPTER command with the following
 payload:
 
-\begin{lstlisting}
-	struct virtio_thinint_area {
-	       be64 summary_indicator;
-	       be64 indicator;
-	       be64 bit_nr;
-	       u8 isc;
-	} __attribute__ ((packed));
-\end{lstlisting}
+\begin{tabular}{ |l|l|l|l|l| }
+\hline
+Offset & Length & Endianness & Name & Description \\
+\hline \hline
+0 & 8 & big & summary_indicator & guest address of summary indicator \\
+\hline
+8 & 8 & big & indicator & guest address of indicator area \\
+\hline
+16 & 8 & big & bit_nr & index of indicator bit for first queue \\
+\hline
+24 & 1 & n/a & isc & I/O interruption subclass \\
+\hline
+\end{tabular}
 
 summary_indicator contains the guest address of the 8 bit summary
 indicator.
@@ -2281,8 +2330,9 @@ used.
 \subsubsection{Resetting Devices}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Operation / Resetting Devices}
 
 In order to reset a device, a driver sends the
-CCW_CMD_VDEV_RESET command.
+CCW_CMD_VDEV_RESET command. It takes no payload.
 
+If the driver transmits a payload, it MUST be ignored by the device.
 
 \chapter{Device Types}\label{sec:Device Types}
 
-- 
1.7.9.5