UMN-Kernel-Object
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎.mailmap‎
Lines changed: 1 addition & 0 deletions b/‎.mailmap‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎REUSE.toml‎
Lines changed: 1 addition & 1 deletion b/‎REUSE.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎doc/SUMMARY.md‎
Lines changed: 4 additions & 0 deletions b/‎doc/SUMMARY.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎doc/include.mak‎
Lines changed: 1 addition & 1 deletion b/‎doc/include.mak‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎doc/kernel/mm/booting.md‎
Lines changed: 58 additions & 0 deletions b/‎doc/kernel/mm/booting.md‎
Lines changed: 58 additions & 0 deletions
diff --git a/‎doc/kernel/mm/memory-map.md‎
Lines changed: 32 additions & 0 deletions b/‎doc/kernel/mm/memory-map.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎doc/kernel/mm/overview.md‎
Lines changed: 29 additions & 0 deletions b/‎doc/kernel/mm/overview.md‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎src/kernel/arch/riscv64/bootstub.S‎
Lines changed: 2 additions & 7 deletions b/‎src/kernel/arch/riscv64/bootstub.S‎
Lines changed: 2 additions & 7 deletions
diff --git a/‎src/kernel/arch/riscv64/bootstub.ld‎
Lines changed: 21 additions & 12 deletions b/‎src/kernel/arch/riscv64/bootstub.ld‎
Lines changed: 21 additions & 12 deletions
@@ -14,6 +14,7 @@ result-*
 
 /build/
 /compile_commands.json
+/src/kernel/arch/riscv64/bootstub_generated.ld
 /src/kernel/arch/riscv64/bootstub_generated.S
 /src/kernel/arch/riscv64/kernel-unstripped.elf
 /src/kernel/arch/riscv64/kernel.elf
 
@@ -0,0 +1 @@
+Amy Ringo <me@remexre.com>
@@ -13,7 +13,7 @@ SPDX-FileCopyrightText = "2025 ukoOS Contributors"
 SPDX-License-Identifier = "CC-BY-SA-4.0 OR GFDL-1.3-or-later"
 
 [[annotations]]
-path = ["flake.lock"]
+path = [".mailmap", "flake.lock"]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2025 ukoOS Contributors"
 SPDX-License-Identifier = "CC0-1.0"
@@ -10,6 +10,10 @@
 - [Kernel]()
   - [The `print()` and `format()` functions](./kernel/print.md)
   - [Threads and Harts](./kernel/threads-and-harts.md)
+  - [Memory management]()
+    - [Overview](./kernel/mm/overview.md)
+    - [Memory map](./kernel/mm/memory-map.md)
+    - [Booting](./kernel/mm/booting.md)
 - [Targets](./targets.md)
 - [Tutorials](./tutorials/tutorials.md)
   - [First Day](./tutorials/first-day.md)
 
@@ -14,7 +14,7 @@ all:: doc/book
 clean::
 	@if [[ -d doc/book ]]; then echo "CLEAN   doc/book"; rm -r doc/book; fi
 doc-serve:
-	$(Q)mdbook serve --dest-dir $(abspath doc/book) $(srcdir)/doc
+	$(Q)mdbook serve --dest-dir "$$(realpath doc/book)" --hostname :: $(srcdir)/doc
 .PHONY: doc-serve
 
 doc/book: $(srcdir)/doc/book.toml $(srcdir)/doc/SUMMARY.md
 
