utils/bits.h: Support compiler magic for unaligned loads and stores.

[mLib] / utils / bits.3

diff --git a/utils/bits.3 b/utils/bits.3
index 7eb1e2b..a002e24 100644 (file)
--- a/utils/bits.3
+++ b/utils/bits.3
@@ -95,6 +95,28 @@ bits \- portable bit manipulation macros
 .\" @ROL64_
 .\" @ROR64_
 .\"
+.\" ENDSWAP16
+.\" ENDSWAP32
+.\" ENDSWAP64
+.\"
+.\" BTOH16
+.\" LTOH16
+.\" HTOB16
+.\" HTOL16
+.\" BTOH32
+.\" LTOH32
+.\" HTOB32
+.\" HTOL32
+.\" BTOH64
+.\" LTOH64
+.\" HTOB64
+.\" HTOL64
+.\"
+.\" RAW8
+.\" RAW16
+.\" RAW32
+.\" RAW64
+.\"
 .\" @GETBYTE
 .\" @PUTBYTE
 .\"
@@ -370,6 +392,85 @@ left or right, respectively, by
 .I n
 places.
 .
+.SS "Byte order conversions"
+For each size suffix
+.IR w ,
+the macro invocation
+.BI ENDSWAP w ( x )
+returns the
+.IR w -bit
+value
+.IR x
+with its bytes reversed.  The
+.B ENDSWAP8
+macro does nothing (except truncate its operand to 8 bits), but is
+provided for the sake of completeness.
+.PP
+A
+.I big-endian
+representation stores the most significant octet of an integer at the
+lowest address, with the following octets in decreasing order of
+significance.  A
+.I little-endian
+representation instead stores the
+.I least
+significant octet at the lowest address, with the following octets in
+increasing order of significance.  An environment has a preferred order
+for arranging the constituent octets of an integer of some given size in
+memory; this might be either the big- or little-endian representation
+just described, or something else strange.
+.PP
+It might be possible to rearrange the bits in an integer so that, when
+that integer is stored to memory in the environment's preferred manner,
+you end up with the big- or little-endian representation of the original
+integer; and, similarly, it might be possible to load a big- or
+little-endian representation of an integer into a variable using the
+environment's preferred ordering and then rearrange the bits so as to
+recover the integer value originally represented.  If the environment is
+sufficiently strange, these things might not be possible, but this is
+actually quite rare.
+.PP
+Say that an integer has been converted to
+.I big-
+or
+.I "little-endian form"
+if, when it is stored in memory in the environment's preferred manner,
+one ends up with a big- or little-endian representation of the original
+integer.  Equivalently, if one starts with a big- or little-endian
+representation of some integer, and loads it into a variable using the
+environment's preferred manner, one ends up with the big- or
+little-endian form of the original integer.
+.PP
+If these things are possible, then the following macros are defined.
+.TP
+.BI HTOL w ( x )
+Convert a
+.IR w -bit
+integer
+.I x
+to little-endian form.
+.TP
+.BI HTOB w ( x )
+Convert a
+.IR w -bit
+integer
+.I x
+to big-endian form.
+.TP
+.BI LTOH w ( x )
+Convert a
+.IR w -bit
+integer
+.I x
+from little-endian form.
+.TP
+.BI BTOH w ( x )
+Convert a
+.IR w -bit
+integer
+.I x
+from big-endian form.
+.
 .SS "Load and store"
 The macro invocation
 .BI GETBYTE( p ", " o )
@@ -389,6 +490,22 @@ These macros always operate on byte offsets regardless of the type of
 the pointer
 .IR p .
 .PP
+For each size suffix
+.IR w ,
+there may be a macro such that the invocation
+.BI RAW w ( p )
+is an lvalue designating the
+.IR w /8
+octets starting at address
+.IR p ,
+interpreted according to the environment's preferred representation,
+except that
+.I p
+need not be aligned in any particular fashion.  There are many reasons
+why this might not be possible; programmers are not normally expected to
+use these macros directly, and they are documented in case they are
+useful for special effects.
+.PP
 For each size-and-endian suffix
 .IR we ,
 the macro invocation