# 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.