Core WG meeting 2021-01-29 conclusion: document that `RawSyscalls`' methods should only be called by `libtock_platform`.
This is to reduce the amount of churn caused by changes to `RawSyscalls`, in anticipation of future changes to support 64-bit platforms.
diff --git a/core/platform/src/raw_syscalls.rs b/core/platform/src/raw_syscalls.rs
index 90fc602..f4e37b8 100644
--- a/core/platform/src/raw_syscalls.rs
+++ b/core/platform/src/raw_syscalls.rs
@@ -1,11 +1,11 @@
-// TODO: Implement `libtock_runtime` and `libtock_unittest`, which are
-// referenced in the comment on `RawSyscalls`.
+// 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::FakeSyscalls`. Components should not use `RawSyscalls`
+/// `libtock_unittest::FakeSyscalls`. **Components should not use `RawSyscalls`
/// directly; instead, use the `Syscalls` trait, which provides higher-level
-/// interfaces to the system calls.
+/// interfaces to the system calls.**
// RawSyscalls is designed to minimize the amount of handwritten assembly code
// needed without generating unnecessary instructions. This comment describes
@@ -111,6 +111,7 @@
// pass YieldType rather than a usize because if we used usize directly then
// this API becomes unsound if the kernel adds support for an unsafe yield
// type (or even one that takes one more argument).
+ /// `raw_yield` should only be called by `libtock_platform`.
fn raw_yield(r0_in: YieldType) -> u32;
// four_arg_syscall is used to invoke the subscribe, command, read-write
@@ -136,6 +137,8 @@
//
// For subscribe(), the callback pointer should be either 0 (for the null
// callback) or an `unsafe extern fn(u32, u32, u32, usize)`.
+ /// `four_arg_syscall` should only be called by `libtock_platform`.
+ ///
/// # Safety
/// `four_arg_syscall` must NOT be used to invoke yield. Otherwise, it has
/// the same safety invariants as the underlying system call, which varies
@@ -175,6 +178,7 @@
// exist are safe. zero_arg_memop takes a ZeroArgMemop rather than a u32 so
// that if the kernel adds an unsafe memop -- or one that can clobber r2/r3
// -- this API doesn't become unsound.
+ /// `four_arg_syscall` should only be called by `libtock_platform`.
fn zero_arg_memop(r0_in: ZeroArgMemop) -> (u32, usize);
// one_arg_memop is used to invoke memop operations that take an argument.
@@ -199,6 +203,7 @@
// exist are safe. zero_arg_memop takes a ZeroArgMemop rather than a u32 so
// that if the kernel adds an unsafe memop -- or one that can clobber r2/r3
// -- this API doesn't become unsound.
+ /// `four_arg_syscall` should only be called by `libtock_platform`.
fn one_arg_memop(r0_in: OneArgMemop, r1: usize) -> (u32, usize);
}
