air_sys_syscall/

system.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Wrappers de la famille `system`.
//!
//! Cf. `docs/specs/layer-0/family-system.md`.

#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!("air-sys-syscall::system supporte uniquement x86_64 et aarch64 (ADR-014).");

use alloc::ffi::CString;
use core::ffi::CStr;
use core::num::NonZeroI32;

use air_sys_types::Errno;
use air_sys_types::system::{GetrandomFlags, SystemInfo, UtsName};

// ─────────────────────────────────────────────────────────────────────────
// Kernel structs (repr(C), utilisées uniquement localement)
// ─────────────────────────────────────────────────────────────────────────

/// Représentation locale de `struct utsname` (Linux) : 6 champs de 65 octets
/// chacun, chaînes C terminées par NUL.
#[repr(C)]
struct KernelUtsname {
    sysname: [u8; 65],
    nodename: [u8; 65],
    release: [u8; 65],
    version: [u8; 65],
    machine: [u8; 65],
    domainname: [u8; 65],
}

impl KernelUtsname {
    fn zeroed() -> Self {
        Self {
            sysname: [0u8; 65],
            nodename: [0u8; 65],
            release: [0u8; 65],
            version: [0u8; 65],
            machine: [0u8; 65],
            domainname: [0u8; 65],
        }
    }
}

/// Représentation locale de `struct sysinfo` sur LP64 (x86_64 / aarch64).
///
/// Le padding est arch-dépendant. Sur les cibles 64 bits Linux (LP64),
/// la structure fait exactement 112 octets.
#[repr(C)]
struct KernelSysinfo {
    uptime: i64,
    loads: [u64; 3],
    totalram: u64,
    freeram: u64,
    sharedram: u64,
    bufferram: u64,
    totalswap: u64,
    freeswap: u64,
    procs: u16,
    pad1: [u8; 6], // padding d'alignement LP64 jusqu'à l'offset 80
    totalhigh: u64,
    freehigh: u64,
    mem_unit: u32,
    pad2: [u8; 4], // padding final à 112 octets
}

const _: () = assert!(core::mem::size_of::<KernelSysinfo>() == 112);

