Skip to contentSkip to conversation

introduction: document #define syntax

PATCH In review Michael S. Tsirkin 3 participants 4 messages Mar 18, 2021 – Apr 21, 2021

lore
Share & tools
lore

Michael S. Tsirkin

author
#0 lore raw

PATCH v2 1/1 introduction: document #define syntax

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

Signed-off-by Michael S. Tsirkin <[email protected]>

---

changes from v1:
address Cornelia's comments

 introduction.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
introduction.tex +23 -0
index cc38e29..47bebf5 100644
@@ -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
Signature · 7 lines
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
Reviewed-by on v2 1/1
#1 lore raw
Quoted 29 lines · On Thu, 18 Mar 2021 14:23:33 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

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

Signed-off-by Michael S. Tsirkin <[email protected]>

---

changes from v1:
address Cornelia's comments

 introduction.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
introduction.tex +8 -0
index cc38e29..47bebf5 100644
@@ -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:

introduction.tex \section{Structure Specifications} · line 230

Quoted 10 lines
introduction.tex +10 -0
+
+\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}.

The reader may infer a general Fld <-> FLD matching requirement here; but OTOH, this is only an example. I don't have an idea how to make that more explicit without being overly verbose, anyway.

introduction.tex \section{Structure Specifications} · line 238

Quoted 8 lines
introduction.tex +5 -0
+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
Reviewed-by Cornelia Huck <[email protected]>

---------------------------------------------------------------------
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

#2 lore raw
In reply to Michael S. Tsirkin
Quoted 34 lines · On Thu, 18 Mar 2021 14:23:33 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

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

Signed-off-by Michael S. Tsirkin <[email protected]>

---

changes from v1:
address Cornelia's comments

 introduction.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
introduction.tex +13 -0
index cc38e29..47bebf5 100644
@@ -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 */

introduction.tex \section{Structure Specifications} · line 235

Quoted 10 lines
introduction.tex +10 -0
+#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.

IMHO we also use the define stuff to do flags, and that does not match nicely with the above sentence, since VIRTIO_FLD_F_A does not mean that the FLD_F field has value A if we are trying to specify a flag or a feature bit. And the left-shift is actually most common in these cases.

I'm not opposed to this change. In the virtio spec we tend to not be very rigorous about formalism, and I came to accept that as a given. Just wanted to point it out.

Sorry for not commenting on this sooner.

Regards,
Halil

introduction.tex \section{Structure Specifications} · line 238

Quoted 3 lines
introduction.tex +0 -0
 \newpage

---------------------------------------------------------------------
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

author
#3 lore raw
Quoted 53 lines · Halil Pasic
Quoted 34 lines · On Thu, 18 Mar 2021 14:23:33 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

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

Signed-off-by Michael S. Tsirkin <[email protected]>

---

changes from v1:
address Cornelia's comments

 introduction.tex | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
introduction.tex +13 -0
index cc38e29..47bebf5 100644
@@ -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 */

introduction.tex \section{Structure Specifications} · line 235

Quoted 10 lines
introduction.tex +10 -0
+#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.

IMHO we also use the define stuff to do flags, and that does not match nicely with the above sentence, since VIRTIO_FLD_F_A does not mean that the FLD_F field has value A if we are trying to specify a flag or a feature bit. And the left-shift is actually most common in these cases.

Quoted 8 lines

I'm not opposed to this change. In the virtio spec we tend to not be very rigorous about formalism, and I came to accept that as a given. Just wanted to point it out.

Sorry for not commenting on this sooner.

Regards,
Halil

All true. Do you want to propose an enhancement, or just let it be for now?

Quoted 9 lines

introduction.tex \section{Structure Specifications} · line 238

Quoted 3 lines
introduction.tex +0 -0
 \newpage

---------------------------------------------------------------------
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

---------------------------------------------------------------------
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