// TODO: Implement `libtock_unittest`, which is referenced in the comment on
// `RawSyscalls`.

/// `RawSyscalls` allows a fake Tock kernel to be injected into components for
/// unit testing. It is implemented by `libtock_runtime::TockSyscalls` and
/// `libtock_unittest::fake::Kernel`. **Components should not use `RawSyscalls`
/// directly; instead, use the `Syscalls` trait, which provides higher-level
/// interfaces to the system calls.**

// The RawSyscalls trait is designed to minimize the complexity and size of its
// implementation, as its implementation is difficult to test (it cannot be used
// in unit tests, with sanitizers, or in Miri). It is also designed to minimize
// the number of unnecessary instructions it generates.
//
// Convention: This file uses the same register naming conventions as the Tock
// 2.0 syscall TRD. Registers r0-r4 correspond to ARM registers r0-r4 and RISC-V
// registers a0-a4.
//
// Theoretically, RawSyscalls could consist of a single raw system call. To
// start, something like this should work:
//
//   unsafe fn syscall<const CLASS: usize>([usize; 4]) -> [usize; 4];
//
// However, this will not work with Miri's -Zmiri-track-raw-pointers flag, as it
// causes pointers passed to the kernel via the Allow system calls to be
// untagged. In order to work with -Zmiri-track-raw-pointers, we need to pass
// pointers for the register values. Rust's closest analogue to C's void pointer
// is *mut () or *const (); we use *mut () because it is shorter:
//
//   unsafe fn syscall<const CLASS: usize>([*mut (); 4]) -> [*mut (); 4];
//
// Using a single system call has a major inefficiency. The single raw system
// call would need to clobber every register that any system call can clobber.
// Yield has a far longer clobber list than most system calls, so this would be
// inefficient for the majority of system calls. As a result, we can split yield
// out into its own function, giving the following API:
//
//   unsafe fn yield([*mut (); 4]) -> [*mut (); 4];
//   unsafe fn syscall<const CLASS: usize>([*mut (); 4]) -> [*mut (); 4];
//
// There is one significant inefficiency remaining. Many system calls, such as
// memop's "get RAM start address" operation, do not need to set all four
// arguments. The compiler cannot optimize away this inefficiency, so to remove
// it we need to split the system calls up based on the number of arguments they
// take:
//
//   unsafe fn yield0([*mut (); 0]) -> [*mut (); 4];
//   unsafe fn yield1([*mut (); 1]) -> [*mut (); 4];
//   unsafe fn yield2([*mut (); 2]) -> [*mut (); 4];
//   unsafe fn yield3([*mut (); 3]) -> [*mut (); 4];
//   unsafe fn yield4([*mut (); 4]) -> [*mut (); 4];
//   unsafe fn syscall0<const CLASS: usize>([*mut (); 0]) -> [*mut (); 4];
//   unsafe fn syscall1<const CLASS: usize>([*mut (); 1]) -> [*mut (); 4];
//   unsafe fn syscall2<const CLASS: usize>([*mut (); 2]) -> [*mut (); 4];
//   unsafe fn syscall3<const CLASS: usize>([*mut (); 3]) -> [*mut (); 4];
//   unsafe fn syscall4<const CLASS: usize>([*mut (); 4]) -> [*mut (); 4];
//
// However, not all of these are used! If we remove the system calls that are
// unused, we are left with the following:
//
//   unsafe fn yield1([*mut (); 1]) -> [*mut (); 4];
//   unsafe fn yield2([*mut (); 2]) -> [*mut (); 4];
//   unsafe fn syscall1<const CLASS: usize>([*mut (); 1]) -> [*mut (); 4];
//   unsafe fn syscall2<const CLASS: usize>([*mut (); 2]) -> [*mut (); 4];
//   unsafe fn syscall4<const CLASS: usize>([*mut (); 4]) -> [*mut (); 4];
//
// These system calls are refined further individually, which is documented on
// a per-function basis.
pub unsafe trait RawSyscalls {
    // yield1 can only be used to call `yield-wait`, which does not have a
    // return value. To simplify the assembly implementation, we remove its
    // return value.
    //
    // yield1 should:
    //     1. Call syscall class 0
    //     2. Pass in r0 as an inlateout register.
    //     3. Mark all caller-saved registers as lateout clobbers.
    //     4. NOT provide any of the following options:
    //            pure             (yield has side effects)
    //            nomem            (a callback can read + write globals)
    //            readonly         (a callback can write globals)
    //            preserves_flags  (a callback can change flags)
    //            noreturn         (yield is expected to return)
    //            nostack          (a callback needs the stack)
    /// `yield1` should only be called by `libtock_platform`.
    /// # Safety
    /// yield1 may only be used for yield operations that do not return a value.
    /// It is exactly as safe as the underlying system call.
    unsafe fn yield1(_: [*mut (); 1]);

