page_table.h File Reference

Page table definitions and helpers for virtual memory mapping. More...

#include "fdt/fdt.h"
#include "linker/linker_defines.h"
#include "mem_layout/mem_layout.h"
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for page_table.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	page_permissions_t
	Software representation of architectural page mapping privileges. More...
struct	table_desc_t
	TABLE DESCRIPTOR LAYOUT (Lookup levels 0, 1, or 2). More...
struct	page_desc_t
	FLAT BLOCK/PAGE DATA DESCRIPTOR LAYOUT — maps real physical memory. More...
union	page_table_entry_t
	Flat, architecturally stable AArch64 Stage 1 Descriptor structure. More...
struct	page_table_t
	Represents a single page table level (512 entries). More...

Macros
#define	PAGE_SIZE   LINKER_PAGE_SIZE
	Size of each memory page in bytes.
#define	PTRS_PER_TABLE   512
	Number of pointers per page table. from table D4-21 in the Armv8-A architecture reference manual.
#define	NUM_PAGES(size)   (((size) + PAGE_SIZE - 1) / PAGE_SIZE)
	Calculate the number of pages needed for a given size.

Typedefs
typedef struct page_permissions_t	page_permissions_t
	Software representation of architectural page mapping privileges.
typedef enum mem_type_t	mem_type_t
	Memory type used as an index into the MAIR_EL1 register.
typedef struct table_desc_t	table_desc_t
	TABLE DESCRIPTOR LAYOUT (Lookup levels 0, 1, or 2).
typedef struct page_desc_t	page_desc_t
	FLAT BLOCK/PAGE DATA DESCRIPTOR LAYOUT — maps real physical memory.
typedef union page_table_entry_t	page_table_entry_t
	Flat, architecturally stable AArch64 Stage 1 Descriptor structure.
typedef struct page_table_t	page_table_t
	Represents a single page table level (512 entries).

Enumerations
enum	mem_type_t { DEVICE = 0 , NORMAL }
	Memory type used as an index into the MAIR_EL1 register. More...

Functions
bool	map_page (page_table_t *root, virt_addr v_addr, phy_addr phy_addr, page_permissions_t perms, mem_type_t mem_typ)
	Map a virtual address to a physical address in the page table.
void	dump_memory_map (page_table_t *root)
	Dump the memory map for debugging.
bool	setup_kernel_id_map (phy_addr serial_device_addr_base)
	Set up the initial identity-mapped region for the kernel.
bool	setup_kernel_map (memory_map_t *mmap)
	Set up the kernel's higher-half virtual-memory map.

Detailed Description

Page table definitions and helpers for virtual memory mapping.

Provides architecture-specific macros and declarations for building and manipulating page tables used by the kernel's memory management.

Author

Abhin Parekadan Jose

Date

2026-05-17

Typedef Documentation

mem_type_t

typedef enum mem_type_t mem_type_t

Memory type used as an index into the MAIR_EL1 register.

The numeric value of each enumerator directly corresponds to the MAIR_EL1 attribute index encoded in page/block descriptor bits [4:2] (AttrIndx). The kernel must program MAIR_EL1 so that each index carries the correct attribute byte before the MMU is enabled.

page_desc_t

typedef struct page_desc_t page_desc_t

FLAT BLOCK/PAGE DATA DESCRIPTOR LAYOUT — maps real physical memory.

Represents a 64-bit Stage 1 VMSAv8-64 block or page descriptor (4 KB granule) as defined in ARMv8/ARMv9 Architecture Reference Manual.

• Level 1/2 block — bits[1:0] == 0b01, maps a 1 GB (L1) or 2 MB (L2) region.
• Level 3 page — bits[1:0] == 0b11, maps a 4 KB page.

Lower attributes (bits [11:2]) control memory type, permissions, and shareability. The output address window (bits [49:12]) holds the physical frame address. Upper attributes (bits [63:50]) carry execution controls and feature extensions.

page_permissions_t

typedef struct page_permissions_t page_permissions_t

Software representation of architectural page mapping privileges.

This tracking structure is used by the Virtual Memory Manager (VMM) to translate abstract software permissions down into raw ARM64 hardware bitfield constraints.