@@ -0,0 +1,58 @@
+# Booting
+
+Before ordinary driver code can run, the three main allocators in the mm subsystem (heap, physical, virtual) need to be initialized.
+This document describes that initialization.
+
+## Build-time
+
+At build-time, we can request pages (as `.bss` or `.data`) that we're given before the kernel starts, saving us from having to implement allocation that early in boot.
+We use this to allocate initial page tables and some initial heap and stack memory.
+
+See `src/kernel/arch/riscv64/generate_bootstub.py` for the code that does this.
+
+The initial page tables are generated ahead-of-time and compiled into the kernel binary, so that virtual memory works immediately, before any allocators are up.
+These page tables have entries for:
+
+- The physical memory mapping.
+  - The entire mapping is made, using 1GiB pages.
+- The initial heap segment.
+  - This is 4MiB, and gets mapped to the RAM area.
+- The boothart's stack.
+  - This is 2MiB, and gets mapped to the RAM area.
+  - After the physical memory allocator is set up, guard pages get set up.
+- The kernel.
+
+## Heap allocator
+
+There is one instance of the heap allocator per hart, to avoid the need to acquire locks or use atomics in the fast-path of allocation.
+The boothart's heap allocator gets initialized with the initial heap segment allocated at build-time.
+This lets the boothart allocate up to 4MiB of objects whose sizes are less than 512KiB.
+
+One annoying thing -- the heap allocator depends on a source of entropy.
+This early in boot, the entropy pool cannot be fully seeded, so we have to try to harvest a bit of entropy to use.
+Right now, our only source of entropy at this point is the cycle and time counters.
+We take a trap while moving to the higher half, so we can get some unpredictability from the timings there; when booting on real hardware, the time taken to load the kernel from storage should also provide some.
+
+The Devicetree gets parsed into memory owned by the heap allocator, which lets us add memory reservations for e.g. the kernel itself.
+
+## Physical allocator
+
+Once the heap allocator is initialized on the boothart, we can discover the rest of the RAM.
+We do this by parsing the Devicetree that was passed to us by the bootloader.
+
+Once it's parsed, we can easily extract the parts of it we need:
+
+- The `/chosen/rng-seed` node, as entropy to further initialize the entropy pool.
+  This is usually enough to fully initialize the pool. 
+- `/memory` nodes, which describe the memory installed on the device.
+- `/reserved-memory` nodes, which we avoid adding to the physical allocator.
+
+From the memory and reservations, we can find all the free regions of unreserved RAM.
+We use a simple free list to track them.
+
+## Virtual allocator
+
+The virtual allocator for higher-half memory can now be initialized as well.
+This allocator covers the entire 38-bit space, but will only ever have the RAM area marked as free.
+
+Once this is done, the heap allocator is able to allocate more heap segments from the physical allocator, so there's no longer a 4MiB limitation on heap allocation.
@@ -0,0 +1,32 @@
+# Memory map
+
+ukoOS is a higher-half kernel (i.e., all the kernel's data is mapped to an address whose MSB is 1).
+Depending on how many bits of virtual address space the hardware supports, the kernel memory map is somewhat different.
+
+## Sv39 memory map
+
+In Sv39, virtual addresses are 39 bits, and sign-extended to 64 bits.
+
+| Start Address        | End Address          | Size           | Description               |
+|:---------------------|:---------------------|:---------------|:--------------------------|
+| `0x0000000000000000` | `0x0000003fffffffff` | 256GiB         | Userspace virtual memory  |
+| `0x0000004000000000` | `0xffffffbfffffffff` | 16EiB - 512GiB | Illegal addresses in Sv39 |
+| `0xffffffc000000000` | `0xffffffdfffffffff` | 128GiB         | Physical memory           |
+| `0xffffffe000000000` | `0xffffffffbfffffff` | 127GiB         | RAM                       |
+| `0xffffffffc0000000` | `0xffffffffffffffff` | 1GiB           | Kernel                    |
+
+- The userspace memory map can be controlled from userspace, and does not have a fixed structure.
+
+- A large range of 64-bit addresses are illegal in Sv39, because there are not enough bits to represent them.
+
+- 128GiB of physical memory is directly mapped.
+  This should be enough to access any memory-mapped devices; devices that use more physical memory than this tend to support Sv48 or Sv57.
+
+- Up to 127GiB of RAM can be mapped.
+  Past this point, no more memory can be used by the kernel.
+  Machines with anywhere near this much memory support Sv48 or Sv57, so this isn't a limitation in practice.
+
+  Memory gets mapped here by the allocator as needed.
+
+- The kernel itself is mapped into a large contiguous region.
+  There are a lot of smaller regions within this region, but they're outside the scope of this page.
@@ -0,0 +1,29 @@
+# Overview
+
+ukoOS has multiple strategies for memory management, that manage memory at different levels.
+
+- The kernel has a standard memory allocator, accessed with the functions `alloc` and `free`.
+  These functions act similarly to `malloc` and `free` in ordinary C.
+
+  This is based on the design from [Mimalloc: Free List Sharding in Action](https://www.microsoft.com/en-us/research/wp-content/uploads/2019/06/mimalloc-tr-v1.pdf); read that if you want to understand the design.
+
+  The allocator that handles these requests is called **the heap memory allocator**.
+
+- The kernel keeps track of all of RAM, and hands out pages to be mapped into userspace processes and to be used by the heap memory allocator.
+
+  This allocator is a simple free list.
+
+  This allocator is currently not capable of allocating more than a single contiguous page, but could be extended to support this in the future.
+  This allocator is called **the physical memory allocator**.
+
+- The kernel manages its own virtual memory, in the RAM region of the memory map.
+
+  This allocator is a pair of treaps, one for all VMAs sorted by address, and another for only free VMAs sorted by size.
+  If you're not already familiar with treaps, there's a Julia Evans piece about them: [Data structure: the treap!](https://jvns.ca/blog/2017/09/09/data-structure--the-treap-/)
+
+  The allocator that handles these requests is called **the virtual memory allocator**.
+
+Each hart has its own root page table, since it can be running a different userspace process.
+However, the kernel's memory map is kept in sync between all harts.
+
+Higher-half memory is only rarely mapped and unmapped, so relatively inefficient mechanisms (a full TLB shootdown) can be used to ensure all harts have the same view of it.
@@ -11,14 +11,13 @@
 # Expects the following arguments:
 #
 # a0: The hart ID.
-# a1: The DeviceTree pointer.
+# a1: The Devicetree pointer.
 .p2align 2
 .global _start
 .type _start, @function
 _start:
 	# Set up the initial stack.
-	la sp, 0xffffffffffffd000 - 16
-	la t0, _stack_end_phys - 16
+	ld sp, (initial_stack_va)
 
 	# Get the (physical) address of the root page table.
 	la t1, boot_pgtbl_2_0000000000000000
@@ -38,10 +37,6 @@ _start:
 	ld a5, (symtab_len)
 	ld a6, (strtab_va)
 	ld a7, (strtab_len)
-	ld t3, (free_va_start)
-	ld t4, (free_va_end)
-	sd t3, (t0)
-	sd t4, 8(t0)
 
 	# Get the (virtual) address of the higher-half entrypoint.
 	ld t0, (entrypoint)
 
@@ -36,19 +36,12 @@ SECTIONS
 	 */
 	_kernel_start_phys = .;
 
-	/**
-	 * The page tables get appended as well.
-	 */
-	.pgtbls ALIGN(0x1000) :
-	{
-		*(.pgtbls)
-	}
-
 	/**
 	 * The kernel's string and symbol table sections get appended.
 	 */
 	.kernel_tables ALIGN(0x1000) :
 	{
+		PROVIDE(__start_kernel_tables = .);
 		*(.kernel_tables)
 	}
 
@@ -57,6 +50,7 @@ SECTIONS
 	 */
 	.kernel ALIGN(0x1000) :
 	{
+		PROVIDE(__start_kernel = .);
 		*(.kernel)
 	}
 	.kernel_bss :
@@ -65,13 +59,28 @@ SECTIONS
 	}
 
 	/**
-	 * An initial stack page, to use in early boot (i.e., before the allocator is up).
+	 * The initial heap segment and boothart stack.
 	 */
-	.stack ALIGN(0x1000) :
+	.initial_heap_segment ALIGN(0x1000) :
+	{
+		PROVIDE(__start_initial_heap_segment = .);
+		. += 0x400000;
+	}
+	.boothart_stack ALIGN(0x1000) :
 	{
-		. += 0x1000;
-		_stack_end_phys = .;
+		PROVIDE(__start_boothart_stack = .);
+		. += 0x200000;
+	}
+
+	/**
+	 * The page tables get appended as well.
+	 */
+	.pgtbls ALIGN(0x1000) :
+	{
+		*(.pgtbls)
 	}
 
 	_kernel_end_phys = .;
+
+	INCLUDE "src/kernel/arch/riscv64/bootstub_generated.ld"
 }