Fichiers
ui/doc/convention-syscall.md
2026-10-11 01:55:22 +02:00

153 lignes
6.7 KiB
Markdown

# 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_<nom>:
mov x8, #PROJ3_NR_<nom>
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<i32>(-raw); }
// Valeur utile. Precondition : is_ok().
constexpr i64 value() const { return raw; }
constexpr i32 fd() const { return static_cast<i32>(raw); }
void* ptr() const { return reinterpret_cast<void*>(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.