page_table_entry_t

typedef union page_table_entry_t page_table_entry_t

Flat, architecturally stable AArch64 Stage 1 Descriptor structure.

This union maps a standard 64-bit ARMv8/ARMv9 translation table descriptor. By avoiding nested internal anonymous unions and leveraging flattened structural representations, it guarantees exact 8-byte compilation across GCC and Clang toolchains without unintended alignment padding.

table_desc_t

typedef struct table_desc_t table_desc_t

TABLE DESCRIPTOR LAYOUT (Lookup levels 0, 1, or 2).

Represents a 64-bit table descriptor as defined by ARMv8/ARMv9 VMSAv8-64 Table D8-50 (4 KB granule). A descriptor at levels 0–2 whose bits [1:0] == 0b11 points to the next-level page table whose base address is encoded in nlta_47_12 (and optionally the DS extension fields). Hierarchical permission fields in bits [63:59] propagate constraints down to every leaf reached through this table.

Enumeration Type Documentation

mem_type_t

enum mem_type_t

Memory type used as an index into the MAIR_EL1 register.

The numeric value of each enumerator directly corresponds to the MAIR_EL1 attribute index encoded in page/block descriptor bits [4:2] (AttrIndx). The kernel must program MAIR_EL1 so that each index carries the correct attribute byte before the MMU is enabled.

Enumerator
DEVICE	Index 0 — MAIR_EL1[7:0]: 0x00 Device-nGnRnE (non-gathering, non-reordering, no early write-ack).
NORMAL	Index 1 — MAIR_EL1[15:8]: 0xFF Normal Inner/Outer Write-Back Read/Write-Allocate Cacheable.

Function Documentation

dump_memory_map()

void dump_memory_map

(

page_table_t *

root

)

Dump the memory map for debugging.

Parameters

root	Pointer to the root page table to dump.

map_page()

bool map_page	(	page_table_t *	root,
		virt_addr	v_addr,
		phy_addr	phy_addr,
		page_permissions_t	perms,
		mem_type_t	mem_typ
	)

Map a virtual address to a physical address in the page table.

Walks the four-level (L0→L3) translation table rooted at root, allocating intermediate table descriptors as needed, and installs a leaf page descriptor at L3 that covers the 4 KB page containing v_addr. The descriptor's AttrIndx field is set from mem_typ, selecting the matching MAIR_EL1 slot (see mem_type_t).

Parameters

root	Pointer to the root (L0) page table. Must not be NULL.
v_addr	Virtual address to map; only bits [47:12] are significant (the 4 KB page base — lower bits are ignored).
phy_addr	Physical address of the target frame; must be 4 KB-aligned.
perms	Software permission flags (page_permissions_t) that are translated into the AP[2:1], PXN, and UXN hardware fields.
mem_typ	Memory type index (mem_type_t) written into AttrIndx[2:0] of the leaf descriptor, selecting the MAIR_EL1 attribute byte (e.g. DEVICE → 0x00 Device-nGnRnE, NORMAL → 0xFF Normal WB-RWA Cacheable).

Returns

true Mapping installed successfully.

false root was NULL, v_addr/phy_addr were not 4 KB aligned, or allocation of an intermediate table failed.

setup_kernel_id_map()

bool setup_kernel_id_map

(

phy_addr

serial_device_addr_base

)

Set up the initial identity-mapped region for the kernel.

Creates the early page-table mappings needed during low-virtual-address boot, including the serial-device mapping used by the early console.

Parameters

serial_device_addr_base

Physical base address of the serial device to map during early boot.

Returns

true on success, false on failure such as an allocation error or invalid mapping setup.

setup_kernel_map()

bool setup_kernel_map

(

memory_map_t *

mmap

)

Set up the kernel's higher-half virtual-memory map.

Maps every region described by mmap into the higher half, giving pages within the kernel image RWX permissions and all other pages RW.

Parameters

mmap	Pointer to the memory map structure describing the available physical-memory regions.

Returns

true on success, false on failure such as an empty memory map, an allocation error, or an invalid mapping configuration.