diff --git a/RELEASE-v0.8.md b/RELEASE-v0.8.md index 80b968b6e..4f5eef43f 100644 --- a/RELEASE-v0.8.md +++ b/RELEASE-v0.8.md @@ -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, +} +``` + +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, // this is only necessary if you have callbacks +} +impl MyServer { + pub fn new(xns: xous_names::XousNames) -> Result { + 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 { + 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 { + // 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 = 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; 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::().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::().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; 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"); + } + } + } +} +``` diff --git a/services/com/src/api.rs b/services/com/src/api.rs index 24fb0a899..a4659036d 100644 --- a/services/com/src/api.rs +++ b/services/com/src/api.rs @@ -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 diff --git a/services/com/src/lib.rs b/services/com/src/lib.rs index bf2680068..36bc5e762 100644 --- a/services/com/src/lib.rs +++ b/services/com/src/lib.rs @@ -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();} + } } diff --git a/services/com/src/main.rs b/services/com/src/main.rs index cee58f884..85f979067 100644 --- a/services/com/src/main.rs +++ b/services/com/src/main.rs @@ -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 { 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 { 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; 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; + } + } + } + } } } diff --git a/services/rkyv-test-client/src/main.rs b/services/rkyv-test-client/src/main.rs index 865783ceb..7e5a35b2c 100644 --- a/services/rkyv-test-client/src/main.rs +++ b/services/rkyv-test-client/src/main.rs @@ -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; } diff --git a/services/xous-names/src/lib.rs b/services/xous-names/src/lib.rs index cdda2ceef..bc0e1dcd6 100644 --- a/services/xous-names/src/lib.rs +++ b/services/xous-names/src/lib.rs @@ -20,7 +20,7 @@ impl XousNames { pub fn register_name(&self, name: &str) -> Result { 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 { 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))?;