First commit, Vystem v0.1

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.