From f5272c51b11ec06627d748901c7747154f3bbf04 Mon Sep 17 00:00:00 2001
From: Richard Qin <richard.qin.x@gmail.com>
Date: Tue, 21 Apr 2026 23:20:32 +0800
Subject: feat: add features header and frame descriptor implementation

---
 na/include/lume/features.h | 40 +++++++++++++++++++++++++++++++
 na/include/lume/frame.h    | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 na/include/lume/features.h
 create mode 100644 na/include/lume/frame.h

(limited to 'na/include')

diff --git a/na/include/lume/features.h b/na/include/lume/features.h
new file mode 100644
index 0000000..85cfb72
--- /dev/null
+++ b/na/include/lume/features.h
@@ -0,0 +1,40 @@
+#ifndef _FEATURES_H
+#define _FEATURES_H
+
+#if defined(_ALL_SOURCE) && !defined(_GNU_SOURCE)
+#define _GNU_SOURCE 1
+#endif
+
+#if defined(_DEFAULT_SOURCE) && !defined(_BSD_SOURCE)
+#define _BSD_SOURCE 1
+#endif
+
+#if !defined(_POSIX_SOURCE) && !defined(_POSIX_C_SOURCE) \
+ && !defined(_XOPEN_SOURCE) && !defined(_GNU_SOURCE) \
+ && !defined(_BSD_SOURCE) && !defined(__STRICT_ANSI__)
+#define _BSD_SOURCE 1
+#define _XOPEN_SOURCE 700
+#endif
+
+#if __STDC_VERSION__ >= 199901L
+#define __restrict restrict
+#elif !defined(__GNUC__)
+#define __restrict
+#endif
+
+#if __STDC_VERSION__ >= 199901L || defined(__cplusplus)
+#define __inline inline
+#elif !defined(__GNUC__)
+#define __inline
+#endif
+
+#if __STDC_VERSION__ >= 201112L
+#elif defined(__GNUC__)
+#define _Noreturn __attribute__((__noreturn__))
+#else
+#define _Noreturn
+#endif
+
+#define __REDIR(x,y) __typeof__(x) x __asm__(#y)
+
+#endif
diff --git a/na/include/lume/frame.h b/na/include/lume/frame.h
new file mode 100644
index 0000000..4424979
--- /dev/null
+++ b/na/include/lume/frame.h
@@ -0,0 +1,59 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright (C) 2026 Richard Qin */
+
+#pragma once
+
+/*
+ * Frame — Physical page frame descriptor
+ *
+ * Each Frame describes one 4KB physical page.  A flat array of Frame
+ * structs (frame_map) covers all physical memory discovered via FDT.
+ *
+ * Memory layout is compressed using a union: only one of free/slab
+ * metadata is valid at a time, determined by `state`.  The refcount
+ * field is independent of the union to support COW sharing.
+ *
+ * Reference: docs/specs/pmm.md §3.1
+ */
+
+#include <lume/types.h>
+#include <lume/list.h>
+#include <lume/atomic.h>
+
+/* Forward declaration — defined in slab module (Phase 2) */
+class KmemCache;
+
+enum class FrameState : uint8 {
+    Free,       // In Buddy free list
+    PcpCached,  // In Per-CPU cache (invisible to buddy coalescing)
+    Allocated,  // Handed out to Slab / VMM / user
+    Slab,       // Backing a Slab cache
+};
+
+struct Frame {
+    /*
+     * Reference count (atomic).
+     * Starts at 1 on allocation.  Incremented by fork() for COW pages.
+     * When decremented to 0, the frame is returned to the free pool.
+     */
+    lume::atomic<uint32> refcount;
+
+    FrameState state;   // Current usage state
+    uint8 order;        // Buddy order (0–10, i.e. 4KB–4MB)
+
+    union {
+        /* Valid when state == Free */
+        struct {
+            list_node free_link;  // Link into Buddy or PCP free list
+        } free;
+
+        /* Valid when state == Slab */
+        struct {
+            KmemCache* cache;     // Owning slab cache
+            uint32 obj_count;     // Number of allocated objects on this page
+            void* freelist;       // Head of in-page free object linked list
+        } slab;
+
+        /* state == Allocated: no extra metadata (yet) */
+    };
+};
-- 
cgit v1.2.3