summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--introduction.tex41
1 files changed, 41 insertions, 0 deletions
diff --git a/introduction.tex b/introduction.tex
index 979881e..a4ac01d 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -157,5 +157,46 @@ in little-endian byte order.
in big-endian byte order.
\end{description}
+Some of the fields to be defined in this specification don't
+start or don't end on a byte boundary. Such fields are called bit-fields.
+A set of bit-fields is always a sub-division of an integer typed field.
+
+Bit-fields within integer fields are always listed in order,
+from the least significant to the most significant bit. The
+bit-fields are considered unsigned integers of the specified
+width with the next in significance relationship of the bits
+preserved.
+
+For example:
+\begin{lstlisting}
+struct S {
+ be16 {
+ A : 15;
+ B : 1;
+ } x;
+ be16 y;
+};
+\end{lstlisting}
+documents the value A stored in the low 15 bit of \field{x} and
+the value B stored in the high bit of \field{x}, the 16-bit
+integer \field{x} in turn stored using the big-endian byte order
+at the beginning of the structure S,
+and being followed immediately by an unsigned integer \field{y}
+stored in big-endian byte order at an offset of 2 bytes (16 bits)
+from the beginning of the structure.
+
+Note that this notation somewhat resembles the C bitfield syntax but
+should not be naively converted to a bitfield notation for portable
+code: it 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.
+
+Assuming that CPU_TO_BE16 converts a 16-bit integer from a native
+CPU to the big-endian byte order, the following is the equivalent
+portable C code to generate a value to be stored into \field{x}:
+\begin{lstlisting}
+CPU_TO_BE16(B << 15 | A)
+\end{lstlisting}
+
\newpage