[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [virtio] [PATCH] introduction: document #define syntax
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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]