Fichiers
ui/README.md
T
2026-10-11 01:55:22 +02:00

201 lignes
9.5 KiB
Markdown

# proj3
> **`proj3` est un PLACEHOLDER.** Le nom officiel du projet n est pas arrete.
> Il apparait comme prefixe de namespace, prefixe de symbole assembleur, prefixe
> de macro et nom de cible CMake. La liste exhaustive des endroits a substituer
> est en fin de ce fichier, section « Substitution du nom ».
Environnement graphique deterministe pour ARM64 (AArch64) sur noyau Linux.
Cible de prototypage : Google Pixel 3a (`sargo`). Cible ulterieure : Poco F5 Pro
(`mondrian`).
## Les trois piliers
1. **Determinisme de latence.** Ce qui compte est la variance, pas le debit
moyen. Toute construction a variabilite non bornee est rejetee, meme si elle
est plus rapide en moyenne.
2. **Budget memoire explicite.** Aucune allocation dynamique apres l init. Tout
est prealloue en arenes de taille fixe.
3. **Acces direct justifie.** Chaque couche traversee doit etre justifiee. Pas
de libc, pas de framework, pas de dependance externe.
## Arborescence
| dossier | contenu |
|---|---|
| `src/` | code C++ (`src/proj3/` : `base`, `sys`, `mem`, `font`, `render`, `boot`) |
| `asm/` | code assembleur AArch64 (`.S`) ; `asm/host/` contient la seule exception x86-64, expliquee plus bas |
| `doc/` | conventions, decisions (`doc/adr/`), notes de methode |
| `test/` | harnais de test : oracle, arenes, syscalls, portage du rasterizer |
| `tools/` | outillage de developpement (generateur de references depuis Gastinel Write) |
| `cmake/` | fichiers de toolchain de cross-compilation |
## Documents de reference
| document | ce qu il fixe |
|---|---|
| [`doc/convention-aarch64.md`](doc/convention-aarch64.md) | AAPCS64, conventions internes, nommage des symboles, regles NEON. Fait autorite sur tout `.S`. |
| [`doc/convention-syscall.md`](doc/convention-syscall.md) | remontee d erreur syscall. **Decision definitive, une seule convention.** |
| [`doc/methode-oracle.md`](doc/methode-oracle.md) | validation croisee C++ / assembleur, comment ajouter une paire |
| [`doc/memoire.md`](doc/memoire.md) | trois modes de pages, cinq arenes, garde-fou d allocation |
| [`doc/adr/`](doc/adr/) | ADR-0001 socle, ADR-0002 wrappers asm, ADR-0003 arenes, ADR-0004 portage |
## Construction
### Prerequis Debian / Ubuntu
```bash
sudo apt install cmake ninja-build
```
Puis **au choix**, une des deux familles de toolchain :
```bash
# Famille 1 (recommandee sous Debian) : GCC croise
sudo apt install g++-aarch64-linux-gnu binutils-aarch64-linux-gnu
# Famille 2 : Clang/LLVM monolithe (un seul paquet pour toutes les cibles)
sudo apt install clang lld llvm
```
Le paquet **`g++-aarch64-linux-gnu`** est celui qui fournit le
cross-compilateur `aarch64-linux-gnu-g++`. Aucun sysroot n est necessaire : le
binaire est `-nostdlib` et n a besoin d aucune bibliotheque cible.
Pour executer le harnais de syscalls sans materiel ARM :
```bash
sudo apt install qemu-user
```
### Cible embarquee (AArch64, le produit)
```bash
cmake -S . -B build-arm64 -G Ninja \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-aarch64-linux.cmake
ninja -C build-arm64
```
La famille de toolchain est choisie automatiquement (GCC croise s il est
present, Clang sinon) et peut etre forcee par `-DPROJ3_TOOLCHAIN=gcc` ou
`-DPROJ3_TOOLCHAIN=clang`. **Aucun chemin n est en dur** : le fichier de
toolchain cherche dans le `PATH`.
Binaires produits :
| binaire | role |
|---|---|
| `proj3_boot` | le produit. Acquiert la memoire, journalise le mode de pages, termine avec le code 0. |
| `proj3_test_syscalls` | harnais des wrappers syscall |
| `proj3_oracle_target` | harnais d oracle, versions assembleur AArch64 comprises |
### Cible hote (outillage et tests)
```bash
cmake -S . -B build-host -G Ninja
ninja -C build-host
ctest --test-dir build-host --output-on-failure
```
### Verifier que le binaire ne depend de rien
```bash
llvm-readelf -h build-arm64/proj3_boot # Type EXEC, Machine AArch64
llvm-readelf -d build-arm64/proj3_boot # aucune section .dynamic
llvm-nm -u build-arm64/proj3_boot # aucun symbole indefini
```
(ou `readelf` / `nm` prefixes `aarch64-linux-gnu-` avec la toolchain GCC.)
### Executer le harnais de syscalls
Sur n importe quel Linux AArch64 — Raspberry Pi 64 bits, VM, conteneur — ou
sous emulation utilisateur. **Pas besoin du telephone.**
```bash
qemu-aarch64 build-arm64/proj3_test_syscalls ; echo "code=$?"
```
## Double cible : une asymetrie assumee
Il y a **deux cibles, et elles n ont pas les memes droits** :
- **Cible embarquee** (`aarch64-linux`, freestanding) : le produit. `-nostdlib`,
pas de libc, point d entree `_start` maison, syscalls maison.
- **Cible hote** (la machine de dev) : l outillage seul. **Elle a le droit
d utiliser la libc de l hote.** Elle ne produit jamais de binaire livre.
La raison est simple : le harnais d oracle doit pouvoir tourner sans telephone,
sans affichage et sans emulateur, sinon il ne sera pas execute.
La frontiere est materialisee dans `CMakeLists.txt` par la liste
`proj3_portable_sources`. Ces unites sont freestanding par construction et
compilees a l identique par les deux cibles ; ce sont les seules partagees.
Tout le reste est specifique a une cible et **le nom du fichier le dit** :
`page_source_linux.cpp` contre `page_source_host.cpp`, `panic.cpp` contre
`panic_host.cpp`.
Consequence visible : `asm/host/demo_fill_x86_64.S`. La machine de dev ne peut
pas executer de l AArch64 ; pour que la preuve « le harnais sait rejeter une
implementation fausse » puisse etre faite sur la machine de dev, la paire de
demonstration existe dans les deux jeux d instructions. **Ce doublon ne sera pas
etendu** aux vraies routines : cf. `doc/methode-oracle.md` section 7.
## Dette technique — inventaire
Rien de ce qui suit n est implicite. Chaque point est aussi documente a
l endroit du code concerne.
### Heritee de Gastinel Write, CONSERVEE VOLONTAIREMENT
| dette | ou | statut |
|---|---|---|
| **Pas de crenage** (ni `kern` ni GPOS) | `font/ttf.hpp` | volontaire cote Write, non corrigee ici |
| **Pas d antialiasing** : couverture binaire 0 ou 255 | `render/rasterizer.hpp` | volontaire cote Write, non corrigee ici |
| **Pas de hinting** : les instructions `fpgm`/`prep`/`cvt` sont ignorees | `font/ttf.hpp` | volontaire cote Write, non corrigee ici |
| Polices CFF / CFF2 / WOFF / TTC refusees | `font/ttf.cpp` | refus explicite avec message utile |
| Alignement composite par indices de points non gere | `font/ttf.cpp` | rarissime hors CJK ancien |
### Introduite ou heritee du socle
| dette | ou | pourquoi elle existe |
|---|---|---|
| `clock_gettime` passe par un vrai `svc`, **pas par le vDSO** | `asm/syscall.S` | le vDSO demande de parcourir l auxiliary vector et de resoudre un symbole ELF ; hors perimetre du chantier 2. A traiter au chantier de mesure de latence, la ou ca comptera. |
| `_start` **ne parcourt pas `.init_array`** | `asm/start.S` | le projet n a aucun constructeur statique non trivial. Verifie : `llvm-readelf -S` ne montre aucune section `.init_array` dans `proj3_boot`. Si un jour il en fallait un, l ADR-0001 devrait etre revise. |
| `memcpy` / `memset` / `memmove` / `memcmp` fournis a la main | `base/cstring.cpp` | le compilateur peut les emettre de lui-meme meme en `-ffreestanding`. Implementations naives, octet par octet : ce sont des candidats evidents pour une paire d oracle et un noyau NEON. |
| `std::hypot` remplace par un calcul naif en `double` | `base/math.hpp` | pas de libm. **Seule divergence numerique connue du portage.** Verifiee nulle sur le jeu de test golden (120 combinaisons glyphe/taille). |
| Enregistrement des paires d oracle : deux mecanismes selon la cible | `test/oracle/oracle.hpp` | section ELF `proj3_pairs` sur la cible (pas de `.init_array`), constructeur statique sur l hote (PE ne synthetise pas `__start_`/`__stop_`). |
| Une variable globale mutable : le mode de pages retenu | `mem/page_source_*.cpp` | seule entorse a « pas de `.data` mutable ». Ecrite une fois a l init, lue ensuite. Justifiee dans le fichier. |
| Le harnais d oracle detourne l arene `scanout` pour lire des fichiers | `test/test_raster_golden.cpp` | detournement local a un test, assume. |
| Pas de mesure de latence, pas de DRM/KMS, pas de `/dev/input` | — | hors perimetre : depend de verifications materielles non faites sur le Pixel 3a. |
## Licence des polices
`test/data/Inter-Regular.ttf` est distribue avec le depot pour le test de
portage du rasterizer. **Inter est sous SIL Open Font License 1.1** ; le texte
integral de la licence accompagne la police dans `test/data/OFL.txt`, comme
l OFL l exige (clause 2 : la notice de copyright et la licence doivent
accompagner toute redistribution).
Copyright (c) 2016 The Inter Project Authors — https://github.com/rsms/inter
## Substitution du nom
`proj3` doit etre remplace partout ci-dessous quand le vrai nom sera arrete :
| ou | forme |
|---|---|
| `src/proj3/` | nom du dossier |
| tous les `#include "proj3/..."` | chemin d inclusion |
| `namespace proj3` et ses sous-namespaces | `proj3::sys`, `proj3::mem`, `proj3::font`, `proj3::render`, `proj3::oracle` |
| `asm/*.S` | symboles `proj3_sys_*`, `proj3_fill_bytes_*`, `_start` (inchange) |
| `src/proj3/sys/syscall_nr.hpp` | macros `PROJ3_NR_*`, `PROJ3_AT_FDCWD` |
| `CMakeLists.txt` | `project(proj3)`, cibles `proj3_*`, variables `PROJ3_*` |
| `test/oracle/oracle.hpp` | macro `PROJ3_ORACLE_PAIR`, section ELF `proj3_pairs` |
| `mem/new_guard.cpp`, `sys/panic.cpp` | prefixe des messages `proj3:` |
| ce README et les documents de `doc/` | texte |
La section ELF `proj3_pairs` est le seul endroit ou le nom a une contrainte
technique : il doit rester un **identifiant C valide**, sans quoi l editeur de
liens ne synthetise plus `__start_` / `__stop_`.