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