OASIS Virtual I/O Device (VIRTIO) TC

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: +egin{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. +
ewpage -- MST

On Wed, Feb 28, 2018 at 09:16:32PM +0200, Michael S. Tsirkin 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(+)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

On Wed, Feb 28, 2018 at 09:16:32PM +0200, Michael S. Tsirkin 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(+) Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Attachment: signature.asc Description: PGP signature

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.

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: > +egin{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. > + >
ewpage > 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.

On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote:
> 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.

What it is saying is that this is equivalent to

CPU_TO_BE16(B << 15 | A)

Maybe adding this part will clarify things?


> Would some kind
> of graphic representation be more helpful?

I'm not good at graphics :)

> 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.


It's BE so I think it's

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

On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote: > 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: > > +egin{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. > > + > >
ewpage > > > > I must admit that this explanation confuses me a bit. What it is saying is that this is equivalent to CPU_TO_BE16(B << 15 A) Maybe adding this part will clarify things? > Would some kind > of graphic representation be more helpful? I'm not good at graphics :) > 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. It's BE so I think it's 15 14 .. 0 B A

On Mon, 5 Mar 2018 16:26:11 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote:
> > 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.
>
> What it is saying is that this is equivalent to
>
> CPU_TO_BE16(B << 15 | A)
>
> Maybe adding this part will clarify things?
>
>
> > Would some kind
> > of graphic representation be more helpful?
>
> I'm not good at graphics :)

Me neither :) But pseudo-graphics might be enough.

>
> > 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.
>
>
> It's BE so I think it's
>
> | 15 |14 .. 0 |
> | B | A |
>

But that's the same, no? Or it's just IBM bitorder striking again...

On Mon, 5 Mar 2018 16:26:11 +0200 "Michael S. Tsirkin" <mst@redhat.com> wrote: > On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote: > > 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: > > > +egin{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. > > > + > > >
ewpage > > > > > > > I must admit that this explanation confuses me a bit. > > What it is saying is that this is equivalent to > > CPU_TO_BE16(B << 15 A) > > Maybe adding this part will clarify things? > > > > Would some kind > > of graphic representation be more helpful? > > I'm not good at graphics :) Me neither :) But pseudo-graphics might be enough. > > > 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. > > > It's BE so I think it's > > 15 14 .. 0 > B A > But that's the same, no? Or it's just IBM bitorder striking again...

On Mon, Mar 05, 2018 at 05:04:40PM +0100, Cornelia Huck wrote:
> On Mon, 5 Mar 2018 16:26:11 +0200
> "Michael S. Tsirkin" <mst@redhat.com> wrote:
>
> > On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote:
> > > 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.
> >
> > What it is saying is that this is equivalent to
> >
> > CPU_TO_BE16(B << 15 | A)
> >
> > Maybe adding this part will clarify things?
> >
> >
> > > Would some kind
> > > of graphic representation be more helpful?
> >
> > I'm not good at graphics :)
>
> Me neither :) But pseudo-graphics might be enough.
>
> >
> > > 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.
> >
> >
> > It's BE so I think it's
> >
> > | 15 |14 .. 0 |
> > | B | A |
> >
>
> But that's the same, no?

I just tried to show that B is in byte 0,
assuming bytes are numbered 0,1,2,3 left to right.

> Or it's just IBM bitorder striking again...

That's what I'm saying these graphics do not help at all.

It's an integer, B is the most significant bit. Integer is stored
in BE format, thus B is the MSB in the first byte.

Let me know whether writing
CPU_TO_BE16(B << 15 | A)

helps clarify things.

On Mon, Mar 05, 2018 at 05:04:40PM +0100, Cornelia Huck wrote: > On Mon, 5 Mar 2018 16:26:11 +0200 > "Michael S. Tsirkin" <mst@redhat.com> wrote: > > > On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote: > > > 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: > > > > +egin{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. > > > > + > > > >
ewpage > > > > > > > > > > I must admit that this explanation confuses me a bit. > > > > What it is saying is that this is equivalent to > > > > CPU_TO_BE16(B << 15 A) > > > > Maybe adding this part will clarify things? > > > > > > > Would some kind > > > of graphic representation be more helpful? > > > > I'm not good at graphics :) > > Me neither :) But pseudo-graphics might be enough. > > > > > > 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. > > > > > > It's BE so I think it's > > > > 15 14 .. 0 > > B A > > > > But that's the same, no? I just tried to show that B is in byte 0, assuming bytes are numbered 0,1,2,3 left to right. > Or it's just IBM bitorder striking again... That's what I'm saying these graphics do not help at all. It's an integer, B is the most significant bit. Integer is stored in BE format, thus B is the MSB in the first byte. Let me know whether writing CPU_TO_BE16(B << 15 A) helps clarify things.

On Mon, 5 Mar 2018 23:11:40 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Mon, Mar 05, 2018 at 05:04:40PM +0100, Cornelia Huck wrote:
> > On Mon, 5 Mar 2018 16:26:11 +0200
> > "Michael S. Tsirkin" <mst@redhat.com> wrote:
> >
> > > On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote:
> > > > 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.
> > >
> > > What it is saying is that this is equivalent to
> > >
> > > CPU_TO_BE16(B << 15 | A)
> > >
> > > Maybe adding this part will clarify things?
> > >
> > >
> > > > Would some kind
> > > > of graphic representation be more helpful?
> > >
> > > I'm not good at graphics :)
> >
> > Me neither :) But pseudo-graphics might be enough.
> >
> > >
> > > > 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.
> > >
> > >
> > > It's BE so I think it's
> > >
> > > | 15 |14 .. 0 |
> > > | B | A |
> > >
> >
> > But that's the same, no?
>
> I just tried to show that B is in byte 0,
> assuming bytes are numbered 0,1,2,3 left to right.
>
> > Or it's just IBM bitorder striking again...
>
> That's what I'm saying these graphics do not help at all.
>
> It's an integer, B is the most significant bit. Integer is stored
> in BE format, thus B is the MSB in the first byte.
>
> Let me know whether writing
> CPU_TO_BE16(B << 15 | A)
>
> helps clarify things.

I think so.

Let's go with that, then. I'm probably a bad measure since I've been
subjected to the IBM notation for a long time...

On Mon, 5 Mar 2018 23:11:40 +0200 "Michael S. Tsirkin" <mst@redhat.com> wrote: > On Mon, Mar 05, 2018 at 05:04:40PM +0100, Cornelia Huck wrote: > > On Mon, 5 Mar 2018 16:26:11 +0200 > > "Michael S. Tsirkin" <mst@redhat.com> wrote: > > > > > On Mon, Mar 05, 2018 at 03:20:35PM +0100, Cornelia Huck wrote: > > > > 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: > > > > > +egin{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. > > > > > + > > > > >
ewpage > > > > > > > > > > > > > I must admit that this explanation confuses me a bit. > > > > > > What it is saying is that this is equivalent to > > > > > > CPU_TO_BE16(B << 15 A) > > > > > > Maybe adding this part will clarify things? > > > > > > > > > > Would some kind > > > > of graphic representation be more helpful? > > > > > > I'm not good at graphics :) > > > > Me neither :) But pseudo-graphics might be enough. > > > > > > > > > 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. > > > > > > > > > It's BE so I think it's > > > > > > 15 14 .. 0 > > > B A > > > > > > > But that's the same, no? > > I just tried to show that B is in byte 0, > assuming bytes are numbered 0,1,2,3 left to right. > > > Or it's just IBM bitorder striking again... > > That's what I'm saying these graphics do not help at all. > > It's an integer, B is the most significant bit. Integer is stored > in BE format, thus B is the MSB in the first byte. > > Let me know whether writing > CPU_TO_BE16(B << 15 A) > > helps clarify things. I think so. Let's go with that, then. I'm probably a bad measure since I've been subjected to the IBM notation for a long time...