vystem/docs/shelter/memmap.md

Shelter kernel memory map layout

Introduction

In order to transmit efficiently the EFI memory map to the kernel, Shelter have his own memory map layout that need to be created from the EFI memory map in order for Shelter to understand it. For details about mapping the Shelter memory map inside the kernel virtual memory space, please see boot contract docs.

Header

The Shelter memory map is first assigned a buffer of 64 kilobytes or 16 pages mapped with non-execution and read only permissions. Each memory map has an header described by the following C structure (sourced from shelter/lib/include/memory/page.h)

#pragma pack(1)
typedef struct {
  sh_uint8 sig_start[8];
  sh_uint64 entry_count;
  sh_uint64 entry_size;
  sh_uint8 mmap_syntax_version;
} sh_page_MEMORY_MAP_HEADER;
#pragma pack()

Each field is packed inside the struct. The signature must be SheMmapB. The number of entry is indicated inside the entry_count field. The size of an entry is indicated inside the entry_size field. Both of these fields are little endian 8 bytes unsigned integer. The mmap_syntax_version is always set to 0x01, as the current version of the Shelter memory map syntax. The kernel also compute the total size of the memory map (header + all entries) and raise an error if it's above the size of the memory map buffer.

Entries

After the header, there are entries that describe which part of the physical memory is currently unusable (due to various factors like ACPI table, etc). A entry is described by the following C structure:

#pragma pack(1)
typedef struct {
  sh_uint32 type;
  sh_uint64 physical_start;
  sh_uint64 pages_count;
  sh_uint64 attributes;
} sh_page_MEMORY_MAP_ENTRY;
#pragma pack()

Each field is packed inside the struct. The type field is a 4 bytes unsigned integer that give the type of the region, as the EFI specification specify it. The physical_start field is a 8 bytes unsigned integer that contain the physical address of the start of the region. The pages_count field is a 8 bytes unsigned integer that contain the number of 4 kilobytes pages that constitute the region. The attributes field contain any other attributes provided by the UEFI firmware. All fields are in little endian.