# Convention de remontee d erreur syscall — decision definitive Statut : **arrete**. Une seule convention dans tout le projet. Tout code qui appelle un wrapper syscall suit celle-ci, sans exception ni variante locale. --- ## 1. Le probleme Le noyau Linux ne dispose pas d `errno`. Sur AArch64, `svc #0` place dans `x0` soit le resultat de l appel, soit **l oppose du code d erreur**. Un resultat est une erreur si et seulement si : ``` -4095 <= x0 <= -1 ``` La borne `-4095` n est pas decorative : `MAX_ERRNO` vaut 4095 dans le noyau (`include/linux/err.h`), et c est exactement ce que fait la macro `IS_ERR_VALUE`. Certains appels retournent legitimement des valeurs negatives hors de cette plage — `lseek` sur un fichier de plus de 8 exaoctets, `mmap` retournant une adresse dont le bit 63 est a 1 sur une configuration a 64 bits d espace utilisateur. Un test approximatif du genre `if (ret < 0)` est donc **faux**, pas seulement imprecis. C est la libc qui, normalement, traduit cela en `-1` + `errno`. Sans libc, il faut choisir. --- ## 2. Options envisagees ### Option A — Valeur sentinelle plus etat global (mimer errno) Le wrapper retourne `-1` en cas d echec et depose le code dans une variable globale `proj3_last_errno`. | Pilier | Evaluation | |---|---| | 1. Determinisme de latence | Neutre en soi, mais impose une variable globale mutable. Des qu on aura plus d un fil d execution ou un gestionnaire de signal, il faut du stockage par contexte : c est le chemin qui mene a `__errno_location()`, donc a un appel indirect non inlinable sur le chemin chaud. | | 2. Budget memoire explicite | Une section `.data`/`.bss` mutable hors arene. Contredit directement la regle "toute donnee mutable vit dans une arene" (`convention-aarch64.md` 3.3). | | 3. Acces direct justifie | C est reconstruire la couche libc qu on a explicitement decide de ne pas avoir. Abstraction non justifiee. | Verdict : **rejetee**. Elle detruit l information (deux appels, le second ecrase le code du premier) et introduit un etat global cache. ### Option B — Structure de retour `{ valeur, code_erreur }` Le wrapper retourne un agregat de deux `i64`. | Pilier | Evaluation | |---|---| | 1. Determinisme de latence | Un agregat de 16 octets rentre dans `x0`+`x1` en AAPCS64, donc pas de retour indirect ni de trafic memoire. Cout nul en theorie. En pratique, cela oblige chaque wrapper assembleur a produire deux registres, donc a tester la plage d erreur **dans** le wrapper : une comparaison et un `csel` par appel, meme quand l appelant ignore l erreur. | | 2. Budget memoire | Rien a allouer. Correct. | | 3. Acces direct | La valeur brute rendue par le noyau est deja porteuse des deux informations. Les scinder puis les recombiner cote appelant est du travail ajoute pour rien. | Verdict : **rejetee**, mais de peu. Le seul reproche serieux est le travail inconditionnel dans le wrapper alors que la meme information est disponible gratuitement. ### Option C — Valeur brute du noyau, encapsulee dans un type a cout nul Le wrapper retourne exactement ce que `svc #0` a mis dans `x0`, tel quel. Cote C++, ce `i64` est enveloppe dans une structure d un seul membre, `proj3::sys::Result`, dont toutes les methodes sont `constexpr` et inlinees : `is_err()`, `err()`, `value()`, `ptr()`, `fd()`. | Pilier | Evaluation | |---|---| | 1. Determinisme de latence | Le wrapper assembleur ne fait **rien** apres le `svc` : `svc #0 ; ret`. Cout strictement minimal et constant. Le test de plage n est paye que par l appelant qui le demande. | | 2. Budget memoire | Aucun etat, aucune allocation, aucune section mutable. | | 3. Acces direct | Zero couche : la valeur traversee est celle du noyau, bit pour bit. La structure n existe qu au niveau du type, pas a l execution (`sizeof == 8`, trivialement copiable, passee en registre). | Verdict : **retenue.** --- ## 3. Convention retenue ### 3.1 Cote assembleur Chaque wrapper est de la forme : ```asm proj3_sys_: mov x8, #PROJ3_NR_ svc #0 ret ``` Aucune transformation. La valeur de retour est le `x0` du noyau. Consequence directe : **aucun wrapper n a de prologue, ne touche a `sp`, ni n empile `x30`.** L alignement de pile est preserve trivialement. ### 3.2 Cote C++ ```cpp namespace proj3::sys { // Valeur de retour brute d un appel systeme Linux. // sizeof == 8, trivialement copiable : passee et rendue en registre. struct Result { i64 raw; // Plage d erreur exacte du noyau : [-4095, -1]. Ni approximative, // ni "raw < 0". constexpr bool is_err() const { return raw < 0 && raw >= -4095; } constexpr bool is_ok() const { return !is_err(); } // Code errno positif. Precondition : is_err(). constexpr i32 err() const { return static_cast(-raw); } // Valeur utile. Precondition : is_ok(). constexpr i64 value() const { return raw; } constexpr i32 fd() const { return static_cast(raw); } void* ptr() const { return reinterpret_cast(raw); } }; } ``` ### 3.3 Regles d usage — obligatoires 1. **Toute valeur `Result` est testee avec `is_err()` avant tout usage de `value()`, `fd()` ou `ptr()`.** Il n existe pas de conversion implicite vers un entier ou un booleen : le type ne se laisse pas utiliser par accident. 2. **Ignorer un `Result` est explicite.** Le type est marque `[[nodiscard]]` ; l ignorer demande d ecrire `(void)`. Le seul cas ou c est legitime est `close()` en chemin de sortie. 3. **Aucun code du projet ne stocke un `errno`.** Un code d erreur est traite la ou il apparait : soit il est recuperable et le chemin de repli est pris sur place (c est le cas du repli `MAP_HUGETLB` -> THP -> `mmap` simple), soit il ne l est pas et on appelle `panic()` avec le nom de l appel et le code. Rien n est mis de cote pour plus tard. 4. **`EINTR` n est jamais reessaye en boucle silencieuse.** Une boucle de retry est une latence non bornee, donc une violation du pilier 1. Le projet n installe aucun gestionnaire de signal ; si `EINTR` apparait, c est un evenement inattendu et il doit remonter. 5. Les constantes `errno` utilisees sont definies dans `src/proj3/sys/errno.hpp`, avec leur source. On ne definit que celles qu on teste effectivement. ### 3.4 Ce que cette convention coute - L appelant doit se souvenir que `mmap` peut legitimement rendre un pointeur dont la valeur signee est negative hors plage d erreur. `is_err()` gere ce cas correctement, mais un appelant qui ecrirait `if (r.raw < 0)` a la main aurait tort. C est le seul piege, et il est nomme ici. - Il n y a pas de message d erreur lisible associe a un code. On imprime le numero. Une table `errno -> chaine` couterait plusieurs kilooctets de `.rodata` pour du confort de debogage ; si elle devient necessaire, elle sera conditionnee a un build de debogage, par un ADR.