introduction: document #define syntax
PATCH v2 1/1 introduction: document #define syntax
We use the C #define syntax to refer to numeric values. Let's document that.
---
changes from v1:
address Cornelia's comments
introduction.tex | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
introduction.tex +23 -0
@@ -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
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 commentsintroduction.tex | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)introduction.tex +8
-0@@ -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
---------------------------------------------------------------------
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
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 commentsintroduction.tex | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)introduction.tex +13
-0@@ -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
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 commentsintroduction.tex | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)introduction.tex +13
-0@@ -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_Adoes not mean that theFLD_Ffield 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