First commit, Vystem v0.1

docs/vyld/index.md

@@ -0,0 +1,5 @@
+# Vyld Docs
+
+Vyld, standing for Vystem Linker, is a specialised linker designed to convert ELF binaries to the VYX executable format. This documentation is divided into two parts:
+- [The VYX executable format](vyx.md)
+- [The Vyld utility](vyld.md)

docs/vyld/vyld.md

@@ -0,0 +1,67 @@
+# Vyld Docs
+
+## Introduction
+
+Vyld, standing for Vystem Linker, is the utility responsible for creating VYX executable from ELF binaries. Vyld has been intended to be used only on a regular Linux system. For a better understanding, it's recommanded you read the [VYX format docs](vyx.md) first.
+
+## Detailled informations
+
+Folder: `vyld`
+Source code file: `vyld.cpp`
+
+For building the `vyld` utility, use the following command:
+``` bash
+g++ vyld.cpp -o vyld
+```
+
+External library:
+- ELFIO, made by Serge Lamikhov-Center, sourced from [serge1/ELFIO](https://github.com/serge1/ELFIO), under the MIT license
+
+## Usage
+
+Requirement: having the `gcc` compiler and `ld` linker reachable in path. For the moment, only the `gcc` compiler is supported.
+
+The `vyld` utility can be used like this:
+``` bash
+vyld <path to C file 1> <path to C file 2> ... <path to C file n> <path to output file>
+```
+
+Each path provided except the last one has to be C file, or else the compilation might fail. The last path can be any extension, but for standard respect, it should be a VYX file.
+
+Vyld can accept custom compilation flags for provided C files if they are passed by using the `VYLD_COMPILATION_FLAGS` environnement variable. They are added to the mandatory compilation flags for provided C files but they will not replace them. The mandatory compilation flags for provided C files are:
+``` bash
+-fno-pic -m64 -mcmodel=large
+```
+
+The mandatory compilation flag for the `_vyx_start.c` entry point are:
+``` bash
+-ffreestanding -nostdlib -nostartfiles -Wall -Wextra -fno-stack-protector -fno-builtin -fno-pic -m64 -mcmodel=large
+```
+These flags aren't applied to provided C files unless passed inside `VYLD_COMPILATION_FLAGS`.
+
+Vyld need to have access to the `_vyx_start.c` file in his executable directory in order to compile any VYX binary. This file is the entry point of any VYX executable.
+
+Command example:
+``` bash
+vyld hello.c io.c binary.vyx
+VYLD_COMPILATION_FLAGS="-Wall -Wextra -Werror -Wpedantic" vyld hello.c io.c binary.vyx
+```
+
+We plane to expand drastically the capabilities and versatility of the `vyld` utility and the VYX format in the future, but for the moment, it's sufficient for what we need (loading the Shelter kernel).
+
+## Detailled generation processus
+
+1) Obtaining his own executable path by reading `/proc/self/exe` in order to obtain a deterministic working directory
+2) Searching for flags provided into the `VYLD_COMPILATION_FLAGS`
+3) Checking for existence of `_vyx_start.c ` and compiling it into `_vyx_start.o` using mandatory compilation flags for entry point. The resulting object file is stored inside the `vyld` executable directory
+4) Iterating for each provided C files: finding his location and generating his output name under the format `<file name without .c extension>.o`
+5) Iterating for each provided C files: compiling each C file into an object file using mandatory compilation flags for provided C files and flags passed through `VYLD_COMPILATION_FLAGS`. The resulting objects files are stored inside the `vyld` executable directory
+6) Combining all objects files (entry point and all provided files under their object form) into one object file named `combined.o` and stored inside the `vyld` executable directory. For that, we use the `gcc -r` feature of `gcc`. The entry point object file is specifically added in first position
+7) Opening `combined.o` and obtaining sections size for `.text`, `.data`, `.rodata` and assimiled sections as well as `.bss` section. Padding these sizes to the nearest multiple of 4096 bytes superior to these sizes
+8) Generating the `.text` section base virtual address (VA) and stack base VA, aligned on 4096 bytes pages
+9) Generating a custom linker script to correctly link the `combined.o` file with the right VAs inside the code and putting in order all the sections into the final binary
+10) Linking the `combined.o` file into an ELF executable named `compiled.elf` and stored inside the `vyld` executable folder
+11) Opening the `compiled.elf` binary, extracting all sections, generating VYX header and executable
+
+The range for generating `.text` section base is currently `0xFFFF800000000000` to `0xFFFF900000000000-1`, then padded to the nearest page boundary.
+The range for generating stack base is currently `0xFFFFF00000000000` to `0xFFFFFF8000000000-0x100000`, then padded to the nearest page boundary.

