vystem/docs/shelter/keycard.md

Kernel bootstrapping using keycard

Introduction

Shelter being a kernel that need to start with pagging enabled, it need to have a intermediary program to safely jump to it: Keycard. Keycard and Shelter have been designed and thinked for x86-64 only.

Overview

Keycard is a very simple assembly program with the following role in the following order:

• loading the kernel page table and enabling pagging
• loading and aligning the kernel stack
• jumping to kernel entry point

In order to achieve that, it need to be identity mapped into virtual lower half into the kernel page table, using a physical address provided by UEFI firmware. The bootloader map it into a page (keycard compiled code fit into a single page) with allowed execution but read-only. It also have a kind of 'ABI' which specify which value to put into which register before jumping to Keycard:

• rax: should contain the stack top virtual address (VA)
• rbx: should contain the physical adrdess of the page table root
• rcx: should contain the VA of the kernel entry point

Due to security concerns, the keycard.bin file contain the compiled code of Keycard and is stored inside the InitFS with the kernel VYX executable.

The Keycard source code is stored inside Blastproof/src/keycard.asm.