Skip to main content

libc_rs/
raw.rs

1//! Raw AArch64 `svc #0` system call dispatch and syscall numbers.
2
3use crate::errno::{Errno, SysResult};
4
5/// AArch64 unikernel system call numbers.
6pub mod nr {
7    pub const GETCWD: usize = 17;
8    pub const EVENTFD2: usize = 19;
9    pub const EPOLL_CREATE1: usize = 20;
10    pub const EPOLL_CTL: usize = 21;
11    pub const DUP: usize = 23;
12    pub const DUP3: usize = 24;
13    pub const FCNTL: usize = 25;
14    pub const IOCTL: usize = 29;
15    pub const FLOCK: usize = 32;
16    pub const MKDIRAT: usize = 34;
17    pub const UNLINKAT: usize = 35;
18    pub const LINKAT: usize = 37;
19    pub const RENAMEAT: usize = 38;
20    pub const UMOUNT2: usize = 39;
21    pub const MOUNT: usize = 40;
22    pub const FTRUNCATE: usize = 46;
23    pub const FACCESSAT: usize = 48;
24    pub const CHDIR: usize = 49;
25    pub const CHROOT: usize = 51;
26    pub const FCHMOD: usize = 52;
27    pub const OPENAT: usize = 56;
28    pub const CLOSE: usize = 57;
29    pub const PIPE2: usize = 59;
30    pub const GETDENTS64: usize = 61;
31    pub const LSEEK: usize = 62;
32    pub const READ: usize = 63;
33    pub const WRITE: usize = 64;
34    pub const WRITEV: usize = 66;
35    pub const PREAD64: usize = 67;
36    pub const PWRITE64: usize = 68;
37    pub const PPOLL: usize = 73;
38    pub const READLINKAT: usize = 78;
39    pub const NEWFSTATAT: usize = 79;
40    pub const FSTAT: usize = 80;
41    pub const SYNC: usize = 81;
42    pub const FSYNC: usize = 82;
43    pub const EXIT: usize = 93;
44    pub const EXIT_GROUP: usize = 94;
45    pub const FUTEX: usize = 98;
46    pub const CLOCK_SETTIME: usize = 112;
47    pub const CLOCK_GETTIME: usize = 113;
48    pub const CLOCK_NANOSLEEP: usize = 115;
49    pub const SCHED_YIELD: usize = 124;
50    pub const KILL: usize = 129;
51    pub const RT_SIGACTION: usize = 134;
52    pub const RT_SIGRETURN: usize = 139;
53    pub const SETPGID: usize = 154;
54    pub const SETSID: usize = 157;
55    pub const GETRLIMIT: usize = 163;
56    pub const SETRLIMIT: usize = 164;
57    pub const GETRUSAGE: usize = 165;
58    pub const UMASK: usize = 166;
59    pub const GETPID: usize = 172;
60    pub const GETUID: usize = 174;
61    pub const GETEUID: usize = 175;
62    pub const GETGID: usize = 176;
63    pub const GETEGID: usize = 177;
64    pub const GETTID: usize = 178;
65    pub const SOCKET: usize = 198;
66    pub const SOCKETPAIR: usize = 199;
67    pub const BIND: usize = 200;
68    pub const LISTEN: usize = 201;
69    pub const CONNECT: usize = 203;
70    pub const GETSOCKNAME: usize = 204;
71    pub const GETPEERNAME: usize = 205;
72    pub const SENDTO: usize = 206;
73    pub const RECVFROM: usize = 207;
74    pub const SETSOCKOPT: usize = 208;
75    pub const GETSOCKOPT: usize = 209;
76    pub const SHUTDOWN: usize = 210;
77    pub const MUNMAP: usize = 215;
78    pub const CLONE: usize = 220;
79    pub const EXECVE: usize = 221;
80    pub const MMAP: usize = 222;
81    pub const MPROTECT: usize = 226;
82    pub const MINCORE: usize = 232;
83    pub const MADVISE: usize = 233;
84    pub const ACCEPT4: usize = 242;
85    pub const WAIT4: usize = 260;
86    pub const GETRANDOM: usize = 278;
87    pub const EPOLL_PWAIT2: usize = 441;
88}
89
90/// Decodes a raw `x0` return value from `svc #0` into [`SysResult<usize>`].
91///
92/// Negative values in `-4095..=-1` represent `-errno`.
93pub const fn decode_raw(raw: usize) -> SysResult<usize> {
94    let signed = raw as isize;
95    if signed >= -4095 && signed < 0 {
96        Err(Errno((-signed) as i32))
97    } else {
98        Ok(raw)
99    }
100}
101
102#[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
103mod mock {
104    #[cfg(test)]
105    use core::sync::atomic::AtomicBool;
106    use core::sync::atomic::AtomicUsize;
107    use core::sync::atomic::Ordering;
108
109    use crate::errno::{ENOSYS, Errno, SysResult};
110
111    pub type SyscallHandler = fn(usize, [usize; 6]) -> SysResult<usize>;
112
113    pub static MOCK_SYSCALL: AtomicUsize = AtomicUsize::new(0);
114
115    #[cfg(test)]
116    static MOCK_LOCK: AtomicBool = AtomicBool::new(false);
117
118    #[cfg(test)]
119    struct LockGuard;
120
121    #[cfg(test)]
122    impl Drop for LockGuard {
123        fn drop(&mut self) {
124            MOCK_SYSCALL.store(0, Ordering::Release);
125            MOCK_LOCK.store(false, Ordering::Release);
126        }
127    }
128
129    #[cfg(test)]
130    pub fn with_mock_syscall<R>(handler: SyscallHandler, f: impl FnOnce() -> R) -> R {
131        while MOCK_LOCK
132            .compare_exchange_weak(false, true, Ordering::Acquire, Ordering::Relaxed)
133            .is_err()
134        {
135            core::hint::spin_loop();
136        }
137        let _guard = LockGuard;
138        MOCK_SYSCALL.store(handler as usize, Ordering::Release);
139        f()
140    }
141
142    pub fn dispatch(nr: usize, args: [usize; 6]) -> SysResult<usize> {
143        let ptr = MOCK_SYSCALL.load(Ordering::Acquire);
144        if ptr == 0 {
145            return Err(Errno(ENOSYS));
146        }
147        // SAFETY: `ptr` was stored from a `SyscallHandler` function pointer in `with_mock_syscall`.
148        let handler: SyscallHandler = unsafe { core::mem::transmute(ptr) };
149        handler(nr, args)
150    }
151}
152
153#[cfg(test)]
154pub(crate) fn with_mock_syscall<R>(
155    handler: fn(usize, [usize; 6]) -> SysResult<usize>,
156    f: impl FnOnce() -> R,
157) -> R {
158    mock::with_mock_syscall(handler, f)
159}
160
161/// Invokes a 0-argument system call.
162///
163/// # Safety
164///
165/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
166#[inline]
167pub unsafe fn syscall0(nr: usize) -> SysResult<usize> {
168    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
169    {
170        let ret: usize;
171        // SAFETY: The caller upholds the syscall contract for `nr`.
172        unsafe {
173            core::arch::asm!(
174                "svc #0",
175                in("x8") nr,
176                lateout("x0") ret,
177                options(nostack, preserves_flags),
178            );
179        }
180        decode_raw(ret)
181    }
182    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
183    {
184        mock::dispatch(nr, [0, 0, 0, 0, 0, 0])
185    }
186}
187
188/// Invokes a 1-argument system call.
189///
190/// # Safety
191///
192/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
193#[inline]
194pub unsafe fn syscall1(nr: usize, a0: usize) -> SysResult<usize> {
195    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
196    {
197        let ret: usize;
198        // SAFETY: The caller upholds the syscall contract for `nr`.
199        unsafe {
200            core::arch::asm!(
201                "svc #0",
202                in("x8") nr,
203                inlateout("x0") a0 => ret,
204                options(nostack, preserves_flags),
205            );
206        }
207        decode_raw(ret)
208    }
209    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
210    {
211        mock::dispatch(nr, [a0, 0, 0, 0, 0, 0])
212    }
213}
214
215/// Invokes a 2-argument system call.
216///
217/// # Safety
218///
219/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
220#[inline]
221pub unsafe fn syscall2(nr: usize, a0: usize, a1: usize) -> SysResult<usize> {
222    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
223    {
224        let ret: usize;
225        // SAFETY: The caller upholds the syscall contract for `nr`.
226        unsafe {
227            core::arch::asm!(
228                "svc #0",
229                in("x8") nr,
230                inlateout("x0") a0 => ret,
231                in("x1") a1,
232                options(nostack, preserves_flags),
233            );
234        }
235        decode_raw(ret)
236    }
237    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
238    {
239        mock::dispatch(nr, [a0, a1, 0, 0, 0, 0])
240    }
241}
242
243/// Invokes a 3-argument system call.
244///
245/// # Safety
246///
247/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
248#[inline]
249pub unsafe fn syscall3(nr: usize, a0: usize, a1: usize, a2: usize) -> SysResult<usize> {
250    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
251    {
252        let ret: usize;
253        // SAFETY: The caller upholds the syscall contract for `nr`.
254        unsafe {
255            core::arch::asm!(
256                "svc #0",
257                in("x8") nr,
258                inlateout("x0") a0 => ret,
259                in("x1") a1,
260                in("x2") a2,
261                options(nostack, preserves_flags),
262            );
263        }
264        decode_raw(ret)
265    }
266    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
267    {
268        mock::dispatch(nr, [a0, a1, a2, 0, 0, 0])
269    }
270}
271
272/// Invokes a 4-argument system call.
273///
274/// # Safety
275///
276/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
277#[inline]
278pub unsafe fn syscall4(nr: usize, a0: usize, a1: usize, a2: usize, a3: usize) -> SysResult<usize> {
279    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
280    {
281        let ret: usize;
282        // SAFETY: The caller upholds the syscall contract for `nr`.
283        unsafe {
284            core::arch::asm!(
285                "svc #0",
286                in("x8") nr,
287                inlateout("x0") a0 => ret,
288                in("x1") a1,
289                in("x2") a2,
290                in("x3") a3,
291                options(nostack, preserves_flags),
292            );
293        }
294        decode_raw(ret)
295    }
296    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
297    {
298        mock::dispatch(nr, [a0, a1, a2, a3, 0, 0])
299    }
300}
301
302/// Invokes a 5-argument system call.
303///
304/// # Safety
305///
306/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
307#[inline]
308pub unsafe fn syscall5(
309    nr: usize,
310    a0: usize,
311    a1: usize,
312    a2: usize,
313    a3: usize,
314    a4: usize,
315) -> SysResult<usize> {
316    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
317    {
318        let ret: usize;
319        // SAFETY: The caller upholds the syscall contract for `nr`.
320        unsafe {
321            core::arch::asm!(
322                "svc #0",
323                in("x8") nr,
324                inlateout("x0") a0 => ret,
325                in("x1") a1,
326                in("x2") a2,
327                in("x3") a3,
328                in("x4") a4,
329                options(nostack, preserves_flags),
330            );
331        }
332        decode_raw(ret)
333    }
334    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
335    {
336        mock::dispatch(nr, [a0, a1, a2, a3, a4, 0])
337    }
338}
339
340/// Invokes a 6-argument system call.
341///
342/// # Safety
343///
344/// The caller must uphold the ABI and memory safety invariants required by syscall `nr`.
345#[inline]
346pub unsafe fn syscall6(
347    nr: usize,
348    a0: usize,
349    a1: usize,
350    a2: usize,
351    a3: usize,
352    a4: usize,
353    a5: usize,
354) -> SysResult<usize> {
355    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
356    {
357        let ret: usize;
358        // SAFETY: The caller upholds the syscall contract for `nr`.
359        unsafe {
360            core::arch::asm!(
361                "svc #0",
362                in("x8") nr,
363                inlateout("x0") a0 => ret,
364                in("x1") a1,
365                in("x2") a2,
366                in("x3") a3,
367                in("x4") a4,
368                in("x5") a5,
369                options(nostack, preserves_flags),
370            );
371        }
372        decode_raw(ret)
373    }
374    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
375    {
376        mock::dispatch(nr, [a0, a1, a2, a3, a4, a5])
377    }
378}
379
380/// Reads the hardware thread pointer register (`TPIDR_EL0`) on AArch64 EL0 targets,
381/// returning `0` on host test targets or before a thread control block is installed.
382#[must_use]
383#[inline]
384pub fn read_thread_pointer() -> usize {
385    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
386    {
387        let tp: usize;
388        // SAFETY: `TPIDR_EL0` is readable at EL0 with no memory side effects.
389        unsafe {
390            core::arch::asm!(
391                "mrs {}, tpidr_el0",
392                out(reg) tp,
393                options(nomem, nostack, preserves_flags),
394            );
395        }
396        tp
397    }
398    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
399    {
400        0
401    }
402}
403
404/// Reads the AArch64 timer frequency register (`CNTFRQ_EL0`) on EL0 targets.
405#[cfg(all(target_arch = "aarch64", target_os = "none"))]
406#[must_use]
407#[inline]
408pub(crate) fn read_cntfrq_el0() -> u64 {
409    let hz: u64;
410    // SAFETY: `cntfrq_el0` is readable from EL0 when `CNTKCTL_EL1.EL0VCTEN == 1`.
411    unsafe {
412        core::arch::asm!(
413            "mrs {}, cntfrq_el0",
414            out(reg) hz,
415            options(nomem, nostack, preserves_flags),
416        );
417    }
418    hz
419}
420
421/// Reads the AArch64 virtual counter register (`CNTVCT_EL0`) on EL0 targets.
422#[cfg(all(target_arch = "aarch64", target_os = "none"))]
423#[must_use]
424#[inline]
425pub(crate) fn read_cntvct_el0() -> u64 {
426    let ticks: u64;
427    // SAFETY: `cntvct_el0` is readable from EL0 when `CNTKCTL_EL1.EL0VCTEN == 1`.
428    unsafe {
429        core::arch::asm!(
430            "mrs {}, cntvct_el0",
431            out(reg) ticks,
432            options(nomem, nostack, preserves_flags),
433        );
434    }
435    ticks
436}
437
438/// Restorer trampoline invoking `rt_sigreturn` (`nr::RT_SIGRETURN = 139`) for `SA_RESTORER`.
439///
440/// # Safety
441///
442/// Must only be invoked by the kernel signal-return path with a valid signal frame on the stack.
443#[cfg(all(target_arch = "aarch64", target_os = "none"))]
444#[unsafe(naked)]
445pub(crate) unsafe extern "C" fn default_sigrestorer() -> ! {
446    core::arch::naked_asm!("mov x8, #139", "svc #0", "brk #0",);
447}
448
449const _: () = {
450    assert!(nr::RT_SIGRETURN == 139);
451    assert!(nr::MUNMAP == 215);
452    assert!(nr::EXIT == 93);
453    assert!(nr::CLONE == 220);
454};
455
456/// Triggers an immediate hardware trap (`brk #0`) on AArch64 EL0 targets.
457pub(crate) fn trap_abort() -> ! {
458    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
459    // SAFETY: `brk #0` immediately traps execution at EL0 without touching memory or stack.
460    unsafe {
461        core::arch::asm!("brk #0", options(noreturn, nostack, nomem));
462    }
463    #[cfg(not(all(target_arch = "aarch64", target_os = "none")))]
464    {
465        panic!("abort")
466    }
467}
468
469/// Clears `TPIDR_EL0`, unmaps the calling detached thread's stack `[map_base, map_base + map_len)`,
470/// and terminates the calling thread via `SYS_EXIT` without touching stack memory.
471///
472/// # Safety
473///
474/// Must only be called as the final action of a detached thread whose stack mapping is
475/// `(map_base, map_len)` and with no live stack references remaining.
476#[cfg(all(target_arch = "aarch64", target_os = "none"))]
477pub unsafe fn unmap_stack_and_exit(map_base: usize, map_len: usize) -> ! {
478    // SAFETY: Caller guarantees no stack memory is accessed after `MUNMAP` and `EXIT` never returns.
479    unsafe {
480        core::arch::asm!(
481            "msr tpidr_el0, xzr",
482            "mov x8, #215",
483            "svc #0",
484            "mov x0, #0",
485            "mov x8, #93",
486            "svc #0",
487            "brk #0",
488            in("x0") map_base,
489            in("x1") map_len,
490            options(noreturn, nostack),
491        );
492    }
493}
494
495/// Spawns a child thread via `SYS_CLONE` on AArch64 EL0, invoking `child_entry()` when `CLONE`
496/// returns `0` in the newly created thread.
497///
498/// # Safety
499///
500/// `child_sp` must be 16-byte aligned with `[child_sp - 16, child_sp + 64)` mapped RW,
501/// `CLONE_SETTLS` must install a valid TCB in `tls` for `child_entry`, and `parent_tid`/`child_tid`
502/// must satisfy `CLONE` flags.
503#[cfg(all(target_arch = "aarch64", target_os = "none"))]
504#[inline(never)]
505pub unsafe fn clone_thread(
506    flags: u64,
507    child_sp: usize,
508    parent_tid: usize,
509    tls: usize,
510    child_tid: usize,
511    child_entry: unsafe extern "C" fn() -> !,
512) -> SysResult<usize> {
513    let ret: usize;
514    // SAFETY: Caller upholds `SYS_CLONE` stack, TLS, and TID pointer invariants.
515    unsafe {
516        core::arch::asm!(
517            "svc #0",
518            in("x8") nr::CLONE,
519            inlateout("x0") flags as usize => ret,
520            in("x1") child_sp,
521            in("x2") parent_tid,
522            in("x3") tls,
523            in("x4") child_tid,
524            options(nostack, preserves_flags),
525        );
526    }
527    if ret == 0 {
528        // SAFETY: Running on the new child stack with `TPIDR_EL0 == tls`; `child_entry` never returns.
529        unsafe { child_entry() }
530    }
531    decode_raw(ret)
532}
533
534#[cfg(test)]
535mod tests {
536    use super::*;
537    use crate::errno::{EINVAL, ENOSYS};
538
539    #[test]
540    fn decode_raw_boundaries() {
541        assert_eq!(decode_raw(0), Ok(0));
542        assert_eq!(decode_raw(42), Ok(42));
543        assert_eq!(decode_raw((-22isize) as usize), Err(Errno(EINVAL)));
544        assert_eq!(decode_raw((-4095isize) as usize), Err(Errno(4095)));
545        assert_eq!(decode_raw((-4096isize) as usize), Ok((-4096isize) as usize));
546    }
547
548    #[test]
549    fn default_mock_returns_enosys() {
550        let res = unsafe { syscall0(nr::GETPID) };
551        assert_eq!(res, Err(Errno(ENOSYS)));
552    }
553}