// tiny_debug_api.h - Debug/Guard/Failfast API declarations
// Purpose: Central header for debug instrumentation functions
//          Eliminates implicit declaration warnings across codebase
// License: MIT
// Date: 2025-11-29

#ifndef TINY_DEBUG_API_H
#define TINY_DEBUG_API_H

#include <stdint.h>
#include <stddef.h>

// Forward declarations for types used in function signatures
struct SuperSlab;
struct TinySlabMeta;

// ============================================================================
// Guard System API (defined in hakmem_tiny_ace_guard_box.inc)
// ============================================================================

// Check if guard instrumentation is enabled
// Controlled by HAKMEM_TINY_GUARD environment variable
int tiny_guard_is_enabled(void);

// Called on allocation to track block metadata
// cls: size class, base: slab base, user: user pointer, stride: block size
void tiny_guard_on_alloc(int cls, void* base, void* user, size_t stride);

// Called when invalid header is detected
// user_ptr: pointer with bad header, hdr: actual header value found
void tiny_guard_on_invalid(void* user_ptr, uint8_t hdr);

// ============================================================================
// Fail-Fast Debugging API (defined in tiny_failfast.c)
// ============================================================================

// Get current fail-fast level (0=disabled, 1=log, 2=signal, 3=abort)
// Controlled by HAKMEM_TINY_REFILL_FAILFAST environment variable
int tiny_refill_failfast_level(void);

// Log fail-fast event with slab metadata
// stage: operation name, class_idx: size class, ss: SuperSlab pointer
// meta: slab metadata, ptr: block pointer, prev: previous freelist pointer
void tiny_failfast_log(const char* stage,
                       int class_idx,
                       struct SuperSlab* ss,
                       struct TinySlabMeta* meta,
                       void* ptr,
                       void* prev);

// Abort on fail-fast condition (or log/signal based on level)
// stage: operation name, ss: SuperSlab pointer, slab_idx: slab index
// ptr: problematic pointer, reason: error description
void tiny_failfast_abort_ptr(const char* stage,
                             struct SuperSlab* ss,
                             int slab_idx,
                             void* ptr,
                             const char* reason);

#endif // TINY_DEBUG_API_H