Add the `CommandReturn` type.
The `command` system call will return a `CommandReturn`. `CommandReturn` is practically free to construct and contains methods to allow drivers to interpret the register values it contains.
diff --git a/core/platform/src/command_return.rs b/core/platform/src/command_return.rs
new file mode 100644
index 0000000..7b4abf3
--- /dev/null
+++ b/core/platform/src/command_return.rs
@@ -0,0 +1,163 @@
+use crate::{return_type, ErrorCode, ReturnType};
+
+/// The response type from `command`. Can represent a successful value or a
+/// failure.
+#[derive(Clone, Copy)]
+pub struct CommandReturn {
+ pub(crate) return_type: ReturnType,
+ // r1, r2, and r3 should only contain 32-bit values. However, these are
+ // converted directly from usizes returned by RawSyscalls::four_arg_syscall.
+ // To avoid casting twice (both when converting to a Command Return and when
+ // calling a get_*() function), we store the usizes directly. Then using the
+ // CommandReturn only involves one conversion for each of r1, r2, and r3,
+ // performed in the get_*() functions.
+ pub(crate) r1: usize,
+ pub(crate) r2: usize,
+ pub(crate) r3: usize,
+}
+
+impl CommandReturn {
+ // I generally expect CommandReturn to be used with pattern matching, e.g.:
+ //
+ // let command_return = Syscalls::command(314, 1, 1, 2);
+ // if let Some((val1, val2)) = command_return.get_success_2_u32() {
+ // // ...
+ // } else if let Some(error_code) = command_return.get_failure() {
+ // // ...
+ // } else {
+ // // Incorrect return type
+ // }
+
+ /// Returns true if this CommandReturn is of type Failure. Note that this
+ /// does not return true for other failure types, such as Failure with u32.
+ pub fn is_failure(&self) -> bool {
+ self.return_type == return_type::FAILURE
+ }
+
+ /// Returns true if this CommandReturn is of type Failure with u32.
+ pub fn is_failure_u32(&self) -> bool {
+ self.return_type == return_type::FAILURE_U32
+ }
+
+ /// Returns true if this CommandReturn is of type Failure with 2 u32.
+ pub fn is_failure_2_u32(&self) -> bool {
+ self.return_type == return_type::FAILURE_2_U32
+ }
+
+ /// Returns true if this CommandReturn is of type Failure with u64.
+ pub fn is_failure_u64(&self) -> bool {
+ self.return_type == return_type::FAILURE_U64
+ }
+
+ /// Returns true if this CommandReturn is of type Success. Note that this
+ /// does not return true for other success types, such as Success with u32.
+ pub fn is_success(&self) -> bool {
+ self.return_type == return_type::SUCCESS
+ }
+
+ /// Returns true if this CommandReturn is of type Success with u32.
+ pub fn is_success_u32(&self) -> bool {
+ self.return_type == return_type::SUCCESS_U32
+ }
+
+ /// Returns true if this CommandReturn is of type Success with 2 u32.
+ pub fn is_success_2_u32(&self) -> bool {
+ self.return_type == return_type::SUCCESS_2_U32
+ }
+
+ /// Returns true if this CommandReturn is of type Success with u64.
+ pub fn is_success_u64(&self) -> bool {
+ self.return_type == return_type::SUCCESS_U64
+ }
+
+ /// Returns true if this CommandReturn is of type Success with 3 u32.
+ pub fn is_success_3_u32(&self) -> bool {
+ self.return_type == return_type::SUCCESS_3_U32
+ }
+
+ /// Returns true if this CommandReturn is of type Success with u32 and u64.
+ pub fn is_success_u32_u64(&self) -> bool {
+ self.return_type == return_type::SUCCESS_U32_U64
+ }
+
+ /// Returns the error code if this CommandReturn is of type Failure.
+ pub fn get_failure(&self) -> Option<ErrorCode> {
+ if !self.is_failure() {
+ return None;
+ }
+ Some(self.r1.into())
+ }
+
+ /// Returns the error code and value if this CommandReturn is of type
+ /// Failure with u32.
+ pub fn get_failure_u32(&self) -> Option<(ErrorCode, u32)> {
+ if !self.is_failure_u32() {
+ return None;
+ }
+ Some((self.r1.into(), self.r2 as u32))
+ }
+
+ /// Returns the error code and return values if this CommandReturn is of
+ /// type Failure with 2 u32.
+ pub fn get_failure_2_u32(&self) -> Option<(ErrorCode, u32, u32)> {
+ if !self.is_failure_2_u32() {
+ return None;
+ }
+ Some((self.r1.into(), self.r2 as u32, self.r3 as u32))
+ }
+
+ /// Returns the error code and return value if this CommandReturn is of type
+ /// Failure with u64.
+ pub fn get_failure_u64(&self) -> Option<(ErrorCode, u64)> {
+ if !self.is_failure_u64() {
+ return None;
+ }
+ Some((self.r1.into(), self.r2 as u64 + ((self.r3 as u64) << 32)))
+ }
+
+ /// Returns the value if this CommandReturn is of type Success with u32.
+ pub fn get_success_u32(&self) -> Option<u32> {
+ if !self.is_success_u32() {
+ return None;
+ }
+ Some(self.r1 as u32)
+ }
+
+ /// Returns the values if this CommandReturn is of type Success with 2 u32.
+ pub fn get_success_2_u32(&self) -> Option<(u32, u32)> {
+ if !self.is_success_2_u32() {
+ return None;
+ }
+ Some((self.r1 as u32, self.r2 as u32))
+ }
+
+ /// Returns the value if this CommandReturn is of type Success with u64.
+ pub fn get_success_u64(&self) -> Option<u64> {
+ if !self.is_success_u64() {
+ return None;
+ }
+ Some(self.r1 as u64 + ((self.r2 as u64) << 32))
+ }
+
+ /// Returns the values if this CommandReturn is of type Success with 3 u32.
+ pub fn get_success_3_u32(&self) -> Option<(u32, u32, u32)> {
+ if !self.is_success_3_u32() {
+ return None;
+ }
+ Some((self.r1 as u32, self.r2 as u32, self.r3 as u32))
+ }
+
+ /// Returns the values if this CommandReturn is of type Success with u32 and
+ /// u64.
+ pub fn get_success_u32_u64(&self) -> Option<(u32, u64)> {
+ if !self.is_success_u32_u64() {
+ return None;
+ }
+ Some((self.r1 as u32, self.r2 as u64 + ((self.r3 as u64) << 32)))
+ }
+
+ /// Returns the return type of this command.
+ pub fn return_type(&self) -> ReturnType {
+ self.return_type
+ }
+}
diff --git a/core/platform/src/command_return_tests.rs b/core/platform/src/command_return_tests.rs
new file mode 100644
index 0000000..ccde359
--- /dev/null
+++ b/core/platform/src/command_return_tests.rs
@@ -0,0 +1,313 @@
+use crate::{error_code, return_type, CommandReturn};
+
+#[test]
+fn failure() {
+ let command_return = CommandReturn {
+ return_type: return_type::FAILURE,
+ r1: error_code::RESERVE.into(),
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), true);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), Some(error_code::RESERVE));
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::FAILURE);
+}
+
+#[test]
+fn failure_u32() {
+ let command_return = CommandReturn {
+ return_type: return_type::FAILURE_U32,
+ r1: error_code::OFF.into(),
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), true);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(
+ command_return.get_failure_u32(),
+ Some((error_code::OFF, 1002))
+ );
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::FAILURE_U32);
+}
+
+#[test]
+fn failure_2_u32() {
+ let command_return = CommandReturn {
+ return_type: return_type::FAILURE_2_U32,
+ r1: error_code::ALREADY.into(),
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), true);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(
+ command_return.get_failure_2_u32(),
+ Some((error_code::ALREADY, 1002, 1003))
+ );
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::FAILURE_2_U32);
+}
+
+#[test]
+fn failure_u64() {
+ let command_return = CommandReturn {
+ return_type: return_type::FAILURE_U64,
+ r1: error_code::BUSY.into(),
+ r2: 0x00001002,
+ r3: 0x00001003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), true);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(
+ command_return.get_failure_u64(),
+ Some((error_code::BUSY, 0x00001003_00001002))
+ );
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::FAILURE_U64);
+}
+
+#[test]
+fn success() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS,
+ r1: 1001,
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), true);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::SUCCESS);
+}
+
+#[test]
+fn success_u32() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS_U32,
+ r1: 1001,
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), true);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), Some(1001));
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::SUCCESS_U32);
+}
+
+#[test]
+fn success_2_u32() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS_2_U32,
+ r1: 1001,
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), true);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), Some((1001, 1002)));
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::SUCCESS_2_U32);
+}
+
+#[test]
+fn success_u64() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS_U64,
+ r1: 0x00001001,
+ r2: 0x00001002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), true);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), Some(0x00001002_00001001));
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::SUCCESS_U64);
+}
+
+#[test]
+fn success_3_u32() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS_3_U32,
+ r1: 1001,
+ r2: 1002,
+ r3: 1003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), true);
+ assert_eq!(command_return.is_success_u32_u64(), false);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), Some((1001, 1002, 1003)));
+ assert_eq!(command_return.get_success_u32_u64(), None);
+ assert_eq!(command_return.return_type(), return_type::SUCCESS_3_U32);
+}
+
+#[test]
+fn success_u32_u64() {
+ let command_return = CommandReturn {
+ return_type: return_type::SUCCESS_U32_U64,
+ r1: 1001,
+ r2: 0x00001002,
+ r3: 0x00001003,
+ };
+ assert_eq!(command_return.is_failure(), false);
+ assert_eq!(command_return.is_failure_u32(), false);
+ assert_eq!(command_return.is_failure_2_u32(), false);
+ assert_eq!(command_return.is_failure_u64(), false);
+ assert_eq!(command_return.is_success(), false);
+ assert_eq!(command_return.is_success_u32(), false);
+ assert_eq!(command_return.is_success_2_u32(), false);
+ assert_eq!(command_return.is_success_u64(), false);
+ assert_eq!(command_return.is_success_3_u32(), false);
+ assert_eq!(command_return.is_success_u32_u64(), true);
+ assert_eq!(command_return.get_failure(), None);
+ assert_eq!(command_return.get_failure_u32(), None);
+ assert_eq!(command_return.get_failure_2_u32(), None);
+ assert_eq!(command_return.get_failure_u64(), None);
+ assert_eq!(command_return.get_success_u32(), None);
+ assert_eq!(command_return.get_success_2_u32(), None);
+ assert_eq!(command_return.get_success_u64(), None);
+ assert_eq!(command_return.get_success_3_u32(), None);
+ assert_eq!(
+ command_return.get_success_u32_u64(),
+ Some((1001, 0x00001003_00001002))
+ );
+ assert_eq!(command_return.return_type(), return_type::SUCCESS_U32_U64);
+}
diff --git a/core/platform/src/error_code.rs b/core/platform/src/error_code.rs
index bd083e0..63cc34e 100644
--- a/core/platform/src/error_code.rs
+++ b/core/platform/src/error_code.rs
@@ -3,6 +3,11 @@
/// response to a system call.
// ErrorCode is not an enum so that conversion from the kernel's return value (a
// `usize` in a register) is free.
+// TODO: derive(Debug) is currently only enabled for test builds, which is
+// necessary so it can be used in assert_eq!. We should develop a lighter-weight
+// Debug implementation and see if it is small enough to enable on non-Debug
+// builds.
+#[cfg_attr(test, derive(Debug))]
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct ErrorCode(usize);
diff --git a/core/platform/src/lib.rs b/core/platform/src/lib.rs
index 9343145..460c999 100644
--- a/core/platform/src/lib.rs
+++ b/core/platform/src/lib.rs
@@ -1,6 +1,7 @@
#![no_std]
mod async_traits;
+mod command_return;
pub mod error_code;
mod raw_syscalls;
pub mod return_type;
@@ -8,7 +9,11 @@
mod syscalls_impl;
pub use async_traits::{CallbackContext, FreeCallback, Locator, MethodCallback};
+pub use command_return::CommandReturn;
pub use error_code::ErrorCode;
pub use raw_syscalls::{OneArgMemop, RawSyscalls, YieldType, ZeroArgMemop};
pub use return_type::ReturnType;
pub use syscalls::Syscalls;
+
+#[cfg(test)]
+mod command_return_tests;
diff --git a/core/platform/src/return_type.rs b/core/platform/src/return_type.rs
index da19e87..84fb8e9 100644
--- a/core/platform/src/return_type.rs
+++ b/core/platform/src/return_type.rs
@@ -1,5 +1,10 @@
/// `ReturnType` describes what value type the kernel has returned.
// ReturnType is not an enum so that it can be converted from a u32 for free.
+// TODO: derive(Debug) is currently only enabled for test builds, which is
+// necessary so it can be used in assert_eq!. We should develop a lighter-weight
+// Debug implementation and see if it is small enough to enable on non-Debug
+// builds.
+#[cfg_attr(test, derive(Debug))]
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct ReturnType(u32);
