From 7aadac2648cb5cf299519d0b45dd975c16464420 Mon Sep 17 00:00:00 2001
From: Douglas Katzman <dougk@google.com>
Date: Sun, 6 Sep 2026 04:39:29 +0000
Subject: [PATCH] Revise some outdated comments

---
 src/compiler/generic/early-objdef.lisp | 27 +++++++++++++++++++++++++-
 src/compiler/generic/objdef.lisp       |  9 ++++-----
 tlsf-bsd/tlsf/tlsf.c                   |  4 ++--
 3 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/src/compiler/generic/early-objdef.lisp b/src/compiler/generic/early-objdef.lisp
index 11d8fb579..769f6d041 100644
--- a/src/compiler/generic/early-objdef.lisp
+++ b/src/compiler/generic/early-objdef.lisp
@@ -438,12 +438,37 @@
 ;;; There are 2 symbol flag bits. The placement restrictions on these stipulate:
 ;;; - no conflict with the generation number (byte 3, low 4 bits)
 ;;; - avoid #+permgen use of byte 3 bit 7 as the "remembered" bit
-;;; - prefer that the uint16_t package ID be naturally aligned if it matters.
 ;;; Given the above:
 ;;; - for x864: byte indices 1 and 2 for the package, byte index 3 for flags so that
 ;;;   the generation byte can stay where it is
 ;;; - for others: byte indices 2 and 3 for package, byte index 1 for flags.
 
+;;; The reason for a discrepancy between x86-64 and everybody else is that
+;;; x86-64 has no penalty for unaligned access, whereas we assume otherwise
+;;; that it is required (or preferred) to use a naturally-aligned uint16_t.
+;;;
+;;; A picture is worth a thousand words:
+;;;
+;;;                       byte 3                    | bytes 1,2  | byte 0  |
+;;;      +-----+-----+-----+-----+-----+------------+------------+---------+ #+x86-64
+;;;      |     |           |     |     |            |   2 byte   |         |
+;;;      |  R  |  f  |  f  |  V  |  -  | generation | package-id | widetag |
+;;;      |     |           |     |     |  (3 bits)  |            |         |
+;;;      +-----+-----+-----+-----+-----+------------+------------+---------+
+;;;
+;;;                       bytes 2,3       |    byte 1            | byte 0  |
+;;;                 +---------------------+-----+-----+----------+---------+ #-x86-64
+;;;                 |       2 byte        |     |     |          |         |
+;;;                 |     package-id      |  f  |  f  | 6 unused | widetag |
+;;;                 |                     |     |     |   bits   |         |
+;;;                 +---------------------|-----+-----+----------+---------+
+
+;;;
+;;; - = unused
+;;; V = "Visited" bit for mark-and-sweep collector
+;;; R = "Remset" presence bit
+;;; f = flag bits
+
 ;;; A symbol that is "fast bindable" is neither constant, nor global,
 ;;; nor a global symbol-macro, nor in a locked package. Such symbols can be
 ;;; bound by PROGV without calling ABOUT-TO-MODIFY-SYMBOL-VALUE, except in the
diff --git a/src/compiler/generic/objdef.lisp b/src/compiler/generic/objdef.lisp
index 0f41b51d3..753493f99 100644
--- a/src/compiler/generic/objdef.lisp
+++ b/src/compiler/generic/objdef.lisp
@@ -145,14 +145,13 @@ Code header representation:
   +---------------------------------+
   max total payload size in words = #x3fffff
 
-  |            total words          | gc_gen | 0 | 0 | widetag |
-  |            (4 bytes)            |        |   |   |         |
+  |         total words          | gc_gen | 0 | TLSF | widetag |
+  |         (4 bytes)            |        |   | bits |         |
   +------------------------------------------------------------+  [64-bit words]
-  |                                 |   N boxed header bytes   |
-  |                                 |        (4 bytes)         |
+  |                              |      N boxed header bytes   |
+  |                              |           (4 bytes)         |
   +------------------------------------------------------------+
 
-  the two zero bytes are reserved for future use
   max total payload size in words = uint_max
     (should probably made the same as for 32-bit word size for consistency)
 
diff --git a/tlsf-bsd/tlsf/tlsf.c b/tlsf-bsd/tlsf/tlsf.c
index ce628fd3e..44465f5a4 100644
--- a/tlsf-bsd/tlsf/tlsf.c
+++ b/tlsf-bsd/tlsf/tlsf.c
@@ -120,14 +120,14 @@ typedef struct block_header_t {
     unsigned char widetag;
     unsigned char _flags; // must have at most bits 0, 1, 2 on
     unsigned char unused; // must be zero
-    unsigned char gen; // low 4 must be 0..5 and bit 0x4 can be on
+    unsigned char gen; // low 4 must be 0..6 and bit index 4 (VISITED) can be on
     uint32_t _nwords; // including the header
 #else
     // For this word to read as an object header, the size and widetag
     // are flipped relative to little-endian.
     // I did not actually test this - I am merely guessing that it's right.
     uint32_t _nwords; // including the header
-    unsigned char gen; // low 4 must be 0..5 and bit 0x4 can be on
+    unsigned char gen; // low 4 must be 0..6 and bit index 4 (VISITED) can be on
     unsigned char unused; // must be zero
     unsigned char _flags; // must have at most bits 0, 1, 2 on
     unsigned char widetag;