[virtio] [PATCH v2] introduction: document #define syntax

["Michael S. Tsirkin" <mst@redhat.com>]

We use the C #define syntax to refer to numeric values.
Let's document that.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---

changes from v1:
address Cornelia's comments


 introduction.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/introduction.tex b/introduction.tex
index cc38e29..47bebf5 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -210,6 +210,29 @@ \section{Structure Specifications}
 \begin{lstlisting}
 CPU_TO_BE16(B << 15 | A)
 \end{lstlisting}
+\section{Constant Specifications}
+
+In many cases, numeric values used in the interface between the device
+and the driver are documented using the C #define and /* */
+comment syntax. Multiple related values are grouped together with
+a common name as a prefix, using _ as a separator.
+Using _XXX as a suffix refers to all values in a group.
+For example:
+
+\begin{lstlisting}
+/* Field Fld value A description */
+#define VIRTIO_FLD_A        (1 << 0)
+/* Field Fld value B description */
+#define VIRTIO_FLD_B        (1 << 1)
+\end{lstlisting}
+documents two numeric values for a field \field{Fld}, with
+\field{Fld} having value 1 referring to \field{A} and \field{Fld}
+having value 2 referring to \field{B}.
+Note that $<<$ refers to the shift-left operation.
+
+Further, in this case VIRTIO_FLD_A and VIRTIO_FLD_B
+refer to values 1 and 2 of Fld respectively. Further, VIRTIO_FLD_XXX refers to
+either VIRTIO_FLD_A or VIRTIO_FLD_B.
 
 \newpage
 
-- 
MST


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php