Merge branch 'xous-ipc-refactor' of github.com:betrusted-io/xous-core into xous-ipc-refactor

This commit is contained in:
Sean Cross 2021-04-02 21:40:08 +08:00
commit 265f99c6ae
6 changed files with 395 additions and 44 deletions

View file

@ -48,6 +48,8 @@ compatibility, over refactoring and improvement.
as they fully block until a callback message arrives.
- Encapsulation of client-side API calls to a server within an object that
maintains variables like connection state.
- Addition of `Drop` trait to connection state objects, so when a client exits
connections clean themselves up.
- Splitting out return message definitions from the internal API enum. Previously,
we were re-using the API name space to define return messages. Now, there is
a distinction between client->server messages being enumerated, by convention,
@ -62,7 +64,326 @@ compatibility, over refactoring and improvement.
and `new_blocking_scalar()` to de-clutter code and make scalar messages a little bit
easier to deal with
## 0.8 API In Practice
## 0.8 Messaging API In Practice
Placeholder for some pointers to examples on how to use the 0.8 API to create
servers and message types.
Here are the idioms for building servers and passing messages.
### api.rs
Incoming messages are defined in an `Opcode` enum, by convention
```rust
#[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)]
pub(crate) enum Opcode {
ExampleScalar,
ExampleBlockingScalar,
ExampleMemory,
ExampleMemoryWithReturn,
RegisterCallback,
}
```
Synchronous return messages are defined in a `Return` enum, by convention
```rust
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub(crate) enum Return {
ExampleMemoryReturn(RichMemStruct),
Failure,
}
```
Asynchronous callback messages are defined in a `Callback` enum, by convention
```rust
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub(crate) enum Callback {
Hello,
Drop,
}
```
Rich memory structures for IPC are also defined in the api.rs crate. These may or may not
be scoped to crate-local.
```rust
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub(crate) struct RichMemStruct {
pub name: xous_ipc::String::<64>,
pub stuff: [u32; 42],
}
#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub struct AnotherRichStruct {
pub name: xous_ipc::String::<64>,
pub other: Option<bool>,
}
```
A server name is also defined in api.rs. This is a human-readable, 64-byte
description that uniquely identifies your server to the name server. This is
later mapped to a random 64-bit ID that only the name server knows.
```rust
pub(crate) const MY_SERVER_NAME: &str = "_Example server_"; // the underscores are optional, but they help readability in logs
```
### lib.rs
Client state is held in an object defined in lib.rs.
```rust
use api::{Callback, Opcode}; // if you prefer to map the api into your local namespace
use xous::{send_message, Error, CID, Message, msg_scalar_unpack};
use xous_ipc::{String, Buffer};
use num_traits::{ToPrimitive, FromPrimitive};
pub struct MyServer {
conn: xous::CID,
callback_sid: Option<xous::SID>, // this is only necessary if you have callbacks
}
impl MyServer {
pub fn new(xns: xous_names::XousNames) -> Result<Self, xous::Error> {
let conn = xns.request_connection_blocking(api::MY_SERVER_NAME).expect("Can't connect to MyServer");
Ok(MyServer {
conn,
callback_sid: None,
})
}
/// an example of a client requesting to send a message to MyServer
/// you can pass up to four usize-args this way, this example has none and just sends 4 zeros as placeholders
pub fn send_example_scalar(&self) -> Result<(), xous::Error> {
send_message(self.conn,
Message::new_scalar(Opcode::ExampleScalar.to_usize().unwrap()), 0, 0, 0, 0)
).map(|_|())
}
/// if you want some return data, a blocking scalar is the way to go
/// in this case, we introduce two arbitrary args, `a` and `b`, and return a u32
pub fn send_example_scalar(&self, a: u32, b: u32) -> Result<u32, xous::Error> {
let response = send_message(self.conn,
Message::new_blocking_scalar(Opcode::ExampleScalar.to_usize().unwrap()), a, b, 0, 0)
).map(|_|())
// you could also receive two scalar values if you use Scalar2 instead of Scalar1
if let xous::Result::Scalar1(result) = response {
Ok(result as u32)
} else {
log::error!("unexpected return value: {:#?}", response);
Err(xous::Error::InternalError)
}
}
/// an example of sending a rich data structure
pub fn send_richdata(&self, words: &str, stuff: [u32; 42]) -> Result<(), xous::Error> {
// build the structure up. Note that RichMemStruct is just inside the API! the caller doesn't need to know about it.
let mut rich_struct = RichMemStruct {
name: String::<64>::new(),
stuff,
};
use core::fmt::Write;
write!(rich_struct.name, "{}", words).expect("words too long");
// now convert it into a Xous::Buffer, which can then be lent to the server
let buf = Buffer::into_buf(rich_struct).or(Err(xous::Error:InternalError))?;
buf.lend(self.conn, Opcode::ExampleMemory.to_u32().unwrap()).map(|_| ())
}
/// an example of rich data with a return type
pub fn get_richdata(&self, stuff: [u32; 42]) -> Result<AnotherRichStruct, xous::Error> {
// build the query up. We're going to re-use RichMemStruct, but it could be anything
let mut rich_struct = RichMemStruct {
name: String::<64>::from_str("example rich query"),
stuff,
};
// now convert it into a Xous::Buffer, which can then be mutably lent to the server
let mut buf = Buffer::into_buf(rich_struct).or(Err(xous::Error:InternalError))?;
buf.lend_mut(self.conn, Opcode::ExampleMemoryWithReturn.to_u32().unwrap()).or(Err(xous::Error::InternalError))?;
// note that to_original() creates a local copy on the stack of the returned buffer
// if you just need to access fields, you can use to_flat() which is a
// zerocopy operation on an "Archived" version of your structure
match buf.to_original().unwrap() {
api::Return::ExampleMemoryReturn(rms) => {
Ok( AnotherRichStruct {
name: String::<64>::from_str(rms.name),
other: None,
} )
}
api::Return::Failure => {
Err(xous::Error::InternalError)
}
_ => panic!("Got unknown return code")
}
}
/// an example of registering for a callback
static mut MYSERVER_CB: Option<fn(BattStats)> = None;
pub fn hook_callback(&mut self, cb: fn(u32)) -> Result<(), xous::Error> {
if unsafe{MYSERVER_CB}.is_some() {
return Err(xous::Error::MemoryInUse) // can't hook it twice
}
unsafe{MYSERVER_CB = Some(cb)};
if self.callback_sid.is_none() {
let sid = xous::create_server().unwrap();
self.callback_sid = Some(sid);
let sid_tuple = sid.to_u32();
xous::create_thread_4(callback_server, sid_tuple.0 as usize, sid_tuple.1 as usize, sid_tuple.2 as usize, sid_tuple.3 as usize).unwrap();
xous::send_message(self.conn,
Message::new_scalar(Opcode::RegisterCallback.to_usize().unwrap(),
sid_tuple.0 as usize, sid_tuple.1 as usize, sid_tuple.2 as usize, sid_tuple.3 as usize
)).unwrap();
}
Ok(())
}
}
/// handles callback messages from the COM server, in the library user's process space.
fn callback_server(sid0: usize, sid1: usize, sid2: usize, sid3: usize) {
let sid = xous::SID::from_u32(sid0 as u32, sid1 as u32, sid2 as u32, sid3 as u32);
loop {
let msg = xous::receive_message(sid).unwrap();
match FromPrimitive::from_usize(msg.body.id()) {
Some(Callback::Hello) => msg_scalar_unpack!(msg, a, _, _, _, {
unsafe {
if let Some(cb) = MYSERVER_CB {
cb(a as u32)
}
}
}),
Some(Callback::Drop) => {
break; // this exits the loop and kills the thread
}
None => (),
}
}
}
impl Drop for MyServer {
fn drop(&mut self) {
// if we have callbacks, destroy the callback server
if let Some(sid) = self.callback_sid.take() {
// no need to tell the pstream server we're quitting: the next time a callback processes,
// it will automatically remove my entry as it will receive a ServerNotFound error.
// tell my handler thread to quit
let cid = xous::connect(sid).unwrap();
xous::send_message(cid,
Message::new_blocking_scalar(api::Callback::Drop.to_usize().unwrap(), 0, 0, 0, 0)).unwrap();
unsafe{xous::disconnect(cid).unwrap();}
xous::destroy_server(sid).unwrap();
}
// now de-allocate myself. It's unsafe because we are responsible to make sure nobody else is using the connection.
// all implementations will need this
unsafe{xous::disconnect(self.conn).unwrap();}
}
}
```
### main.rs
The server implementation is in main.rs. It handles the requests coming from lib.rs.
Here is a generic template example that doesn't do very much, other than exercise the four
API cases laid out above: sending a scalar message, handling a blocking scalar (e.g. scalar
message with return value), a "lend" memory message, and a "mutable lend" memory message (e.g.
a memory message with return value).
Note that all message types block the caller until they are returned.
```rust
use num_traits::FromPrimitive;
use xous_ipc::{String, Buffer};
use api::Opcode;
use xous::{CID, msg_scalar_unpack, msg_blocking_scalar_unpack};
#[xous::xous_main]
fn xmain() -> ! {
log_server::init_wait().unwrap();
info!("my PID is {}", xous::process::id()); // this is so we can figure out what PID goes to what server
let xns = xous_names::XousNames::new().unwrap();
let my_sid = xns.register_name(api::MY_SERVER_NAME).expect("can't register server");
trace!("registered with NS -- {:?}", sid);
// only needed if doing callbacks
let mut cb_conns: [Option<CID>; 32] = [None; 32];
loop {
let msg = xous::receive_message(sid).unwrap(); // this blocks until we get a message
trace!("Message: {:?}", msg);
match FromPrimitive::from_usize(msg.body.id()) {
Some(Opcode::ExampleScalar) => msg_scalar_unpack!(msg, _, _, _, _, { /* what the scalar message does */ }),
Some(Opcode::ExampleBlockingScalar) => msg_blocking_scalar_unpack!(msg, a, b, _, _, {
let value = a + b;
xous::return_scalar(msg.sender, value).expect("couldn't return value to ExampleBlockingScalar");
// note that you can also return two usize values with return_scalar2
}),
Some(Opcode::ExampleMemory) => {
let buffer = unsafe { Buffer::from_memory_message(msg.body.memory_message().unwrap()) };
let rms = buffer.to_flat::<RichMemStruct, _>().unwrap();
// we can now access fields in rms without copying the data
// use to_original if you need to invoke methods on the struct object
}
Some(Opcode::ExampleMemoryWithReturn) => {
let mut buffer = unsafe { Buffer::from_memory_message_mut(msg.body.memory_message_mut().unwrap()) };
let rms = buffer.to_original::<RichMemStruct, _>().unwrap();
let response = api::Return;
if things_look_okay {
let retstruct = AnotherRichStruct {
name: String::<64>::from_str(rms.as_str()),
other: Some(true),
}
response = api::Return::ExampleMemoryReturn(retstruct);
} else {
response = api::Return::Failure
}
buffer.replace(response).unwrap(); // the buffer that was sent is replaced with AnotherRichStruct
}
// only needed if doing callbacks
Some(Opcode::RegisterCallback) => msg_scalar_unpack!(msg, sid0, sid1, sid2, sid3, {
let sid = xous::SID::from_u32(sid0 as _, sid1 as _, sid2 as _, sid3 as _);
let cid = Some(xous::connect(sid).unwrap());
let mut found = false;
for entry in cb_conns.iter_mut() {
if *entry == None {
*entry = cid;
found = true;
break;
}
}
if !found {
error!("RegisterCallback listener ran out of space registering callback");
}
}
),
None => log::error!("couldn't convert opcode")
}
// if you have callbacks, you'll probably want to start a separate thread to handle them
// but for simplicity we just call a function here. But in this example, it means the callback
// can only gets processed after any message is received.
do_callback(&mut cb_conns);
}
}
/// only if doing callbacks. This might actually make more sense in a thread of its own, to make it
/// truly asynchronous, but this example is focused on the messaging API, not the threading API.
/// This example admittedly sweeps a rather hairy issue (passing data between process-local threads)
/// under the carpet. As of Xous 0.8 your options to send data around between threads within a process
/// are:
/// 1. Define a crate-local API to pass the messages
/// 2. Use Atomic data types (only applicable if you have primitive data to send)
/// 3. Do some static mut unsafe thing because we don't have a Mutex data type yet.
fn do_callback(&mut cb_conns: [Option<CID>; 32]) {
let a = useful_computation();
for maybe_conn in cb_conns.iter_mut() { // this code is notional and probably doesn't work
if let Some(conn) = maybe_conn {
match xous::send_message(conn,
xous:Message::new_scalar(api::Callback::Hello.to_usize().unwrap(), a, 0, 0, 0)
) {
Err(xous::Error::ServerNotFound) => {
maybe_conn = None // automatically de-allocate callbacks for clients that have dropped
},
Ok => {}
_ => panic!("unhandled error in callback processing");
}
}
}
}
```