    // yield2 can only be used to call `yield-no-wait`. `yield-no-wait` does not
    // return any values, so to simplify the assembly we omit return arguments.
    //
    // yield2 should:
    //     1. Call syscall class 0
    //     2. Pass in r0 and r1 as inlateout registers.
    //     3. Mark all caller-saved registers as lateout clobbers.
    //     4. NOT provide any of the following options:
    //            pure             (yield has side effects)
    //            nomem            (a callback can read + write globals)
    //            readonly         (a callback can write globals)
    //            preserves_flags  (a callback can change flags)
    //            noreturn         (yield is expected to return)
    //            nostack          (a callback needs the stack)
    /// `yield2` should only be called by `libtock_platform`.
    /// # Safety
    /// yield2 may only be used for yield operations that do not return a value.
    /// It has the same safety invariants as the underlying system call.
    unsafe fn yield2(_: [*mut (); 2]);

    // syscall1 is only used to invoke Memop operations. Because there are no
    // Memop commands that set r2 or r3, raw_syscall1 only needs to return r0
    // and r1.
    //
    // Memop commands may panic in the unit test environment, as not all memop
    // calls can be sensibly implemented in that environment.
    //
    // syscall1 should:
    //     1. Call the syscall class specified by CLASS.
    //     2. Pass r0 as an inlateout register.
    //     3. Specify r1 as a lateout register and return its value.
    //     4. Not mark any registers as clobbered.
    //     5. Have all of the following options:
    //            preserves_flags
    //            nostack
    //            nomem            (it is okay for the compiler to cache globals
    //                              across memop calls)
    //     6. NOT have any of the following options:
    //            pure      (two invocations of the same memop can return
    //                       different values)
    //            readonly  (incompatible with nomem)
    //            noreturn
    /// `syscall1` should only be called by `libtock_platform`.
    /// # Safety
    /// This directly makes a system call. It can only be used for core kernel
    /// system calls that accept 1 argument and only overwrite r0 and r1 on
    /// return. It is unsafe any time the underlying system call is unsafe.
    unsafe fn syscall1<const CLASS: usize>(_: [*mut (); 1]) -> [*mut (); 2];

    // syscall2 is used to invoke Exit as well as Memop operations that take an
    // argument. Memop does not currently use more than 2 registers for its
    // return value, and Exit does not return, so syscall2 only returns 2
    // values.
    //
    // syscall2 should:
    //     1. Call the syscall class specified by CLASS.
    //     2. Pass r0 and r1 as inlateout registers.
    //     3. Not mark any registers as clobbered.
    //     4. Have all of the following options:
    //            preserves_flags
    //            nostack
    //            nomem            (the compiler can cache globals across memop
    //                              calls)
    //     5. NOT have any of the following options:
    //            pure      Two invocations of sbrk can return different values
    //            readonly  Incompatible with nomem
    //            noreturn
    /// `syscall2` should only be called by `libtock_platform`.
    /// # Safety
    /// `syscall2` directly makes a system call. It can only be used for core
    /// kernel system calls that accept 2 arguments and only overwrite r0 and r1
    /// on return. It is unsafe any time the underlying system call is unsafe.
    unsafe fn syscall2<const CLASS: usize>(_: [*mut (); 2]) -> [*mut (); 2];

    // syscall4 should:
    //     1. Call the syscall class specified by CLASS.
    //     2. Pass r0-r3 in the corresponding registers as inlateout registers.
    //     3. Not mark any registers as clobbered.
    //     4. Have all of the following options:
    //            preserves_flags  (these system calls do not touch flags)
    //            nostack          (these system calls do not touch the stack)
    //     5. NOT have any of the following options:
    //            pure      (these system calls have side effects)
    //            nomem     (the compiler needs to write to globals before allow)
    //            readonly  (rw allow can modify memory)
    //            noreturn  (all these system calls are expected to return)
    //
    // For subscribe(), the callback pointer should be either 0 (for the null
    // callback) or an `unsafe extern fn(u32, u32, u32, Userdata)`.
    /// `syscall4` should only be called by `libtock_platform`.
    ///
    /// # Safety
    /// `syscall4` must NOT be used to invoke yield. Otherwise, it has the same
    /// safety invariants as the underlying system call, which varies depending
    /// on the system call class.
    unsafe fn syscall4<const CLASS: usize>(_: [*mut (); 4]) -> [*mut (); 4];
}