79 lines
2.6 KiB
C
79 lines
2.6 KiB
C
// front_gate_classifier.h - Box FG: Pointer Classification Front Gate
|
|
//
|
|
// Purpose: Single point of truth for classifying pointers (Tiny/Pool/Mid/Large)
|
|
// Design: Heuristic-free, safe header probe + Registry lookup fallback
|
|
//
|
|
// Key Rules:
|
|
// 1. ptr-1 is read ONLY here (never elsewhere)
|
|
// 2. Header probe only when safe (same page + readable)
|
|
// 3. C7 (headerless) always identified via Registry
|
|
// 4. No 1KB alignment heuristics (eliminated false positives)
|
|
//
|
|
// Architecture:
|
|
// - Box FG (this): Classification authority
|
|
// - Box REG: SuperSlab registry (O(1) reverse lookup)
|
|
// - Box TLS: next pointer clearing for C7
|
|
//
|
|
// Performance:
|
|
// - Fast path (C0-C6 header): 5-10 cycles (unchanged)
|
|
// - Slow path (C7 REG): 50-100 cycles (rare)
|
|
// - Safety: SEGV eliminated, false positive = 0%
|
|
|
|
#ifndef FRONT_GATE_CLASSIFIER_H
|
|
#define FRONT_GATE_CLASSIFIER_H
|
|
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
|
|
// Forward declaration
|
|
struct SuperSlab;
|
|
|
|
// Pointer classification kinds
|
|
typedef enum {
|
|
PTR_KIND_TINY_HEADER, // C0-C6: Has 1-byte header (fast path)
|
|
PTR_KIND_TINY_HEADERLESS, // C7: Headerless 1KB blocks (REG path)
|
|
PTR_KIND_POOL_TLS, // Pool TLS 8KB-52KB
|
|
PTR_KIND_MID_LARGE, // Mid/Large allocations
|
|
PTR_KIND_UNKNOWN // Unknown/external allocation
|
|
} tiny_ptr_kind_t;
|
|
|
|
// Classification result
|
|
typedef struct {
|
|
tiny_ptr_kind_t kind; // Classification result
|
|
int class_idx; // Tiny class (0-7), or -1 if not Tiny
|
|
struct SuperSlab* ss; // SuperSlab pointer (from Registry, or NULL)
|
|
int slab_idx; // Slab index within SuperSlab (or -1)
|
|
} ptr_classification_t;
|
|
|
|
// ========== Front Gate API ==========
|
|
|
|
// Classify pointer (single point of truth)
|
|
// Returns: Classification result with kind, class_idx, SuperSlab
|
|
//
|
|
// Strategy:
|
|
// 1. Try safe header probe (C0-C6 fast path: 5-10 cycles)
|
|
// 2. Fallback to Registry lookup (C7 or header failed)
|
|
// 3. Check Pool TLS magic
|
|
// 4. Check AllocHeader (16-byte malloc/mmap)
|
|
// 5. Return UNKNOWN if all fail
|
|
//
|
|
// Safety:
|
|
// - Header probe only if: (ptr & 0xFFF) >= 1 (same page)
|
|
// - No 1KB alignment heuristics
|
|
// - Registry provides ground truth for headerless
|
|
ptr_classification_t classify_ptr(void* ptr);
|
|
|
|
// ========== Debug/Stats (optional) ==========
|
|
|
|
#if !HAKMEM_BUILD_RELEASE
|
|
// Track classification hit rates
|
|
extern __thread uint64_t g_classify_header_hit;
|
|
extern __thread uint64_t g_classify_headerless_hit;
|
|
extern __thread uint64_t g_classify_pool_hit;
|
|
extern __thread uint64_t g_classify_unknown_hit;
|
|
|
|
void front_gate_print_stats(void);
|
|
#endif
|
|
|
|
#endif // FRONT_GATE_CLASSIFIER_H
|