hakmem/core/box/ptr_conversion_box.h

/**
 * @file ptr_conversion_box.h
 * @brief Box 3: Unified Pointer Conversion Layer
 *
 * MISSION: Fix BASE/USER pointer confusion across codebase
 *
 * DESIGN:
 * - BASE pointer: Points to start of block in storage (0-byte aligned)
 * - USER pointer: Points to usable memory (+1 byte for all Tiny classes in header mode)
 * - Freed blocks may overwrite the header for next-pointer storage (C0/C7), but
 *   allocation path rewrites the header before returning USER.
 *
 * BOX BOUNDARIES:
 * - Box 1 (Front Gate) → Box 3 → Box 4 (User)  [BASE to USER]
 * - Box 4 (User) → Box 3 → Box 1 (Front Gate)  [USER to BASE]
 */

#ifndef HAKMEM_PTR_CONVERSION_BOX_H
#define HAKMEM_PTR_CONVERSION_BOX_H

#include <stdint.h>
#include <stddef.h>
#include "ptr_type_box.h"
#include "tiny_layout_box.h"

#ifdef HAKMEM_PTR_CONVERSION_DEBUG
#include <stdio.h>
#define PTR_CONV_LOG(...) fprintf(stderr, "[PTR_CONV] " __VA_ARGS__)
#else
#define PTR_CONV_LOG(...) ((void)0)
#endif

/**
 * Convert BASE pointer (storage) to USER pointer (returned to caller)
 * Phase E1-CORRECT: Offsets defined in tiny_layout_box.h
 *
 * @param base Block start in storage (wrapped hak_base_ptr_t)
 * @param class_idx Size class
 * @return User pointer (wrapped hak_user_ptr_t)
 */
static inline hak_user_ptr_t ptr_base_to_user(hak_base_ptr_t base, int class_idx) {
    void* raw_base = HAK_BASE_TO_RAW(base);
    if (raw_base == NULL) {
        return HAK_USER_FROM_RAW(NULL);
    }

#if HAKMEM_TINY_HEADERLESS
    (void)class_idx;
    // Headerless: user = base (identity)
    void* raw_user = raw_base;
    size_t offset = 0;
#else
    size_t offset = tiny_user_offset(class_idx);
    void* raw_user = (void*)((uint8_t*)raw_base + offset);
#endif
    
    PTR_CONV_LOG("BASE→USER cls=%d base=%p → user=%p (+%zu)\n",
                 class_idx, raw_base, raw_user, offset);
    return HAK_USER_FROM_RAW(raw_user);
}

/**
 * Convert USER pointer (from caller) to BASE pointer (storage)
 * Phase E1-CORRECT: Offsets defined in tiny_layout_box.h
 *
 * @param user Pointer from user (wrapped hak_user_ptr_t)
 * @param class_idx Size class
 * @return Base pointer (wrapped hak_base_ptr_t)
 */
static inline hak_base_ptr_t ptr_user_to_base(hak_user_ptr_t user, int class_idx) {
    void* raw_user = HAK_USER_TO_RAW(user);
    if (raw_user == NULL) {
        return HAK_BASE_FROM_RAW(NULL);
    }

#if HAKMEM_TINY_HEADERLESS
    (void)class_idx;
    // Headerless: base = user (identity)
    void* raw_base = raw_user;
    size_t offset = 0;
#else
    size_t offset = tiny_user_offset(class_idx);
    void* raw_base = (void*)((uint8_t*)raw_user - offset);
#endif
    
    PTR_CONV_LOG("USER→BASE cls=%d user=%p → base=%p (-%zu)\n",
                 class_idx, raw_user, raw_base, offset);
    return HAK_BASE_FROM_RAW(raw_base);
}

/**
 * Convert USER pointer to BASE pointer WITHOUT knowing class_idx
 * Primary use: free() entry point where class is not yet known
 */
static inline void* ptr_user_to_base_blind(void* user_ptr) {
    if (user_ptr == NULL) return NULL;

#if HAKMEM_TINY_HEADERLESS || !HAKMEM_TINY_HEADER_CLASSIDX
    // Headerless: base = user
    return user_ptr;
#else
    // Phase E1-CORRECT: All Tiny classes use 1 byte header.
    // For blind conversion (no class info), assume standard header offset
    // This works because class is determined AFTER base pointer calculation
    size_t offset = TINY_HEADER_SIZE;  // From tiny_layout_box.h
    return (void*)((uint8_t*)user_ptr - offset);
#endif
}

/**
 * Convenience macros for cleaner call sites
 */
#define PTR_BASE_TO_USER(base, cls) ptr_base_to_user((base), (cls))
#define PTR_USER_TO_BASE(user, cls) ptr_user_to_base((user), (cls))

#endif /* HAKMEM_PTR_CONVERSION_BOX_H */