On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <m...@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 <m...@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. --------------------------------------------------------------------- To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org