From de1e83c0a9e53b5549898083ef495878aaaf50b2 Mon Sep 17 00:00:00 2001
From: Richard Qin <richard.qin.x@gmail.com>
Date: Tue, 21 Apr 2026 23:10:48 +0800
Subject: feat: add address conversion and console initialization helpers

---
 na/include/lume/addr.h    | 71 +++++++++++++++++++++++++++++++++++++++++++++++
 na/include/lume/console.h | 15 ++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 na/include/lume/addr.h
 create mode 100644 na/include/lume/console.h

diff --git a/na/include/lume/addr.h b/na/include/lume/addr.h
new file mode 100644
index 0000000..a873c1b
--- /dev/null
+++ b/na/include/lume/addr.h
@@ -0,0 +1,71 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright (C) 2026 Richard Qin */
+
+#pragma once
+
+/*
+ * Machine-Independent Address Conversion Helpers
+ *
+ * All PA↔VA conversions in MI code (mm/, kernel/, etc.) must go through
+ * these functions.  The actual offset is provided by <arch/config.h>.
+ *
+ * Reference: docs/specs/00_conventions.md §1.1 (MI/MD separation)
+ */
+
+#include <lume/types.h>
+#include <lume/config.h>
+#include <arch/config.h>
+
+/* Convert physical address to kernel virtual address */
+inline uint64 pa_to_va(uint64 pa)
+{
+    return pa + arch::kVAOffset;
+}
+
+/* Convert kernel virtual address to physical address */
+inline uint64 va_to_pa(uint64 va)
+{
+    return va - arch::kVAOffset;
+}
+
+/* Check if an address is a kernel virtual address */
+inline bool is_kernel_va(uint64 addr)
+{
+    return addr >= arch::kVAOffset;
+}
+
+/* Convert an address that might be VA or PA to PA */
+inline uint64 ensure_pa(uint64 addr)
+{
+    return is_kernel_va(addr) ? va_to_pa(addr) : addr;
+}
+
+/* Convert an address that might be VA or PA to VA */
+inline uint64 ensure_va(uint64 addr)
+{
+    return is_kernel_va(addr) ? addr : pa_to_va(addr);
+}
+
+/* Align up to page boundary */
+inline uint64 page_align_up(uint64 addr)
+{
+    return (addr + kPageSize - 1) & ~(kPageSize - 1);
+}
+
+/* Align down to page boundary */
+inline uint64 page_align_down(uint64 addr)
+{
+    return addr & ~(kPageSize - 1);
+}
+
+/* Convert physical address to page frame number (PFN) */
+inline uint64 pa_to_pfn(uint64 pa)
+{
+    return pa / kPageSize;
+}
+
+/* Convert page frame number (PFN) to physical address */
+inline uint64 pfn_to_pa(uint64 pfn)
+{
+    return pfn * kPageSize;
+}
diff --git a/na/include/lume/console.h b/na/include/lume/console.h
new file mode 100644
index 0000000..ff9f019
--- /dev/null
+++ b/na/include/lume/console.h
@@ -0,0 +1,15 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/* Copyright (C) 2026 Richard Qin */
+
+#pragma once
+
+#include <lume/types.h>
+
+extern "C" void early_putc(char c);
+extern "C" void early_puts(const char* s);
+
+/* Early UART discovery via raw FDT parsing. */
+void console_early_init(uint64 fdt_paddr);
+
+/* Full console initialization. Maps MMIO. */
+void console_init();
-- 
cgit v1.2.3