impl KernelSysinfo {
    fn zeroed() -> Self {
        Self {
            uptime: 0,
            loads: [0; 3],
            totalram: 0,
            freeram: 0,
            sharedram: 0,
            bufferram: 0,
            totalswap: 0,
            freeswap: 0,
            procs: 0,
            pad1: [0; 6],
            totalhigh: 0,
            freehigh: 0,
            mem_unit: 0,
            pad2: [0; 4],
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────
// Helper errno
// ─────────────────────────────────────────────────────────────────────────

fn errno_from_negative_syscall_ret(ret: i64) -> Errno {
    debug_assert!(ret < 0 && ret > -4096);
    #[allow(clippy::cast_possible_truncation)]
    let raw = ret.wrapping_neg() as i32;
    let nz = NonZeroI32::new(raw).expect("errno strictement positif par construction");
    Errno::from_nonzero(nz)
}

// ─────────────────────────────────────────────────────────────────────────
// Helper : extrait une CString à partir d'un buffer null-terminated
// ─────────────────────────────────────────────────────────────────────────

/// Extrait la portion avant le premier NUL d'un buffer kernel null-terminé,
/// et la convertit en [`CString`].
///
/// Convention 4 ADR-021 exception explicite : la sémantique exige un type
/// owned (le buffer kernel est local temporaire ; la `CString` doit sortir
/// du frame). Allocation bornée à la longueur du champ (65 octets max).
fn cstring_from_uts_field(field: &[u8; 65]) -> CString {
    let length = field.iter().position(|&b| b == 0).unwrap_or(65);
    // CString::new exige l'absence de NUL interne ; on passe uniquement les
    // octets avant le premier NUL trouvé — le kernel garantit la terminaison.
    CString::new(&field[..length]).expect("champ utsname sans NUL interne avant terminateur")
}

// ─────────────────────────────────────────────────────────────────────────
// getrandom
// ─────────────────────────────────────────────────────────────────────────

/// Remplit `buffer` avec des octets aléatoires cryptographiquement sûrs.
///
/// Utilise le syscall `getrandom(2)` (Linux 3.17+), qui puise dans le
/// CSPRNG kernel — mécanisme recommandé par Air pour toute génération
/// d'entropie. Ne passe jamais par `/dev/urandom` ni par la libc.
///
/// Peut retourner **moins** d'octets que `buffer.len()` (surtout pour les
/// grands buffers). L'appelant doit boucler si nécessaire.
///
/// # Parameters
///
/// - `buffer` : buffer de destination à remplir.
/// - `flags` : drapeaux de comportement (`GetrandomFlags::empty()` pour
///   le cas nominal).
///
/// # Errors
///
/// - `EINTR` : interrompu par un signal (conforme à ADR-021 convention 2 ;
///   l'appelant doit retry explicitement si désiré).
/// - `EAGAIN` : entropie non disponible et `NONBLOCK` était positionné
///   (au démarrage, avant l'initialisation du pool).
/// - `EFAULT` : pointeur invalide (ne se produit pas via cette API safe).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::system::getrandom;
/// use air_sys_types::GetrandomFlags;
///
/// let mut buffer = [0u8; 32];
/// let n = getrandom(&mut buffer, GetrandomFlags::empty()).expect("getrandom");
/// assert!(n > 0);
/// ```
pub fn getrandom(buffer: &mut [u8], flags: GetrandomFlags) -> Result<usize, Errno> {
    let buf_ptr = buffer.as_mut_ptr() as u64;
    // Longueur du buffer : sur les cibles LP64 d'Air (x86_64/aarch64),
    // usize == u64, la conversion est exacte. `cast_lossless` non applicable
    // ici car usize -> u64 est lossless sur 64 bits ; on le documente.
    #[allow(clippy::cast_lossless)]
    let buf_len = buffer.len() as u64;
    let flags_u64 = u64::from(flags.bits());

    // SAFETY:
    // - getrandom(2) (x86_64 = 318, aarch64 = 278) écrit `count` octets au
    //   maximum dans `buffer` (pointeur valide pour toute la durée du syscall,
    //   fourni par la référence mutable `buffer`).
    // - Pas de `readonly` : le kernel écrit dans `*buf_ptr`.
    let ret = unsafe { raw_syscall_getrandom(buf_ptr, buf_len, flags_u64) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    // ret >= 0 : nombre d'octets écrits. Borné par buffer.len() <= usize::MAX.
    // Sur LP64, i64 et usize ont la même largeur ; le cast est exact.
    // La troncature ne peut pas se produire car ret est borné par buffer.len(),
    // qui est lui-même un usize — donc ret < usize::MAX sur LP64.
    #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
    Ok(ret as usize)
}

// ─────────────────────────────────────────────────────────────────────────
// uname
// ─────────────────────────────────────────────────────────────────────────

/// Retourne les informations sur le système d'exploitation et le kernel.
///
/// Wrappeur de `uname(2)`. Retourne un [`UtsName`] avec les champs
/// `sysname`, `nodename`, `release`, `version`, `machine` et
/// `domainname` sous forme de [`CString`] propriétaires.
///
/// # Errors
///
/// `uname(2)` ne retourne jamais d'erreur en pratique sur Linux moderne
/// (la glibc et le kernel ne documentent aucun errno). Retour d'erreur
/// inclus par convention défensive.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::system::uname;
///
/// let info = uname().expect("uname");
/// // info.machine vaut "x86_64" ou "aarch64" sur les plateformes Air
/// ```
pub fn uname() -> Result<UtsName, Errno> {
    let mut buffer = KernelUtsname::zeroed();
    let buf_ptr = (&mut buffer as *mut KernelUtsname) as u64;

    // SAFETY:
    // - uname(2) (x86_64 = 63, aarch64 = 160) écrit `sizeof(struct utsname)`
    //   octets dans le pointeur fourni. `buffer` est local valide pour toute la
    //   durée du syscall.
    // - Pas de `readonly` : le kernel écrit dans `*buf_ptr`.
    let ret = unsafe { raw_syscall_uname(buf_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    Ok(UtsName {
        sysname: cstring_from_uts_field(&buffer.sysname),
        nodename: cstring_from_uts_field(&buffer.nodename),
        release: cstring_from_uts_field(&buffer.release),
        version: cstring_from_uts_field(&buffer.version),
        machine: cstring_from_uts_field(&buffer.machine),
        domainname: cstring_from_uts_field(&buffer.domainname),
    })
}

// ─────────────────────────────────────────────────────────────────────────
// sysinfo
// ─────────────────────────────────────────────────────────────────────────

/// Retourne des statistiques globales sur l'état du système.
///
/// Wrappeur de `sysinfo(2)`. Les valeurs de RAM et swap sont converties
/// en octets (multiplication par `mem_unit` effectuée en interne).
/// Les `load_average` sont normalisés en `f64`.
///
/// # Errors
///
/// `sysinfo(2)` ne retourne normalement pas d'erreur.
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::system::sysinfo;
///
/// let info = sysinfo().expect("sysinfo");
/// // info.free_ram indique la RAM libre en octets
/// ```
pub fn sysinfo() -> Result<SystemInfo, Errno> {
    let mut info = KernelSysinfo::zeroed();
    let info_ptr = (&mut info as *mut KernelSysinfo) as u64;

    // SAFETY:
    // - sysinfo(2) (x86_64 = 99, aarch64 = 179) écrit exactement 112 octets
    //   dans le pointeur fourni (struct sysinfo LP64). `info` est local valide
    //   pour toute la durée du syscall.
    // - Pas de `readonly` : le kernel écrit dans `*info_ptr`.
    let ret = unsafe { raw_syscall_sysinfo(info_ptr) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }

    // mem_unit est l'unité des valeurs mémoire du kernel. Sur Linux moderne
    // mem_unit vaut toujours 1, mais la spec impose la multiplication.
    let unit = u64::from(info.mem_unit);

    // Saturation sur overflow : mem_unit * valeur peut théoriquement déborder
    // un u64 sur des systèmes avec mem_unit > 1 et RAM extrême. La saturation
    // est préférable à un résultat incorrect silencieux (Principe 2).
    let scale = |v: u64| v.saturating_mul(unit);

    // uptime : i64 de secondes. Valeur toujours >= 0 après boot.
    let uptime_secs = u64::try_from(info.uptime).unwrap_or(0);
    let uptime = core::time::Duration::from_secs(uptime_secs);

    // Load averages : divisés par 65536.0 pour obtenir une valeur en nombre
    // de processus. Le cast f64 d'un u64 est une widening conversion (lossless
    // pour les valeurs dans la plage de représentation IEEE 754 double).
    #[allow(clippy::cast_precision_loss)]
    let load_average = [
        info.loads[0] as f64 / 65536.0,
        info.loads[1] as f64 / 65536.0,
        info.loads[2] as f64 / 65536.0,
    ];

    Ok(SystemInfo {
        uptime,
        load_average,
        total_ram: scale(info.totalram),
        free_ram: scale(info.freeram),
        shared_ram: scale(info.sharedram),
        buffer_ram: scale(info.bufferram),
        total_swap: scale(info.totalswap),
        free_swap: scale(info.freeswap),
        processes: info.procs,
        total_high: scale(info.totalhigh),
        free_high: scale(info.freehigh),
        mem_unit: info.mem_unit,
    })
}

// ─────────────────────────────────────────────────────────────────────────
// gethostname (via uname)
// ─────────────────────────────────────────────────────────────────────────

/// Retourne le nom d'hôte du système.
///
/// Implémenté en interne via `uname(2)` (extraction du champ `nodename`)
/// plutôt qu'un syscall `gethostname` séparé — économise un syscall et
/// réutilise le code déjà testé.
///
/// # Errors
///
/// Voir [`uname`].
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::system::gethostname;
///
/// let name = gethostname().expect("gethostname");
/// ```
pub fn gethostname() -> Result<CString, Errno> {
    let info = uname()?;
    Ok(info.nodename)
}

// ─────────────────────────────────────────────────────────────────────────
// sethostname
// ─────────────────────────────────────────────────────────────────────────

/// Modifie le nom d'hôte du système.
///
/// Wrappeur de `sethostname(2)`. Exige `CAP_SYS_ADMIN`. Rarement
/// utilisé par les applications Air normales — plutôt réservé au
/// launcher dans un UTS namespace.
///
/// # Parameters
///
/// - `name` : nouveau nom d'hôte. Doit avoir une longueur ≤
///   `HOST_NAME_MAX` (64 octets sur Linux). Les octets NUL intermédiaires
///   sont interdits.
///
/// # Errors
///
/// - `EPERM` : `CAP_SYS_ADMIN` manquant.
/// - `EINVAL` : nom trop long (> 64 octets).
///
/// # Examples
///
/// ```no_run
/// use air_sys_syscall::system::sethostname;
/// use core::ffi::CStr;
///
/// // Requiert CAP_SYS_ADMIN
/// sethostname(c"air-node-01").expect("sethostname");
/// ```
pub fn sethostname(name: &CStr) -> Result<(), Errno> {
    let bytes = name.to_bytes(); // octets sans le NUL terminal
    let ptr = bytes.as_ptr() as u64;
    // Longueur sans le NUL terminal (sémantique sethostname(2)).
    // Sur LP64, usize == u64, cast exact.
    #[allow(clippy::cast_lossless)]
    let length = bytes.len() as u64;

    // SAFETY:
    // - sethostname(2) (x86_64 = 170, aarch64 = 161) lit `length` octets à
    //   l'adresse `ptr`. `name.to_bytes()` fournit une slice valide pour
    //   toute la durée du syscall (lifetime de `name` couvre l'appel).
    // - `readonly` correct : le kernel ne modifie pas la mémoire passée.
    let ret = unsafe { raw_syscall_sethostname(ptr, length) };
    if ret < 0 {
        return Err(errno_from_negative_syscall_ret(ret));
    }
    Ok(())
}

// ─────────────────────────────────────────────────────────────────────────
// Raw syscall helpers — x86_64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_getrandom(buffer: u64, count: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_getrandom (x86_64 = 318). Le kernel écrit au plus `count` octets
    //   à l'adresse `buffer` (validité garantie par l'appelant — référence mutable
    //   au buffer).
    // - ABI x86_64 : numéro en RAX, args en RDI/RSI/RDX ; retour en RAX ;
    //   clobbe RCX (RIP) et R11 (RFLAGS).
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 318_i64,
            in("rdi") buffer,
            in("rsi") count,
            in("rdx") flags,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_uname(buffer: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_uname (x86_64 = 63). Le kernel écrit `sizeof(struct utsname)`
    //   (390 octets) à l'adresse `buffer` (validité garantie par l'appelant —
    //   `KernelUtsname` local).
    // - ABI x86_64 : numéro en RAX, arg1 en RDI ; retour en RAX ; clobbe
    //   RCX et R11.
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 63_i64,
            in("rdi") buffer,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sysinfo(buffer: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sysinfo (x86_64 = 99). Le kernel écrit exactement 112 octets
    //   (struct sysinfo LP64) à l'adresse `buffer` (validité garantie par
    //   l'appelant — `KernelSysinfo` local, 112 octets vérifiés à la
    //   compilation).
    // - ABI x86_64 : numéro en RAX, arg1 en RDI ; retour en RAX ; clobbe
    //   RCX et R11.
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 99_i64,
            in("rdi") buffer,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "x86_64")]
#[inline]
unsafe fn raw_syscall_sethostname(name: u64, length: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sethostname (x86_64 = 170). Le kernel lit `length` octets à
    //   l'adresse `name` (validité garantie par l'appelant — bytes valide
    //   pour la durée du syscall).
    // - ABI x86_64 : numéro en RAX, args en RDI/RSI ; retour en RAX ;
    //   clobbe RCX et R11.
    // - `readonly` correct : le kernel lit uniquement la mémoire fournie,
    //   sans l'écrire.
    unsafe {
        core::arch::asm!(
            "syscall",
            in("rax") 170_i64,
            in("rdi") name,
            in("rsi") length,
            lateout("rax") ret,
            lateout("rcx") _,
            lateout("r11") _,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Raw syscall helpers — aarch64
// ─────────────────────────────────────────────────────────────────────────

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_getrandom(buffer: u64, count: u64, flags: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_getrandom (aarch64 = 278). Le kernel écrit au plus `count`
    //   octets à l'adresse `buffer` (validité garantie par l'appelant).
    // - ABI aarch64 : numéro en X8, args en X0/X1/X2, retour en X0.
    //   `inout("x0")` passe buffer en entrée et lit ret en sortie.
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 278_i64,
            inout("x0") buffer => ret,
            in("x1") count,
            in("x2") flags,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_uname(buffer: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_uname (aarch64 = 160). Identique x86_64 en sémantique.
    // - ABI aarch64 : numéro en X8, arg1 en X0, retour en X0.
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 160_i64,
            inout("x0") buffer => ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sysinfo(buffer: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sysinfo (aarch64 = 179). Identique x86_64 en sémantique.
    // - ABI aarch64 : numéro en X8, arg1 en X0, retour en X0.
    // - Pas de `readonly` : le kernel écrit dans `*buffer`.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 179_i64,
            inout("x0") buffer => ret,
            options(nostack, preserves_flags),
        );
    }
    ret
}

#[cfg(target_arch = "aarch64")]
#[inline]
unsafe fn raw_syscall_sethostname(name: u64, length: u64) -> i64 {
    let ret: i64;
    // SAFETY:
    // - SYS_sethostname (aarch64 = 161). Identique x86_64 en sémantique.
    // - ABI aarch64 : numéro en X8, args en X0/X1, retour en X0.
    // - `readonly` correct : le kernel lit uniquement la mémoire fournie.
    unsafe {
        core::arch::asm!(
            "svc 0",
            in("x8") 161_i64,
            inout("x0") name => ret,
            in("x1") length,
            options(nostack, preserves_flags, readonly),
        );
    }
    ret
}

// ─────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests;