Rewrite my explanation of the design of RawSyscalls based on Phil's feedback.
diff --git a/core/platform/src/raw_syscalls.rs b/core/platform/src/raw_syscalls.rs index 36ea454..90fc602 100644 --- a/core/platform/src/raw_syscalls.rs +++ b/core/platform/src/raw_syscalls.rs
@@ -8,8 +8,10 @@ /// interfaces to the system calls. // RawSyscalls is designed to minimize the amount of handwritten assembly code -// needed without generating unnecessary instructions. There are a few major -// factors affecting its design: +// needed without generating unnecessary instructions. This comment describes +// the thought process that led to the choice of methods for RawSyscalls. There +// are a few major considerations affecting its design: +// // 1. Most system calls only clobber r0-r4 (*), while yield has a far longer // clobber list. As such, yield must have its own assembly // implementation. @@ -34,24 +36,48 @@ // the Tock 2.0 syscalls TRD. Registers r0-r4 correspond to ARM registers r0-r4 // and RISC-V registers a0-a4. // -// Currently, yield takes exactly one argument, to specify what yield type to -// do. Therefore we only need one raw yield call. +// Currently, yield takes exactly one argument (to specify what yield type to +// do). Therefore we only need one raw yield call. // -// Subscribe, command, read-write allow, and read-only allow all take four -// argument types. Even when calling command IDs that have unused arguments, we -// still need to clear the argument registers so as to avoid passing -// confidential data to capsules (this is in line with Tock's threat model). As -// such, four_arg_syscall() is used for all subscribe, command, read-only allow, -// and read-write allow system calls. +// Based on these considerations, it would make sense to have the following +// methods: +// yield +// zero_arg_syscall +// one_arg_syscall +// two_arg_syscall +// three_arg_syscall +// four_arg_syscall // -// Memop takes 1 or 2 arguments (operation and an optional argument). Because it -// is part of the core kernel, it is okay for us to leave arbitrary data in the -// argument register for operations where the argument register is unused -// (again, in line with Tock's threat model). As such, for efficiency, we need -// two raw memop calls: one for operations without an argument and one for -// operations with an argument. +// However, there are no system calls that take 0 or 3 arguments, so we do not +// need the corresponding methods. This leaves yield, 1-arg, 2-arg, and 4-arg +// system calls. // -// The success type for Memop calls depends on the operation perform. However, +// The 1-arg and 2-arg system calls are only used for memop. Memop currently has +// the property that none of its operations can lead to undefined behavior. +// Therefore, we can rename the 1-arg and 2-arg system calls to zero_arg_memop +// and one_arg_memop and make them safe methods (the argument counts change +// because the number of system call arguments is one greater than the number of +// arguments passed to the specific op). +// +// This only leaves four_arg_syscall, which is used to implement subscribe, +// command, read-write allow, and read-only allow. +// +// Therefore the final design has 4 methods: +// yield +// zero_arg_memop +// one_arg_memop +// four_arg_syscall +// +// If a new system call class that uses fewer than four arguments is added, then +// the above list will need to be revised. +// +// Note that `command` always needs to use four_arg_syscall, even when calling a +// command with fewer arguments, because we don't want to leak the +// (possibly secret) values in the r2 and r3 registers to untrusted capsules. +// Yield and memop do not have this concern and can leave arbitrary data in r2 +// and r3, because they are implemented by the core kernel, which is trusted. +// +// The success type for Memop calls depends on the operation performed. However, // all *currently defined* memop operations return either Success or Success // with u32. Therefore, the memop implementations only need to mark r0 and r1 as // clobbered, not r2 and r3. This choice of clobbers will need to be revisited