vystem/docs/vyld/vyld.md

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

Detailled informations

Folder: vyld Source code file: vyld.cpp

For building the vyld utility, use the following command:

g++ vyld.cpp -o vyld

External library:

• ELFIO, made by Serge Lamikhov-Center, sourced from 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:

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:

-fno-pic -m64 -mcmodel=large

The mandatory compilation flag for the _vyx_start.c entry point are:

-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:

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.