introduction: document #define syntax
PATCH 1/1 introduction: document #define syntax
We use the C #define syntax to refer to numeric values. Let's document that.
--- introduction.tex | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
introduction.tex +21 -0
@@ -210,6 +210,27 @@ \section{Structure Specifications} \begin{lstlisting} CPU_TO_BE16(B << 15 | A) \end{lstlisting} +\section{Constant Specifications} + +In many cases, numberic 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} +/* Value A description */ +#define VIRTIO_VALUE_A (1 << 0) +/* Value B description */ +#define VIRTIO_VALUE_B (1 << 1) +\end{lstlisting} +documents two numeric values: 1 meaning Value A and 2 meaning +Value B. Note that $<<$ refers to the shift-left operation. + +Further, in this case VIRTIO_VALUE_A and VIRTIO_VALUE_B +refer to 1 and 2 respectively. Further, VIRTIO_VALUE_XXX refers to +either VIRTIO_VALUE_A or VIRTIO_VALUE_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 13 lines · On Tue, 16 Mar 2021 17:13:17 -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]>--- introduction.tex | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)introduction.tex +0
-0
introduction.tex \section{Structure Specifications} · line 215
Quoted 6 lines
introduction.tex +3
-0@@ -210,6 +210,27 @@ \section{Structure Specifications} \begin{lstlisting} CPU_TO_BE16(B << 15 | A) \end{lstlisting} +\section{Constant Specifications} + +In many cases, numberic values used in the interface between the device
s/numberic/numeric/
Quoted 4 lines
introduction.tex +4
-0+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.
introduction.tex \section{Structure Specifications}
Quoted 10 lines
introduction.tex +10
-0+For example: + +\begin{lstlisting} +/* Value A description */ +#define VIRTIO_VALUE_A (1 << 0) +/* Value B description */ +#define VIRTIO_VALUE_B (1 << 1) +\end{lstlisting} +documents two numeric values: 1 meaning Value A and 2 meaning +Value B.
Doesn't that really document that Value A *is* 1? I'm a bit confused by that sentence.
introduction.tex \section{Structure Specifications} · line 235
Quoted 8 lines
Note that $<<$ refers to the shift-left operation.
introduction.tex +4
-0+ +Further, in this case VIRTIO_VALUE_A and VIRTIO_VALUE_B +refer to 1 and 2 respectively. Further, VIRTIO_VALUE_XXX refers to +either VIRTIO_VALUE_A or VIRTIO_VALUE_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 7 lines · Cornelia Huck
Quoted 4 lines · On Tue, 16 Mar 2021 17:13:17 -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]>
thanks for the comments, tried to clarify in v2.
Quoted 27 lines
Quoted 9 lines
--- introduction.tex | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)introduction.tex +0
-0introduction.tex \section{Structure Specifications} · line 215
Quoted 6 lines
introduction.tex +3
-0@@ -210,6 +210,27 @@ \section{Structure Specifications} \begin{lstlisting} CPU_TO_BE16(B << 15 | A) \end{lstlisting} +\section{Constant Specifications} + +In many cases, numberic values used in the interface between the devices/numberic/numeric/
Quoted 9 lines
introduction.tex +9
-0+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} +/* Value A description */ +#define VIRTIO_VALUE_A (1 << 0)
Quoted 8 lines
introduction.tex \section{Structure Specifications}
Quoted 5 lines
introduction.tex +5
-0+/* Value B description */ +#define VIRTIO_VALUE_B (1 << 1) +\end{lstlisting} +documents two numeric values: 1 meaning Value A and 2 meaning +Value B.Doesn't that really document that Value A *is* 1? I'm a bit confused by that sentence.
The interface only includes numeric values. The numbers are interpreted by the devices and the drivers to refer to e.g. A or B.
Quoted 8 lines
introduction.tex \section{Structure Specifications} · line 235
Quoted 8 lines
Note that $<<$ refers to the shift-left operation.
introduction.tex +4
-0+ +Further, in this case VIRTIO_VALUE_A and VIRTIO_VALUE_B +refer to 1 and 2 respectively. Further, VIRTIO_VALUE_XXX refers to +either VIRTIO_VALUE_A or VIRTIO_VALUE_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 13 lines · Michael S. Tsirkin
We use the C #define syntax to refer to numeric values. Let's document that.
Signed-off-by Michael S. Tsirkin <[email protected]>--- introduction.tex | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)introduction.tex +0
-0
introduction.tex \section{Structure Specifications} · line 219
Quoted 10 lines
introduction.tex +7
-0@@ -210,6 +210,27 @@ \section{Structure Specifications} \begin{lstlisting} CPU_TO_BE16(B << 15 | A) \end{lstlisting} +\section{Constant Specifications} + +In many cases, numberic 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.
This sentence confused me. It's not talking about C #define syntax. It's a convention for referring to the #defines in the spec text.
This could be clarified:
Multiple constants with the same prefix are referred to in the text using a _XXX a suffix as a shorthand for all constants that share the prefix.
I suggest moving this down to the bottom where the VIRTIO_VALUE_XXX example is given.
Quoted 24 lines · Michael S. Tsirkin
We use the C #define syntax to refer to numeric values. Let's document that.
Signed-off-by Michael S. Tsirkin <[email protected]>--- introduction.tex | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)introduction.tex +7
-0@@ -210,6 +210,27 @@ \section{Structure Specifications} \begin{lstlisting} CPU_TO_BE16(B << 15 | A) \end{lstlisting} +\section{Constant Specifications} + +In many cases, numberic 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.
introduction.tex \section{Structure Specifications} · line 229
Quoted 10 lines
introduction.tex +10
-0+For example: + +\begin{lstlisting} +/* Value A description */ +#define VIRTIO_VALUE_A (1 << 0) +/* Value B description */ +#define VIRTIO_VALUE_B (1 << 1) +\end{lstlisting} +documents two numeric values: 1 meaning Value A and 2 meaning +Value B. Note that $<<$ refers to the shift-left operation.
I'm not sure if somebody can be confused about this, but maybe s/shift-left operation/shift-left bitwise operation/ is more clear?
Quoted 11 lines
introduction.tex +4
-1+ +Further, in this case VIRTIO_VALUE_A and VIRTIO_VALUE_B +refer to 1 and 2 respectively. Further, VIRTIO_VALUE_XXX refers to +either VIRTIO_VALUE_A or VIRTIO_VALUE_B. \newpage --MST
Quoted 4 lines
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/