Important Concepts#

• The linker script (asm/linker.ld) does not execute. It tells the linker how to arrange the kernel’s code and data in the resulting executable.
• The boot assembly (asm/boot.S) does execute. However, something must first load its machine code into memory and transfer control to it.
• The boot sequence depends on the boot protocol. A bootloader may configure the CPU and memory before entering the kernel, so asm/boot.S does not necessarily perform every startup task.
• The Rust kernel entry point runs after the required startup state has been established.

Boot Flow#

BIOS / UEFI
    |
    v
Bootloader
    |
    | Loads kernel into RAM
    v
Kernel image arranged by the linker
    |
    v
asm/boot.S
    |
    | Sets up required CPU state
    v
Rust kernel entry point
    |
    v
Operating system initialization

Note: asm/linker.ld is used during linking, not as a runtime step. It determines the kernel image’s layout; it does not sit between the bootloader and assembly as an executable stage.

1. Firmware: BIOS or UEFI#

Initializes hardware and selects a boot device

2. Bootloader#

Loads the kernel ELF segments into physical RAM

3. asm/linker.ld#

Defines the kernel’s linked memory layout and entry symbol

4. asm/boot.S#

Establishes stack, page tables, CPU mode and other startup state, if implemented there

5. Rust kernel entry point#

Initializes kernel facilities and begins running OS code

The linker script doesn’t execute. It tells the linker how to arrange the kernel. The boot assembly does execute, but only after something has loaded it and transferred control to it.

What each directive means#

Why start at 1 MiB? It is a common conventional physical load address for x86 kernels. The low-memory region contains firmware data structures and other historically important areas, so kernels often avoid placing their main image there. The exact address is a bootloader and linker design decision, not a universal requirement.

• Important: an ELF virtual address, ELF physical load address, and actual runtime virtual address are not necessarily identical. A higher-half kernel, for example, may be loaded into low physical RAM but linked to execute at a much higher virtual address.

3.1 Example Physical RAM Layout#

The following addresses are illustrative for a simple kernel linked near 1 MiB. They are not a dump of the current machine’s memory.

The actual addresses, section order, and alignment depend on asm/linker.ld, the ELF file, the boot protocol, and the memory layout established at runtime.

3.2 Important ELF Program-Header Fields#

A loadable ELF segment is typically identified by the PT_LOAD program-header type.

Important: p_vaddr and p_paddr are not necessarily the same. How they are interpreted depends on the loader and boot protocol.

3.3 Example: Loading a Segment into Memory#

Suppose an ELF PT_LOAD segment has these values:

The memory requirement is:

The loader copies the 4096 file-backed bytes into the segment’s load location. The remaining 2048 bytes must be initialized appropriately, commonly by zero-filling them.

This is how zero-initialized storage, such as .bss, can occupy RAM without requiring all of its bytes to be present in the ELF file.

3.4 Inspect the ELF from the CLI#

Run these commands from your project directory:

# Inspect the ELF header and entry point
readelf -h target/x86_64-unknown-none/debug/a02_hello_world

# Inspect sections such as .text, .rodata, .data, and .bss
readelf -S target/x86_64-unknown-none/debug/a02_hello_world

# Inspect loadable segments and their memory sizes
readelf -l target/x86_64-unknown-none/debug/a02_hello_world

Adjust the ELF path to match your actual build output. For example, release builds commonly place the executable under target/x86_64-unknown-none/release/.

• readelf -S displays sections, which organize code and data.
• readelf -l displays program headers, which describe how segments should be loaded.
• readelf -h displays the ELF entry-point address and other file-level metadata.

Key takeaway: The linker defines the layout, the ELF records the layout and loading information, and the bootloader loads the required segments into memory according to the boot protocol.

Step A: Establish a safe starting state#

A boot stub might begin with instructions such as:

cli
cld

• cli clears the interrupt-enable flag, preventing ordinary maskable interrupts from interrupting early initialization.
• cld clears the direction flag so string instructions such as rep stosd proceed forward through memory.

These instructions don’t allocate memory. They establish CPU state.

Step B: Set up a stack#

For example:

mov esp, offset stack_top

This sets the 32-bit stack pointer to the top of a reserved stack region.

A simplified stack definition might be:

.section .bss
.align 16
stack_bottom:
    .skip 16384
stack_top:

Here, .skip 16384 reserves 16 KiB of storage. It doesn’t mean that 16 KiB of stack data is already present in the ELF file. The linker places this storage in the appropriate section, and the loader must provide its memory.

The stack usually grows toward lower addresses:

Higher addresses
+-----------------------+
| stack_top             |  <- initial ESP/RSP
|                       |
|     unused stack      |
|                       |
| function return data  |  <- stack grows down
+-----------------------+
| stack_bottom          |
+-----------------------+
Lower addresses

A function call pushes a return address onto the stack. Function prologues may also reserve space for local variables. Rust code requires a valid stack before ordinary function calls can safely run.

Step C: Build page tables#

In x86-64, paging uses a hierarchy of tables. A basic four-level setup has:

CR3
 |
 v
PML4 (level 4)
 |
 v
PDPT (level 3)
 |
 v
Page Directory (level 2)
 |
 v
Page Table (level 1, if needed)
 |
 v
