xous: split messages into a sub-module

The `Messages` types were getting hairy, and `definitions.rs` was really
long. Trim it down by moving types into their own files.

Signed-off-by: Sean Cross <sean@xobs.io>
This commit is contained in:
Sean Cross 2022-04-25 11:27:25 +08:00
parent f531955c44
commit 2084a9cda4
7 changed files with 387 additions and 373 deletions

View file

@ -1,10 +1,9 @@
use core::convert::{TryFrom, TryInto};
use core::convert::TryInto;
use core::num::{NonZeroU8, NonZeroUsize};
pub type MemoryAddress = NonZeroUsize;
pub type MemorySize = NonZeroUsize;
pub type StackPointer = usize;
pub type MessageId = usize;
pub type PID = NonZeroU8;
pub type Connection = usize;
@ -56,31 +55,8 @@ pub static TESTING_RNG_SEED: AtomicU64 = AtomicU64::new(0);
pub mod exceptions;
pub use exceptions::*;
#[derive(Debug, PartialEq, Eq, Ord, PartialOrd, Copy, Clone, Default)]
pub struct MessageSender {
data: usize,
}
impl MessageSender {
pub fn to_usize(&self) -> usize {
self.data
}
pub fn from_usize(data: usize) -> Self {
MessageSender { data }
}
pub fn pid(&self) -> Option<PID> {
let pid_u8 = ((self.data >> 24) & 0xff) as u8;
PID::new(pid_u8)
}
}
impl core::fmt::Display for MessageSender {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(f, "MessageSender.data: 0x{:08x}", self.data)
}
}
pub mod messages;
pub use messages::*;
/// Server ID
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
@ -318,349 +294,6 @@ pub struct Context {
pid: PID,
}
#[repr(C)]
#[derive(Debug, PartialEq)]
/// A struct describing memory that is passed between processes.
/// The `buf` value will get translated as necessary.
pub struct MemoryMessage {
/// A user-assignable message ID.
pub id: MessageId,
/// The offset of the buffer. This address will get transformed when the
/// message is moved between processes.
pub buf: MemoryRange,
/// The offset within the buffer where the interesting stuff starts. The usage
/// of this field is purely advisory, is not checked by the kernel, should not
/// be trusted by the receiver. It is perfectly legal for this to be larger
/// than the buffer size.
///
/// As a result, this field may be repurposed for other uses. For example,
/// you can store a `usize` in this field by setting
/// `message.offset = MemoryAddress::new(val)`, and get a `usize` back by
/// reading `message.offset.map(|v| v.get()).unwrap_or_default()`.
///
/// For `MutableBorrow` messages this value will be returned to the sender and the
/// field will be updated when the Message is returned. Therefore you may also use
/// this field to communicate additional information to the message sender.
pub offset: Option<MemoryAddress>,
/// How many bytes in the buffer are valid. This field is advisory, and is not
/// checked by the kernel. It is legal for the sender to specify a `valid` range
/// that is larger than `buf.len()`, so this value should not be blindly trusted.
///
/// As a result, this field may be repurposed for other uses. For example,
/// you can store a `usize` in this field by setting
/// `message.valid = MemoryAddress::new(val)`, and get a `usize` back by
/// reading `message.valid.map(|v| v.get()).unwrap_or_default()`.
///
/// For `MutableBorrow` messages this value will be returned to the sender and the
/// field will be updated when the Message is returned. Therefore you may also use
/// this field to communicate additional information to the message sender.
pub valid: Option<MemorySize>,
}
impl MemoryMessage {
pub fn from_usize(
id: usize,
addr: usize,
size: usize,
offset: usize,
valid: usize,
) -> Option<MemoryMessage> {
let addr = match MemoryAddress::new(addr) {
None => return None,
Some(s) => s,
};
let size = match MemorySize::new(size) {
None => return None,
Some(s) => s,
};
let buf = MemoryRange { addr, size };
let offset = MemoryAddress::new(offset);
let valid = MemorySize::new(valid);
Some(MemoryMessage {
id,
buf,
offset,
valid,
})
}
pub fn to_usize(&self) -> [usize; 5] {
[
self.id,
self.buf.addr.get(),
self.buf.size.get(),
self.offset.map(|e| e.get()).unwrap_or(0),
self.valid.map(|e| e.get()).unwrap_or(0),
]
}
}
#[repr(C)]
#[derive(Debug, PartialEq, Clone, Copy)]
/// A simple scalar message. This is similar to a `move` message.
pub struct ScalarMessage {
pub id: MessageId,
pub arg1: usize,
pub arg2: usize,
pub arg3: usize,
pub arg4: usize,
}
impl ScalarMessage {
pub fn from_usize(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> ScalarMessage {
ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
}
}
pub fn to_usize(&self) -> [usize; 5] {
[self.id, self.arg1, self.arg2, self.arg3, self.arg4]
}
}
#[repr(usize)]
#[derive(Debug, PartialEq)]
pub enum Message {
MutableBorrow(MemoryMessage),
Borrow(MemoryMessage),
Move(MemoryMessage),
Scalar(ScalarMessage),
BlockingScalar(ScalarMessage),
}
impl Message {
pub fn new_scalar(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> crate::Message {
Message::Scalar(crate::ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
})
}
pub fn new_blocking_scalar(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> crate::Message {
Message::BlockingScalar(crate::ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
})
}
pub fn new_lend(
id: usize,
buf: MemoryRange,
offset: Option<MemoryAddress>,
valid: Option<MemorySize>,
) -> crate::Message {
Message::Borrow(crate::MemoryMessage {
id,
buf,
offset,
valid,
})
}
pub fn new_lend_mut(
id: usize,
buf: MemoryRange,
offset: Option<MemoryAddress>,
valid: Option<MemorySize>,
) -> crate::Message {
Message::MutableBorrow(crate::MemoryMessage {
id,
buf,
offset,
valid,
})
}
/// Determine whether the specified Message will block
pub fn is_blocking(&self) -> bool {
match *self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::BlockingScalar(_) => true,
Message::Move(_) | Message::Scalar(_) => false,
}
}
/// Determine whether the specified message has data attached
pub fn has_memory(&self) -> bool {
match *self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::Move(_) => true,
Message::BlockingScalar(_) | Message::Scalar(_) => false,
}
}
pub fn memory(&self) -> Option<&MemoryRange> {
self.memory_message().map(|msg| &msg.buf)
}
pub fn memory_message(&self) -> Option<&MemoryMessage> {
match self {
Message::MutableBorrow(mem) | Message::Borrow(mem) | Message::Move(mem) => Some(mem),
Message::BlockingScalar(_) | Message::Scalar(_) => None,
}
}
pub fn memory_message_mut(&mut self) -> Option<&mut MemoryMessage> {
match self {
Message::MutableBorrow(mem) | Message::Move(mem) => Some(mem),
Message::BlockingScalar(_) | Message::Scalar(_) | Message::Borrow(_) => None,
}
}
pub fn scalar_message(&self) -> Option<&ScalarMessage> {
match self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::Move(_) => None,
Message::BlockingScalar(scalar) | Message::Scalar(scalar) => Some(scalar),
}
}
pub(crate) fn message_type(&self) -> usize {
match *self {
Message::MutableBorrow(_) => 1,
Message::Borrow(_) => 2,
Message::Move(_) => 3,
Message::Scalar(_) => 4,
Message::BlockingScalar(_) => 5,
}
}
/// Return the ID of this message
pub fn id(&self) -> usize {
match &self {
&Message::MutableBorrow(mem) | &Message::Borrow(mem) | &Message::Move(mem) => mem.id,
&Message::Scalar(s) | &Message::BlockingScalar(s) => s.id,
}
}
}
impl TryFrom<(usize, usize, usize, usize, usize, usize)> for Message {
type Error = ();
fn try_from(
value: (usize, usize, usize, usize, usize, usize),
) -> core::result::Result<Self, Self::Error> {
match value.0 {
1 => Ok(Message::MutableBorrow(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
2 => Ok(Message::Borrow(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
3 => Ok(Message::Move(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
4 => Ok(Message::Scalar(ScalarMessage {
id: value.1,
arg1: value.2,
arg2: value.3,
arg3: value.4,
arg4: value.5,
})),
5 => Ok(Message::BlockingScalar(ScalarMessage {
id: value.1,
arg1: value.2,
arg2: value.3,
arg3: value.4,
arg4: value.5,
})),
_ => Err(()),
}
}
}
#[repr(C)]
#[derive(Debug, PartialEq)]
pub struct MessageEnvelope {
pub sender: MessageSender,
pub body: Message,
}
impl MessageEnvelope {
pub fn to_usize(&self) -> [usize; 7] {
let ret = match &self.body {
Message::MutableBorrow(m) => (0, m.to_usize()),
Message::Borrow(m) => (1, m.to_usize()),
Message::Move(m) => (2, m.to_usize()),
Message::Scalar(m) => (3, m.to_usize()),
Message::BlockingScalar(m) => (4, m.to_usize()),
};
[
self.sender.to_usize(),
ret.0,
ret.1[0],
ret.1[1],
ret.1[2],
ret.1[3],
ret.1[4],
]
}
}
#[cfg(not(feature = "forget-memory-messages"))]
/// When a MessageEnvelope goes out of scope, return the memory. It must either
/// go to the kernel (in the case of a Move), or back to the borrowed process
/// (in the case of a Borrow). Ignore Scalar messages.
impl Drop for MessageEnvelope {
fn drop(&mut self) {
match &self.body {
Message::Borrow(x) | Message::MutableBorrow(x) => {
crate::syscall::return_memory_offset_valid(self.sender, x.buf, x.offset, x.valid)
.expect("couldn't return memory")
}
Message::Move(msg) => {
// Reconstitute the vec and drop it right away to ensure it's freed.
#[cfg(any(unix, windows))]
let _v = unsafe {
std::vec::Vec::from_raw_parts(
msg.buf.as_mut_ptr(),
msg.buf.len(),
msg.buf.len(),
)
};
#[cfg(not(any(unix, windows)))]
crate::syscall::unmap_memory(msg.buf).expect("couldn't free memory message")
}
_ => (),
}
}
}
impl MemoryRange {
/// # Safety
///

View file

@ -0,0 +1,58 @@
use super::{Message, MessageSender};
#[repr(C)]
#[derive(Debug, PartialEq)]
pub struct Envelope {
pub sender: MessageSender,
pub body: Message,
}
impl Envelope {
pub fn to_usize(&self) -> [usize; 7] {
let ret = match &self.body {
Message::MutableBorrow(m) => (0, m.to_usize()),
Message::Borrow(m) => (1, m.to_usize()),
Message::Move(m) => (2, m.to_usize()),
Message::Scalar(m) => (3, m.to_usize()),
Message::BlockingScalar(m) => (4, m.to_usize()),
};
[
self.sender.to_usize(),
ret.0,
ret.1[0],
ret.1[1],
ret.1[2],
ret.1[3],
ret.1[4],
]
}
}
#[cfg(not(feature = "forget-memory-messages"))]
/// When a MessageEnvelope goes out of scope, return the memory. It must either
/// go to the kernel (in the case of a Move), or back to the borrowed process
/// (in the case of a Borrow). Ignore Scalar messages.
impl Drop for Envelope {
fn drop(&mut self) {
match &self.body {
Message::Borrow(x) | Message::MutableBorrow(x) => {
crate::syscall::return_memory_offset_valid(self.sender, x.buf, x.offset, x.valid)
.expect("couldn't return memory")
}
Message::Move(msg) => {
// Reconstitute the vec and drop it right away to ensure it's freed.
#[cfg(any(unix, windows))]
let _v = unsafe {
std::vec::Vec::from_raw_parts(
msg.buf.as_mut_ptr(),
msg.buf.len(),
msg.buf.len(),
)
};
#[cfg(not(any(unix, windows)))]
crate::syscall::unmap_memory(msg.buf).expect("couldn't free memory message")
}
_ => (),
}
}
}

View file

@ -0,0 +1 @@
pub type Id = usize;

View file

@ -0,0 +1,298 @@
use core::convert::TryFrom;
pub mod envelope;
pub use envelope::Envelope as MessageEnvelope;
pub mod sender;
pub use sender::Sender as MessageSender;
pub mod id;
pub use id::Id as MessageId;
use super::{MemoryRange, MemoryAddress, MemorySize};
#[repr(C)]
#[derive(Debug, PartialEq)]
/// A struct describing memory that is passed between processes.
/// The `buf` value will get translated as necessary.
pub struct MemoryMessage {
/// A user-assignable message ID.
pub id: MessageId,
/// The offset of the buffer. This address will get transformed when the
/// message is moved between processes.
pub buf: MemoryRange,
/// The offset within the buffer where the interesting stuff starts. The usage
/// of this field is purely advisory, is not checked by the kernel, should not
/// be trusted by the receiver. It is perfectly legal for this to be larger
/// than the buffer size.
///
/// As a result, this field may be repurposed for other uses. For example,
/// you can store a `usize` in this field by setting
/// `message.offset = MemoryAddress::new(val)`, and get a `usize` back by
/// reading `message.offset.map(|v| v.get()).unwrap_or_default()`.
///
/// For `MutableBorrow` messages this value will be returned to the sender and the
/// field will be updated when the Message is returned. Therefore you may also use
/// this field to communicate additional information to the message sender.
pub offset: Option<MemoryAddress>,
/// How many bytes in the buffer are valid. This field is advisory, and is not
/// checked by the kernel. It is legal for the sender to specify a `valid` range
/// that is larger than `buf.len()`, so this value should not be blindly trusted.
///
/// As a result, this field may be repurposed for other uses. For example,
/// you can store a `usize` in this field by setting
/// `message.valid = MemoryAddress::new(val)`, and get a `usize` back by
/// reading `message.valid.map(|v| v.get()).unwrap_or_default()`.
///
/// For `MutableBorrow` messages this value will be returned to the sender and the
/// field will be updated when the Message is returned. Therefore you may also use
/// this field to communicate additional information to the message sender.
pub valid: Option<MemorySize>,
}
impl MemoryMessage {
pub fn from_usize(
id: usize,
addr: usize,
size: usize,
offset: usize,
valid: usize,
) -> Option<MemoryMessage> {
let addr = match MemoryAddress::new(addr) {
None => return None,
Some(s) => s,
};
let size = match MemorySize::new(size) {
None => return None,
Some(s) => s,
};
let buf = MemoryRange { addr, size };
let offset = MemoryAddress::new(offset);
let valid = MemorySize::new(valid);
Some(MemoryMessage {
id,
buf,
offset,
valid,
})
}
pub fn to_usize(&self) -> [usize; 5] {
[
self.id,
self.buf.addr.get(),
self.buf.size.get(),
self.offset.map(|e| e.get()).unwrap_or(0),
self.valid.map(|e| e.get()).unwrap_or(0),
]
}
}
#[repr(C)]
#[derive(Debug, PartialEq, Clone, Copy)]
/// A simple scalar message. This is similar to a `move` message.
pub struct ScalarMessage {
pub id: MessageId,
pub arg1: usize,
pub arg2: usize,
pub arg3: usize,
pub arg4: usize,
}
impl ScalarMessage {
pub fn from_usize(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> ScalarMessage {
ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
}
}
pub fn to_usize(&self) -> [usize; 5] {
[self.id, self.arg1, self.arg2, self.arg3, self.arg4]
}
}
#[repr(usize)]
#[derive(Debug, PartialEq)]
pub enum Message {
MutableBorrow(MemoryMessage),
Borrow(MemoryMessage),
Move(MemoryMessage),
Scalar(ScalarMessage),
BlockingScalar(ScalarMessage),
}
impl Message {
pub fn new_scalar(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> crate::Message {
Message::Scalar(crate::ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
})
}
pub fn new_blocking_scalar(
id: usize,
arg1: usize,
arg2: usize,
arg3: usize,
arg4: usize,
) -> crate::Message {
Message::BlockingScalar(crate::ScalarMessage {
id,
arg1,
arg2,
arg3,
arg4,
})
}
pub fn new_lend(
id: usize,
buf: MemoryRange,
offset: Option<MemoryAddress>,
valid: Option<MemorySize>,
) -> crate::Message {
Message::Borrow(crate::MemoryMessage {
id,
buf,
offset,
valid,
})
}
pub fn new_lend_mut(
id: usize,
buf: MemoryRange,
offset: Option<MemoryAddress>,
valid: Option<MemorySize>,
) -> crate::Message {
Message::MutableBorrow(crate::MemoryMessage {
id,
buf,
offset,
valid,
})
}
/// Determine whether the specified Message will block
pub fn is_blocking(&self) -> bool {
match *self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::BlockingScalar(_) => true,
Message::Move(_) | Message::Scalar(_) => false,
}
}
/// Determine whether the specified message has data attached
pub fn has_memory(&self) -> bool {
match *self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::Move(_) => true,
Message::BlockingScalar(_) | Message::Scalar(_) => false,
}
}
pub fn memory(&self) -> Option<&MemoryRange> {
self.memory_message().map(|msg| &msg.buf)
}
pub fn memory_message(&self) -> Option<&MemoryMessage> {
match self {
Message::MutableBorrow(mem) | Message::Borrow(mem) | Message::Move(mem) => Some(mem),
Message::BlockingScalar(_) | Message::Scalar(_) => None,
}
}
pub fn memory_message_mut(&mut self) -> Option<&mut MemoryMessage> {
match self {
Message::MutableBorrow(mem) | Message::Move(mem) => Some(mem),
Message::BlockingScalar(_) | Message::Scalar(_) | Message::Borrow(_) => None,
}
}
pub fn scalar_message(&self) -> Option<&ScalarMessage> {
match self {
Message::MutableBorrow(_) | Message::Borrow(_) | Message::Move(_) => None,
Message::BlockingScalar(scalar) | Message::Scalar(scalar) => Some(scalar),
}
}
pub(crate) fn message_type(&self) -> usize {
match *self {
Message::MutableBorrow(_) => 1,
Message::Borrow(_) => 2,
Message::Move(_) => 3,
Message::Scalar(_) => 4,
Message::BlockingScalar(_) => 5,
}
}
/// Return the ID of this message
pub fn id(&self) -> usize {
match &self {
&Message::MutableBorrow(mem) | &Message::Borrow(mem) | &Message::Move(mem) => mem.id,
&Message::Scalar(s) | &Message::BlockingScalar(s) => s.id,
}
}
}
impl TryFrom<(usize, usize, usize, usize, usize, usize)> for Message {
type Error = ();
fn try_from(
value: (usize, usize, usize, usize, usize, usize),
) -> core::result::Result<Self, Self::Error> {
match value.0 {
1 => Ok(Message::MutableBorrow(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
2 => Ok(Message::Borrow(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
3 => Ok(Message::Move(MemoryMessage {
id: value.1,
buf: unsafe { MemoryRange::new(value.2, value.3).map_err(|_| ()) }?,
offset: MemoryAddress::new(value.4),
valid: MemorySize::new(value.5),
})),
4 => Ok(Message::Scalar(ScalarMessage {
id: value.1,
arg1: value.2,
arg2: value.3,
arg3: value.4,
arg4: value.5,
})),
5 => Ok(Message::BlockingScalar(ScalarMessage {
id: value.1,
arg1: value.2,
arg2: value.3,
arg3: value.4,
arg4: value.5,
})),
_ => Err(()),
}
}
}

View file

@ -0,0 +1,27 @@
use crate::PID;
#[derive(Debug, PartialEq, Eq, Ord, PartialOrd, Copy, Clone, Default)]
pub struct Sender {
data: usize,
}
impl Sender {
pub fn to_usize(&self) -> usize {
self.data
}
pub fn from_usize(data: usize) -> Self {
Sender { data }
}
pub fn pid(&self) -> Option<PID> {
let pid_u8 = ((self.data >> 24) & 0xff) as u8;
PID::new(pid_u8)
}
}
impl core::fmt::Display for Sender {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
write!(f, "MessageSender.data: 0x{:08x}", self.data)
}
}

View file

@ -13,7 +13,6 @@ pub mod arch;
pub mod carton;
pub mod definitions;
mod messages;
pub mod process;
pub mod string;
@ -22,7 +21,6 @@ pub mod syscall;
pub use arch::{ProcessArgs, ProcessInit, ProcessKey, ThreadInit};
pub use definitions::*;
pub use messages::*;
pub use string::*;
pub use stringbuffer::*;
pub use syscall::*;

View file

@ -1 +0,0 @@