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

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 :

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++

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.