Physical page

With 2 MiB pages, the page-directory entries can map physical memory without needing a level-1 page table for every 4 KiB page.

For a simple identity mapping, virtual and physical addresses are equal:

Virtual address 0x00100000
          |
          v
Physical address 0x00100000

This makes early execution easier because code and data loaded into low physical memory can be accessed at the same numeric virtual addresses.

For example, mapping the first 1 GiB with 2 MiB pages requires:

$\frac{1\ \text{GiB}}{2\ \text{MiB}} = 512$

That is 512 page-directory entries. Each entry is 8 bytes, so those entries consume 4096 bytes—the size of one page directory.

A page-table entry is not a full allocation of the memory it maps. It is metadata describing a mapping. The physical RAM being mapped is separate from the RAM used by the page tables.

Example kernel memory allocations#

Assume a kernel loaded at 1 MiB with 4 KiB page alignment.

The sample ranges are deliberately illustrative and must not overlap in a real linker layout. Actual addresses come from your ELF, linker script, bootloader, and runtime allocator.

Three different things are happening here:

• Reserving storage: the linker gives the stack and BSS a place in the image’s memory layout.
• Allocating metadata: the boot code reserves page-table pages and fills in mapping entries.
• Mapping physical memory: page tables tell the CPU how virtual addresses correspond to physical addresses.

The bootstrap often reserves page tables and a stack statically rather than asking a dynamic kernel allocator for them. A general-purpose allocator may not exist yet.

What to look for#

• readelf -h: the ELF entry point and architecture.
• readelf -S: .text, .rodata, .data, .bss, and other sections.
• readelf -l: loadable segments and their virtual/physical addresses.
• nm -n: symbol addresses, including _start if present.
• objdump -d -Mintel: the actual machine instructions and the order they execute.

For the runtime memory map, your bootloader’s BootInfo output is another useful source. Its memory_regions describe the memory map the kernel receives; they are not the same thing as the ELF’s section table.

1. Build and Link Order#

The linker script is used during the build process. It does not execute on the CPU.

Rust source code (.rs) ──┐
                        ├──> Compiler / Assembler
Assembly source (.S) ───┘            |
                                     v
                              Object files (.o)
                                     |
                                     v
                           Linker + asm/linker.ld
                                     |
                                     v
                                Kernel ELF

Important: asm/linker.ld is an input to the linker. It is not part of the runtime execution sequence.

2. Runtime Boot Order#

After the kernel image has been built, the machine can boot it.

BIOS / UEFI
    |
    v
Bootloader
    |
    | Loads the kernel image into RAM
    | Prepares the boot environment
    v
Kernel entry point
    |
    v
asm/boot.S              (if the entry point is in this assembly)
    |
    | Initializes required CPU state
    v
Rust kernel entry point
    |
    v
Kernel initialization

The exact runtime sequence depends on the boot protocol and the entry point configured in the ELF file.

3. How the Linker and Runtime Connect#

The linker script can specify an entry symbol, such as:

ENTRY(_start)

The assembly may define that symbol:

.global _start
_start:
    # Startup instructions go here

During linking, the linker records _start as the ELF entry point. At runtime, the bootloader or firmware-aware loader uses the executable’s entry information—or another boot protocol’s specified entry—to determine where to transfer control.

The linker does not call _start. It only records the layout and entry information in the output image.

4. The Complete Picture#

BUILD TIME
==========

Rust (.rs) + Assembly (.S) + Linker Script (.ld)
                       |
                       v
                 Kernel ELF
                       |
                 (build ends)


RUNTIME
=======

Firmware
   |
   v
Bootloader
   |
   v
Assembly entry, if used
   |
   v
Rust kernel entry
   |
   v
Kernel initialization

Remember:

• Linker order describes how source files become a kernel executable.
• Runtime order describes how the computer loads and executes that kernel.
• asm/linker.ld influences the executable’s layout but never executes.
• asm/boot.S is executable machine code, but it runs only if the boot process transfers control to it.

Add this section after 3.1 Example Physical RAM Layout in your README.md. It clarifies the difference between physical addresses and virtual addresses in an x86-64 kernel.

3.2 Physical Addresses vs. Virtual Addresses#

A physical address identifies a location in RAM, while a virtual address is an address used by the CPU when paging is enabled. The CPU’s page tables translate virtual addresses into physical addresses.

Important: The example addresses above are illustrative. A physical address and its corresponding virtual address may be identical or different.

Virtual address:  0x10000000000 + 0x4470
                  = 0x10000004470

Physical address: 0x00600000 + 0x4470
                  = 0x00604470

Rust kernel code
       |
       | Accesses virtual address
       v
+--------------------------+
| CPU MMU                  |
|                          |
| Consults page tables     |
+--------------------------+
       |
       | Translates address
       v
Physical address in RAM

# ELF entry point and file metadata
readelf -h target/x86_64-unknown-none/debug/a02_hello_world

# Section addresses
readelf -S target/x86_64-unknown-none/debug/a02_hello_world

# Segment virtual addresses, physical addresses, and sizes
readelf -l target/x86_64-unknown-none/debug/a02_hello_world

# Symbol addresses
nm -n target/x86_64-unknown-none/debug/a02_hello_world