XeLabs/asm_book
2
0
Fork 0
mirror of https://github.com/pkivolowitz/asm_book.git synced 2026-06-21 02:26:59 +08:00
Code Issues Projects Releases Packages Wiki Activity

Document hex dump display convention in alignment chapter

Browse source 
Closes #22.

The alignment chapter's hex dump examples (e.g. "0011 eeff ccdd aabb"
for a little-endian long initialized to 0xaabbccddeeff0011) are correct
under the default hexdump(1) output convention: bytes grouped into
16-bit little-endian words, each word printed most-significant byte
first. But the chapter never told the reader which convention was in
use, so a reader reproducing the example with xxd or hexdump -C (both
byte-oriented, showing raw memory order) would get a different-looking
result and conclude the book had an endianness bug. That is exactly
what issue #22 reported, and it is also part of what the #33 filer
flagged as "there are no instructions about how to do such a thing"
for hex dumps in this chapter.

Fix: one new subsection "A Note on Hex Dumps" placed before Example 1,
stating the convention explicitly and warning xxd / hexdump -C users
that the bytes within each pair will appear swapped relative to the
examples. The examples themselves are unchanged; they were already
self-consistent under the word-oriented convention.

Rejected alternative: rewriting all the examples in byte-oriented
(xxd) form. That would have matched what most modern readers reach
for, but would also have required regenerating every hex dump in the
chapter and losing continuity with any reader who already absorbed
the current notation. A single explanatory paragraph is less invasive
and teaches the distinction, which is useful in its own right.

No test coverage applies; this is prose.
This commit is contained in:
Perry Kivolowitz 2026-04-19 02:20:10 -05:00
parent 8e8c700b48
commit 88c8f496c4
1 changed files with 12 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
section_1/structs/alignment.md
View file

@ -58,6 +58,18 @@ stinkin' rules.
If they don't mind writing code that's buggy, that is.
## A Note on Hex Dumps
The hex dumps shown in the examples that follow use the
default `hexdump(1)` output format: bytes are grouped into
16-bit *little endian* words, and each word is printed with
its most significant byte first. A byte-oriented tool such
as `xxd` or `hexdump -C` displays the raw bytes in memory
order instead — the same contents, shown differently.
If you reproduce these examples with `xxd`, expect the bytes
within each pair to appear swapped relative to what is shown
here.
## Example 1
```c