We use the C #define syntax to refer to numeric values. Let's document that.
Signed-off-by: Michael S. Tsirkin <[email protected]> --- 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. \newpage -- MST --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
