On Thu, 18 Mar 2021 14:23:33 -0400
"Michael S. Tsirkin" <m...@redhat.com> wrote:
> We use the C #define syntax to refer to numeric values.
> Let's document that.
>
> Signed-off-by: Michael S. Tsirkin <m...@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}.
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.
> +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
>
Reviewed-by: Cornelia Huck <coh...@redhat.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org
