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

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

[Michael S. Tsirkin]

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

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 introduction.tex | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/introduction.tex b/introduction.tex
index cc38e29..4febed2 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -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
 
-- 
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 

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

[Cornelia Huck]

On Tue, 16 Mar 2021 17:13:17 -0400
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> We use the C #define syntax to refer to numeric values.
> Let's document that.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  introduction.tex | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/introduction.tex b/introduction.tex
> index cc38e29..4febed2 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -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/

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

Doesn't that really document that Value A *is* 1? I'm a bit confused by
that sentence.

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


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

[virtio] Re: [virtio-dev] [PATCH] introduction: document #define syntax

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1356 bytes --]

On Tue, Mar 16, 2021 at 05:13:17PM -0400, Michael S. Tsirkin wrote:
> We use the C #define syntax to refer to numeric values.
> Let's document that.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  introduction.tex | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/introduction.tex b/introduction.tex
> index cc38e29..4febed2 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[virtio-comment] Re: [virtio-dev] [PATCH] introduction: document #define syntax

[Eugenio Perez Martin]

On Tue, Mar 16, 2021 at 10:13 PM Michael S. Tsirkin <mst@redhat.com> wrote:
>
> We use the C #define syntax to refer to numeric values.
> Let's document that.
>
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  introduction.tex | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
>
> diff --git a/introduction.tex b/introduction.tex
> index cc38e29..4febed2 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -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.

I'm not sure if somebody can be confused about this, but maybe
s/shift-left operation/shift-left bitwise operation/ is more clear?

> +
> +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
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>


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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

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

[Michael S. Tsirkin]

On Wed, Mar 17, 2021 at 09:43:34AM +0100, Cornelia Huck wrote:
> On Tue, 16 Mar 2021 17:13:17 -0400
> "Michael S. Tsirkin" <mst@redhat.com> wrote:
> 
> > We use the C #define syntax to refer to numeric values.
> > Let's document that.
> > 
> > Signed-off-by: Michael S. Tsirkin <mst@redhat.com>

thanks for the comments, tried to clarify in v2.

> > ---
> >  introduction.tex | 21 +++++++++++++++++++++
> >  1 file changed, 21 insertions(+)
> > 
> > diff --git a/introduction.tex b/introduction.tex
> > index cc38e29..4febed2 100644
> > --- a/introduction.tex
> > +++ b/introduction.tex
> > @@ -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/
> 
> > +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.  
> 
> 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.

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


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