docs/vyld/vyx.md

@@ -0,0 +1,32 @@
+# The VYX executable format
+
+## Introduction
+
+The VYX format, standing for Vystem Executable, is a very simple binary format made for simple binary loading from any environnement. As long as you can access the `.vyx` file, you can load a VYX binary. 
+
+## Header
+
+Because VYX format has been designed to provide a simple way to load any kind of binary, we wanted to make it as easely updatable as possible. For the moment, it's just a very simple format built for loading the Shelter kernel, but in a few updates, it will be use for loading all kind of binaries. No spoiler on that. The header is designed like that:
+- Signature: three bytes spelling `VyX` in ASCII
+- VYX format version: the version of the VYX format used in the binary, represented as an uint16_t. Depending on the version number, the following structure will probably changed a lot. The current version is `0x0001`.
+- `.text` base address: the virtual address (VA) at which the `.text` should be loaded. It should be aligned on the boundary of a 4 kilobytes page. Represented as an uint64_t
+- stack base: the VA at which the stack base should be setuped. Be careful, it indicate the base, not the top. It should be aligned on the boundary of a 4 kilobytes page. Represented as an uint64_t
+- the size of the `.text` section: It should be aligned on a multiple of 4096 bytes. Represented as an uint64_t
+- the size of the `.data` section: It should be aligned on a multiple of 4096 bytes. Represented as an uint64_t
+- the size of the `.rodata` section: It should be aligned on a multiple of 4096 bytes. Represented as an uint64_t
+- the size of the `.bss` section: It should be aligned on a multiple of 4096 bytes. Represented as an uint64_t
+
+All the multibytes integers should be written in little endian. The VYX executable format has been made for x86-64 only binary.
+
+## Sections organizations
+
+The VYX format only support three sections inside the binary that should be in the following order: `.text`, `.data`, `.rodata`. The `.bss` should be initialized and zeroed by the loader just after the `.rodata` section. The space occupied by the three sections inside the binary should occupy a multiple of 4096 bytes, according to the size indicated in the header, padded with zeroes if necessary.
+For example, if each sections take 2 pages, after being padded to the nearest multiple of 4096 bytes superior to their real size, and that the `.text` base is 0x1000, `.text` should be located at 0x1000, `.data` at 0x3000, `.rodata` at 0x5000 and `.bss` at 0x7000
+
+## Specifications
+
+The VYX binaries use the SystemV ABI. They doesn't support rellocations nor dynamic linking. While relative addressing into the binary code is theorically working, all the Vystem binaries will be compiled 64 bits static addressing with position-dependent code (non-PIC), especially the kernel. That why respecting the indicated `.text` section base and order of sections loading is extremely important.
+Obviously, the right privileges should be applied in term of pagging: no execution unless `.text` pages, read only `.text` and `.rodata` sections, read-write `.data` and `.bss` sections.
+For the moment, the entry point is located at the base of the `.text` section.
+The stack size can be decided at the convenience of the loader, but the stack size used for the Shelter kernel is, for the moment, 256 kilobytes. The stack growing downward, the initial stack pointer should be set to stack base + stack size.
+A reference implementation of a VYX loader, exploiting all currently documented features, can be found into the Blastproof bootloader source code.