hakmem/core/box/tiny_next_ptr_box.h

#ifndef TINY_NEXT_PTR_BOX_H
#define TINY_NEXT_PTR_BOX_H

/**
 * 📦 Box: Next Pointer Operations (Lowest-Level API)
 *
 * Phase E1-CORRECT: Unified next pointer read/write API for ALL classes (C0-C7)
 *
 * This Box provides structural guarantee that ALL next pointer operations
 * use consistent offset calculation, eliminating scattered direct pointer
 * access bugs.
 *
 * Design:
 * - With HAKMEM_TINY_HEADER_CLASSIDX=1: Next pointer stored at base+1 (ALL classes)
 * - Without headers: Next pointer stored at base+0
 * - Inline expansion ensures ZERO performance cost
 *
 * Usage:
 *   void* next = tiny_next_read(class_idx, base_ptr);      // Read next pointer
 *   tiny_next_write(class_idx, base_ptr, new_next);        // Write next pointer
 *
 * Critical:
 * - ALL freelist operations MUST use this API
 * - Direct access like *(void**)ptr is PROHIBITED
 * - Grep can detect violations: grep -rn '\*\(void\*\*\)' core/
 */

#include <stdint.h>
#include <stdio.h>   // For debug fprintf
#include <stdatomic.h>  // For _Atomic
#include <stdlib.h>  // For abort()

/**
 * Write next pointer to freelist node
 *
 * @param class_idx Size class index (0-7)
 * @param base Base pointer (NOT user pointer)
 * @param next_value Next pointer to store (or NULL for list terminator)
 *
 * CRITICAL FIX: Class 0 (8B block) cannot fit 8B pointer at offset 1!
 * - Class 0: 8B total = [1B header][7B data] → pointer at base+0 (overwrite header when free)
 * - Class 1-6: Next at base+1 (after header)
 * - Class 7: Next at base+0 (no header in original design, kept for compatibility)
 *
 * NOTE: We take class_idx as parameter (NOT read from header) because:
 * - Linear carved blocks don't have headers yet (uninitialized memory)
 * - Class 0/7 overwrite header with next pointer when on freelist
 */
static inline void tiny_next_write(int class_idx, void* base, void* next_value) {
#if HAKMEM_TINY_HEADER_CLASSIDX
    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
    // Reading uninitialized header bytes causes random offset calculation
    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;

    // 🐛 DEBUG: Log writes for debugging (Class 1-6 only - Class 0/7 overwrite header)
    #if !HAKMEM_BUILD_RELEASE
    static _Atomic uint64_t g_write_count = 0;
    uint64_t write_num = atomic_fetch_add(&g_write_count, 1);

    // Log first 20 writes for debugging
    if (write_num < 20) {
        fprintf(stderr, "[BOX_WRITE #%lu] class=%d base=%p next=%p offset=%zu\n",
                write_num, class_idx, base, next_value, next_offset);
        fflush(stderr);
    }

    // Verify header for Class 1-6 (Class 0/7 have no valid header on freelist)
    if (next_offset != 0) {
        uint8_t header_before = *(uint8_t*)base;
        *(void**)((uint8_t*)base + next_offset) = next_value;
        uint8_t header_after = *(uint8_t*)base;

        if (header_after != header_before) {
            fprintf(stderr, "\n🐛 BUG DETECTED: Header corruption!\n");
            fprintf(stderr, "Class: %d, Base: %p, Header before: 0x%02x, after: 0x%02x\n",
                    class_idx, base, header_before, header_after);
            fflush(stderr);
            abort();
        }
    } else {
        // Class 0/7: Just write, no header validation
        *(void**)((uint8_t*)base + next_offset) = next_value;
    }
    #else
    // Release: Direct write
    *(void**)((uint8_t*)base + next_offset) = next_value;
    #endif
#else
    // No headers: Next pointer at base
    *(void**)base = next_value;
#endif
}

/**
 * Read next pointer from freelist node
 *
 * @param class_idx Size class index (0-7)
 * @param base Base pointer (NOT user pointer)
 * @return Next pointer (or NULL if end of list)
 */
static inline void* tiny_next_read(int class_idx, const void* base) {
#if HAKMEM_TINY_HEADER_CLASSIDX
    // Phase E1-CORRECT FIX: Use class_idx parameter (NOT header byte!)
    size_t next_offset = (class_idx == 0 || class_idx == 7) ? 0 : 1;

    // 🐛 DEBUG: Check if we're about to read a corrupted next pointer (Class 1-6 only)
    #if !HAKMEM_BUILD_RELEASE
    void* next_val = *(void**)((const uint8_t*)base + next_offset);

    // For Class 1-6 (offset=1), check if next pointer looks corrupted (starts with 0xa0-0xa7)
    // This means someone wrote to offset 0, overwriting the header
    if (next_offset == 1 && next_val != NULL) {
        uintptr_t next_addr = (uintptr_t)next_val;
        uint8_t high_byte = (next_addr >> 56) & 0xFF;

        if (high_byte >= 0xa0 && high_byte <= 0xa7) {
            fprintf(stderr, "\n🐛 BUG DETECTED: Corrupted next pointer!\n");
            fprintf(stderr, "Class: %d, Base: %p, Next: %p (high byte: 0x%02x)\n",
                    class_idx, base, next_val, high_byte);
            fprintf(stderr, "This means next pointer was written at OFFSET 0!\n");
            fflush(stderr);
            abort();
        }
    }
    #endif

    return *(void**)((const uint8_t*)base + next_offset);
#else
    // No headers: Next pointer at base
    return *(void**)base;
#endif
}

#endif  // TINY_NEXT_PTR_BOX_H