# Shelter kernel boot configuration

## Introduction

The Shelter kernel requires a boot configuration in order to start. It doesn't come under the form of a command line but under the form of a C struct. For details on how to transmit the configuration to the kernel, please see [boot contract docs](bootcontract.md).

## Overview

Shelter boot configuration come under the following layout (extracted from `shelter/lib/include/kernel/conf.h`) :
``` C
typedef struct __attribute__((aligned(8))) {
  sh_uint8 sig_start[8];
  sh_uint8 log_level;
  sh_uint16 page_table_allocator_level;
  sh_page_PHYSICAL_ADDRESS page_table_pool_pa;
  sh_page_VIRTUAL_ADDRESS page_table_pool_va;
  sh_bool test_benchmark;
  sh_uint64 bench_iterations;
  sh_bool log_disable_serial_port;
  sh_bool disable_serial_port;
  sh_uint16 log_ring_size;
  sh_uint64 acpi_rsdp;
  sh_uint8 acpi_ver;
  sh_uint16 kbd_events_queue_capacity;
  sh_conf_FB_CONFIG fb_config;
  sh_uint8 sig_end[8];
} sh_conf_BOOT_CONFIG;
```

The starting signature must be `ShCfgBeg` in ASCII and the starting signature must be `ShCfgEnd` in ASCII. The alignment to respect for the boot config is 8 bytes.

## List of all keys

**log_level:**
- Type: 1 byte unsigned integer
- Description: represent the minimal (inclusive) log level for any log payload to be logged, can range from 0 to 6. The value of this key is provided by the `kernel_log_level` from the Blastproof boot config

**page_table_allocator_level:**
- Type: 2 bytes unsigned integer
- Description: the value of the bumb allocator after all mapping inside the kernel boot PTP

**page_table_pool_pa:**
- Type: physical address, aka 8 bytes unsigned integer
- Description: the physical address of the first page of the kernel boot PTP

**page_table_pool_va:**
- Type: virtual address, aka 8 bytes unsigned integer
- Description: the virtual address of the first page of the kernel boot PTP, inside kernel virtual memory layout

**test_benchmark:**
- Type: boolean, aka 1 byte unsigned integer
- Description: define if the kernel should test and benchmark his subsystems. The value of this key is provided by the `kernel_test_benchmark` from the Blastproof boot config

**bench_iterations:**
- Type: 8 bytes unsigned integer
- Description: define the amount of iterations to apply for compatible benchmarks. Not all benchmarks will follow this value. The value of this key is provided by the `kernel_bench_iterations` from the Blastproof boot config

**log_disable_serial_port:**
- Type: boolean, aka 1 byte unsigned integer
- Description: if true, the kernel will not output his logs on the serial port. The value of this key is provided by the `kernel_log_disable_serial_port` from the Blastproof boot config

**disable_serial_port:**
- Type: boolean, aka 1 byte unsigned integer
- Description: define if the kernel should allow serial port usage. The value of this key is provided by the `kernel_disable_serial_port` from the Blastproof boot config

**log_ring_size:**
- Type: 2 bytes unsigned integer
- Description: define the amount of pages used for logging ring buffer

**acpi_rsdp:**
- Type: 8 bytes unsigned integer
- Description: the physical address of the ACPI RDSP

**acpi_ver:**
- Type: 1 byte unsigned integer
- Description: define the version of ACPI provided by the firmware, can be 1 or 2 depending on the ACPI version GUID found by Blastproof

**kbd_events_queue_capacity:**
- Type: 2 bytes unsigned integer
- Description: the capacity of each keyboard events queue. The value of this key is provided by the `kernel_kbd_events_queue_capacity` from the Blastproof boot config

**fb_config:**
- Type: custom struct
- Description: informations on the early boot framebuffer, intended to work with GOP framebuffer information

## FB config structure

The `fb_config` structure is defined like that:
``` C
typedef struct __attribute__((aligned(8))) {
  sh_bool fb_present;
  sh_page_VIRTUAL_ADDRESS fb_pa;
  sh_uint32 white_pixel_value;
  sh_uint32 gray_pixel_value;
  sh_uint64 size_in_bytes;
  sh_uint32 fb_height;
  sh_uint32 fb_width;
  sh_uint16 text_x;
  sh_uint16 text_y;
  sh_uint16 text_width;
  sh_uint16 text_height;
} sh_conf_FB_CONFIG;
```

The `fb_present` field should be set to `false` if anything impeach the framebuffer to be fully operational. The `fb_pa` field is the physical address of the framebuffer. The kernel will map the framebuffer itself. The `white_pixel_value` and `gray_pixel_value` contain the encoded pixel data for the color white and gray. The `text_x`, `text_y`, `text_width` and `text_height` serve the purpose of defining an area that the kernel should erase before starting using the progress bar. They are named like that because most of the time, it will be a text placed by the bootloader that the kernel should erase. Others fields are self-explenatory.
