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.

core/platform/src/raw_syscalls.rs

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);
 }