# 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 easily 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 `0x0002`.
- `.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 setup. Be careful, it indicates 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
- the number of payloads integrated into the VYX file. 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

## Payloads

The VYX format now support, as of `0x0002` version, the integration of payloads. There are additionnal ressources that the VYX loader need to discover.

This discovery process is started from the end of the `.rodata` section. The loader need to look for the signature `VPAYLOAD` in ASCII. Once localised, the loader know it has found a payload header, which is structured like this:
- Signature: 8 bytes
- Payload size in bytes: represented as an uint32_t
- Payload size in amount of 4 kilobytes pages: represented as an uint32_t
- Payload mapping flags: 1 byte specifying how the VYX loader should map the payload in the virtual address space of the program being loaded:
  - Bit 0: if 1, the payload should be mapped as executable data
  - Bit 1: if 1, the payload should be mapped as writable data
- Payload virtual address! the address at which the payload should be mapped by the VYX loader. Should be aligned on 4 kilobytes pages frontier and shouldn't be in reserved virtual address space for program image and stack

Then, for the indicated payload size in bytes, the VYX loader should extract the payload (that come immediately after the payload header) and map it accordingly. Restriction can be applied on mapping flags depending on the VYX loader context.

If the payload size in bytes is bigger that the remaining size in bytes into the VYX file, it indicates VYX file corruption. The discovery process continue as long as the amount of payloads discovered isn't the same as indicated into the header.

## Specifications

The VYX binaries use the SystemV ABI. They doesn't support rellocations nor dynamic linking. While relative addressing into the binary code is theoretically 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.
