Re: [PATCH] introduction: document bitfield notation

[Cornelia Huck <cohuck@redhat.com>]

On Wed, 28 Feb 2018 21:16:32 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Bitfields are a useful and familiar way to specify sub-byte structure
> layout. The only issue is that bitfield order isn't portable across
> architectures.  Document that we list bitfields from least to
> most significant one, and warn about portability issues.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  introduction.tex | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/introduction.tex b/introduction.tex
> index 979881e..3cb7a70 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -157,5 +157,23 @@ in little-endian byte order.
>  in big-endian byte order.
>  \end{description}
>  
> +When documenting sub-byte data fields, C-like bitfield notation
> +is used. Fields within an integer are always listed in order,
> +from the least significant to the most significant bit.
> +
> +For example:
> +\begin{lstlisting}
> +be16 A : 15;
> +be16 B : 1;
> +\end{lstlisting}
> +documents the value A stored in the low 15 bit of a 16 bit
> +integer and the value B stored in the high bit of the 16 bit
> +integer, the integer in turn using the big-endian byte order.
> +
> +Note that this notation typically matches the way bitfields are
> +packed by C compilers on little-endian architectures but not the
> +way bitfields are packed by C compilers on big-endian
> +architectures.
> +
>  \newpage
>  

I must admit that this explanation confuses me a bit. Would some kind
of graphic representation be more helpful?

For example, on s390 I would expect the structure to look like the
following:

|0  ..  14 | 15 |
|    A     |  B |

If you included another example for little-endian byte order, this
would clear up things more, I think.