.\" @ROL64_
.\" @ROR64_
.\"
+.\" ENDSWAP16
+.\" ENDSWAP32
+.\" ENDSWAP64
+.\"
+.\" BTOH16
+.\" LTOH16
+.\" HTOB16
+.\" HTOL16
+.\" BTOH32
+.\" LTOH32
+.\" HTOB32
+.\" HTOL32
+.\" BTOH64
+.\" LTOH64
+.\" HTOB64
+.\" HTOL64
+.\"
+.\" RAW8
+.\" RAW16
+.\" RAW32
+.\" RAW64
+.\"
.\" @GETBYTE
.\" @PUTBYTE
.\"
.SH SYNOPSIS
.nf
.B "#include <mLib/bits.h>"
-
+.PP
.BR "typedef " ... " octet;"
.BR "typedef " ... " uint16;"
.BR "typedef " ... " uint24;"
.BR "typedef " ... " uint32;"
.BR "typedef " ... " uint64;"
.BR "typedef " ... " kludge64;"
-
+.PP
.BI "#define TY_" we " " type
.BI "#define SZ_" we " \fR..."
.BI "#define MASK_" we " \fR..."
-
+.PP
.BI "#define DOUINTSZ(" f ") \fR..."
.BI "#define DOUINTCONV(" f ") \fR..."
-
+.PP
.IB type " U" w ( v );
-
+.PP
.IB type " LSL" w ( type " " v ", int " s );
.IB type " LSR" w ( type " " v ", int " s );
.IB type " ROL" w ( type " " v ", int " s );
.IB type " ROR" w ( type " " v ", int " s );
-
+.PP
.BI "octet GETBYTE(void *" p ", size_t " o );
.BI "void PUTBYTE(void *" p ", size_t " o ", octet " v );
-
+.PP
.IB type " LOAD" we "(void *" p );
.BI "void STORE" we "(void *" p ", " type " " v );
-
+.PP
.BI "void SET64(kludge64 &" d ", uint32 " h ", uint32 " l );
.BI "kludge64 X64(" hexh ", " hexl );
.BI "void ASSIGN64(kludge64 &" d ", " x );
.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 )
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
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
-
~mdw / mLib / blobdiff