[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [virtio-comment] [PATCH v2] introduction: document #define syntax
On Thu, 18 Mar 2021 14:23:33 -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> > --- > > 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. 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 > > \newpage >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]