introduction: document bitfield notation
PATCH 1/1 introduction: document bitfield notation
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.
--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)
introduction.tex +18 -0
@@ -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
Signature · 6 lines
MST --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
Quoted 9 lines · Michael S. Tsirkin
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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)
Quoted 28 lines · On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <[email protected]> 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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)introduction.tex +10
-0@@ -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
introduction.tex in little-endian byte order. · line 179
Quoted 10 lines
introduction.tex +8
-0+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 from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
Quoted 35 lines · Cornelia Huck
Quoted 32 lines · On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <[email protected]> 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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)introduction.tex +14
-0@@ -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
Quoted 8 lines
introduction.tex in little-endian byte order. · line 179
Quoted 6 lines
introduction.tex +4
-0+packed by C compilers on little-endian architectures but not the +way bitfields are packed by C compilers on big-endian +architectures. + \newpageI 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?
Quoted 2 lines
Would some kind
of graphic representation be more helpful?
I'm not good at graphics :)
Quoted 8 lines
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 |
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
Quoted 49 lines · On Mon, 5 Mar 2018 16:26:11 +0200 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 35 lines · Cornelia Huck
Quoted 32 lines · On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <[email protected]> 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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)introduction.tex +14
-0@@ -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 areQuoted 8 lines
introduction.tex in little-endian byte order. · line 179
Quoted 6 lines
introduction.tex +4
-0+packed by C compilers on little-endian architectures but not the +way bitfields are packed by C compilers on big-endian +architectures. + \newpageI 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)
Quoted 7 lines
Maybe adding this part will clarify things?
Quoted 2 lines
Would some kind
of graphic representation be more helpful?I'm not good at graphics :)
Me neither :) But pseudo-graphics might be enough.
Quoted 7 lines
Quoted 7 lines
For example, on s390 I would expect the structure to look like the following:
|0 .. 14 | 15 | | A | B |
Quoted 9 lines
Quoted 2 lines
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...
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
Quoted 73 lines · Cornelia Huck
Quoted 49 lines · On Mon, 5 Mar 2018 16:26:11 +0200 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 35 lines · Cornelia Huck
Quoted 32 lines · On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <[email protected]> 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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)introduction.tex +14
-0@@ -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 areQuoted 8 lines
introduction.tex in little-endian byte order. · line 179
Quoted 6 lines
introduction.tex +4
-0+packed by C compilers on little-endian architectures but not the +way bitfields are packed by C compilers on big-endian +architectures. + \newpageI 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)Quoted 7 lines
Maybe adding this part will clarify things?
Quoted 2 lines
Would some kind
of graphic representation be more helpful?I'm not good at graphics :)
Me neither :) But pseudo-graphics might be enough.
Quoted 11 lines
Quoted 9 lines
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.
Quoted 7 lines
Quoted 5 lines
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.
Quoted 1 line
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 writingCPU_TO_BE16(B << 15 | A)
helps clarify things.
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
Quoted 89 lines · On Mon, 5 Mar 2018 23:11:40 +0200 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 73 lines · Cornelia Huck
Quoted 49 lines · On Mon, 5 Mar 2018 16:26:11 +0200 "Michael S. Tsirkin" <[email protected]> wrote:
Quoted 35 lines · Cornelia Huck
Quoted 32 lines · On Wed, 28 Feb 2018 21:16:32 +0200 "Michael S. Tsirkin" <[email protected]> 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 <[email protected]>--- introduction.tex | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+)introduction.tex +14
-0@@ -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 areQuoted 8 lines
introduction.tex in little-endian byte order. · line 179
Quoted 6 lines
introduction.tex +4
-0+packed by C compilers on little-endian architectures but not the +way bitfields are packed by C compilers on big-endian +architectures. + \newpageI 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)Quoted 7 lines
Maybe adding this part will clarify things?
Quoted 2 lines
Would some kind
of graphic representation be more helpful?I'm not good at graphics :)
Me neither :) But pseudo-graphics might be enough.
Quoted 11 lines
Quoted 9 lines
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.
Quoted 7 lines
Quoted 5 lines
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.
Quoted 1 line
Or it's just IBM bitorder striking again...
That's what I'm saying these graphics do not help at all.
Quoted 7 lines
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...
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php