View file

@ -1,12 +1,6 @@
use xous::{Message, ScalarMessage};
use xous_ipc::String;
// NOTE: the use of ComState "verbs" as commands is not meant as a 1:1 mapping of commands
// It's just a convenient abuse of already-defined constants. However, it's intended that
// the COM server on the SoC side abstracts much of the EC bus complexity away.
use com_rs::*;
use com_rs_ref as com_rs;
pub(crate) const SERVER_NAME_COM: &str = "_COM manager_";
#[derive(Debug, Default, Copy, Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
@ -41,7 +35,6 @@ impl Into<[usize; 2]> for BattStats {
]
}
}
#[allow(dead_code)]
#[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)]
pub(crate) enum Opcode {
/// Battery stats

View file

@ -1,7 +1,5 @@
#![cfg_attr(target_os = "none", no_std)]
use core::convert::TryInto;
/// This is the API that other servers use to call the COM. Read this code as if you
/// are calling these functions inside a different process.
pub mod api;
@ -23,7 +21,7 @@ fn battstats_server(sid0: usize, sid1: usize, sid2: usize, sid3: usize) {
loop {
let msg = xous::receive_message(sid).unwrap();
match FromPrimitive::from_usize(msg.body.id()) {
Some(api::Callback::BattStats) => msg_scalar_unpack!(msg, lo, hi, _, _, {
Some(Callback::BattStats) => msg_scalar_unpack!(msg, lo, hi, _, _, {
let bs: BattStats = [lo, hi].into();
unsafe {
if let Some(cb) = BATTSTATS_CB {
@ -31,7 +29,7 @@ fn battstats_server(sid0: usize, sid1: usize, sid2: usize, sid3: usize) {
}
}
}),
Some(api::Callback::Drop) => {
Some(Callback::Drop) => {
break; // this exits the loop and kills the thread
}
None => (),
@ -124,10 +122,21 @@ impl Com {
impl Drop for Com {
fn drop(&mut self) {
// tell my handler thread to quit
xous::send_message(self.conn,
Message::new_scalar(api::Callback::Drop.to_usize().unwrap(), 0, 0, 0, 0)).unwrap();
// now de-allocate myself
self.battstats_sid = None;
// if we have callbacks, destroy the battstats callback server
if let Some(sid) = self.battstats_sid.take() {
// no need to tell the COM server we're quitting: the next time a callback processes,
// it will automatically remove my entry as it will receive a ServerNotFound error.
// tell my handler thread to quit
let cid = xous::connect(sid).unwrap();
xous::send_message(cid,
Message::new_blocking_scalar(api::Callback::Drop.to_usize().unwrap(), 0, 0, 0, 0)).unwrap();
unsafe{xous::disconnect(cid).unwrap();}
xous::destroy_server(sid).unwrap();
}
// now de-allocate myself. It's unsafe because we are responsible to make sure nobody else is using the connection.
unsafe{xous::disconnect(self.conn).unwrap();}
}
}

View file

@ -4,7 +4,6 @@
mod api;
use api::Opcode;
use core::convert::TryFrom;
use num_traits::{ToPrimitive, FromPrimitive};
use log::{error, info, trace};
@ -12,7 +11,7 @@ use log::{error, info, trace};
use com_rs_ref as com_rs;
use com_rs::*;
use xous::{CID, msg_scalar_unpack, msg_blocking_scalar_unpack};
use xous::{CID, msg_scalar_unpack};
use xous_ipc::{Buffer, String};
const STD_TIMEOUT: u32 = 100;
@ -39,7 +38,6 @@ mod implementation {
use com_rs::*;
use log::error;
use utralib::generated::*;
use xous::CID;
use heapless::Vec;
use heapless::consts::U64;
@ -129,21 +127,31 @@ mod implementation {
self.txrx(tx)
}
pub fn process_queue(&mut self) {
pub fn process_queue(&mut self) -> Option<xous::CID> {
if !self.workqueue.is_empty() && !self.busy {
self.busy = true;
let work_descriptor = self.workqueue.swap_remove(0); // not quite FIFO, but Vec does not support FIFO (best we can do with "heapless")
if work_descriptor.work.verb == ComState::STAT.verb {
let ret = if work_descriptor.work.verb == ComState::STAT.verb {
let stats = self.get_battstats();
return_battstats(work_descriptor.sender, stats)
.expect("Could not return BattStatsNb value");
match return_battstats(work_descriptor.sender, stats) {
Err(xous::Error::ServerNotFound) => {
// the callback target has quit, so de-allocate it from our list
Some(work_descriptor.sender)
},
Ok(()) => None,
_ => panic!("unhandled error in callback process_queue"),
}
} else {
error!(
"unimplemented work queue responder 0x{:x}",
work_descriptor.work.verb
);
}
None
};
self.busy = false;
ret
} else {
None
}
}
@ -209,21 +217,31 @@ mod implementation {
}
}
pub fn process_queue(&mut self) {
pub fn process_queue(&mut self) -> Option<xous::CID> {
if !self.workqueue.is_empty() && !self.busy {
self.busy = true;
let work_descriptor = self.workqueue.swap_remove(0); // not quite FIFO, but Vec does not support FIFO (best we can do with "heapless")
if work_descriptor.work.verb == ComState::STAT.verb {
let ret = if work_descriptor.work.verb == ComState::STAT.verb {
let stats = self.get_battstats();
return_battstats(work_descriptor.sender, stats)
.expect("Could not return BattStatsNb value");
match return_battstats(work_descriptor.sender, stats) {
Err(xous::Error::ServerNotFound) => {
// the callback target has quit, so de-allocate it from our list
Some(work_descriptor.sender)
},
Ok(()) => None,
_ => panic!("unhandled error in callback process_queue"),
}
} else {
error!(
"unimplemented work queue responder 0x{:x}",
work_descriptor.work.verb
);
}
None
};
self.busy = false;
ret
} else {
None
}
}
}
@ -232,16 +250,13 @@ mod implementation {
#[xous::xous_main]
fn xmain() -> ! {
use crate::implementation::XousCom;
use core::pin::Pin;
use xous::buffer;
use rkyv::archived_value_mut;
log_server::init_wait().unwrap();
info!("my PID is {}", xous::process::id());
let xns = xous_names::XousNames::new().unwrap();
let com_sid = xns.register_name(api::SERVER_NAME_COM).expect("can't register server");
info!("registered with NS -- {:?}", com_sid);
trace!("registered with NS -- {:?}", com_sid);
// Create a new com object
let mut com = XousCom::new();
@ -250,7 +265,7 @@ fn xmain() -> ! {
let mut battstats_conns: [Option<xous::CID>; 32] = [None; 32];
// other future notification vectors shall go here
info!("starting main loop");
trace!("starting main loop");
loop {
let msg = xous::receive_message(com_sid).unwrap();
trace!("Message: {:?}", msg);
@ -346,6 +361,15 @@ fn xmain() -> ! {
None => error!("unknown opcode"),
}
com.process_queue();
if let Some(dropped_cid) = com.process_queue() {
for entry in battstats_conns.iter_mut() {
if let Some(cid) = *entry {
if cid == dropped_cid {
*entry = None;
break;
}
}
}
}
}
}

View file

@ -13,6 +13,10 @@ fn print_log_messages(log_message: &str, prefix: &str) {
fn handle_battstats(bs: com::BattStats) {
log::info!("battstats: {:?}", bs);
// note: at this point to repatriate data into the core main loop, you have two options:
// 1. send a new message to the server, using your own private API. This feels "wasteful"
// as you're bouncing a message twice but it keeps the API spaces strictly on crate boundaries
// 2. use an Atomic type to transfer primitive data types from the handler thread to the main thread
}
#[xous::xous_main]
@ -37,7 +41,7 @@ fn rkyv_test_client() -> ! {
let xns = xous_names::XousNames::new().unwrap();
let mut com = com::Com::new(xns).unwrap();
com.hook_batt_stats(handle_battstats);
com.hook_batt_stats(handle_battstats).unwrap();
loop {
log::info!("2 + {} = {}", idx, rkyv_test_server::add(2, idx).unwrap());
@ -57,7 +61,7 @@ fn rkyv_test_client() -> ! {
log::info!("Sending a string \"{}\"", sent_str);
rkyv_test_server::log_message("prefix", sent_str);
com.req_batt_stats();
com.req_batt_stats().unwrap();
idx += 1;
}

View file

@ -20,7 +20,7 @@ impl XousNames {
pub fn register_name(&self, name: &str) -> Result<xous::SID, xous::Error> {
let mut registration_name = String::<64>::new();
// could also do String::from_str() but in this case we want things to fail if the string is too long.
write!(registration_name, "{}", name).expect("NS: name probably too long");
write!(registration_name, "{}", name).expect("name probably too long");
let mut buf = Buffer::into_buf(registration_name).or(Err(xous::Error::InternalError))?;
@ -33,20 +33,20 @@ impl XousNames {
match buf.to_original().unwrap() {
api::Return::SID(sid_raw) => {
let sid = sid_raw.into();
xous::create_server_with_sid(sid).expect("NS: can't auto-register server");
xous::create_server_with_sid(sid).expect("can't auto-register server");
Ok(sid)
}
api::Return::Failure => {
Err(xous::Error::InternalError)
}
_ => unimplemented!("NS: unimplemented return codes")
_ => unimplemented!("unimplemented return codes")
}
}
/// note: if this throws an AccessDenied error, you can retry with a request_authenticate_connection() call (to be written)
pub fn request_connection(&self, name: &str) -> Result<xous::CID, xous::Error> {
let mut lookup_name = xous_ipc::String::<64>::new();
write!(lookup_name, "{}", name).expect("NS: name problably too long");
write!(lookup_name, "{}", name).expect("name problably too long");
let mut buf = Buffer::into_buf(lookup_name).or(Err(xous::Error::InternalError))?;