Skip to contentSkip to conversation

introduction: document bitfield notation

PATCH In review Michael S. Tsirkin 3 participants 7 messages Feb 28, 2018 – Mar 6, 2018

lore
Share & tools
lore
#0 lore raw

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
index 979881e..3cb7a70 100644
@@ -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 
Reviewed-by on v1 1/1
#1 lore raw
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
#2 lore raw
In reply to Michael S. Tsirkin
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
introduction.tex +10 -0
index 979881e..3cb7a70 100644
@@ -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

#3 lore raw
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
introduction.tex +14 -0
index 979881e..3cb7a70 100644
@@ -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.
+
 \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?

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

#4 lore raw
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
introduction.tex +14 -0
index 979881e..3cb7a70 100644
@@ -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.
+
 \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)

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

#5 lore raw
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
introduction.tex +14 -0
index 979881e..3cb7a70 100644
@@ -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.
+
 \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)

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 writing
CPU_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

#6 lore raw
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.

---
 introduction.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
introduction.tex +14 -0
index 979881e..3cb7a70 100644
@@ -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.
+
 \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)

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