diff --git a/api/susres/Cargo.toml b/api/susres/Cargo.toml new file mode 100644 index 000000000..44b324cbe --- /dev/null +++ b/api/susres/Cargo.toml @@ -0,0 +1,27 @@ +[package] +name = "xous-api-susres" +version = "0.9.0" +authors = ["bunnie "] +edition = "2018" +description = "Manager of suspend/resume operations" + +# Dependency versions enforced by Cargo.lock. +[dependencies] +xous = "0.9.9" +log-server = { version = "0.1.3", package = "xous-api-log" } +xous-names = { version = "0.9.3", package = "xous-api-names" } +log = "0.4.14" +xous-ipc = "0.9.9" +num-derive = {version = "0.3.3", default-features = false} +num-traits = {version = "0.2.14", default-features = false} +rkyv = {version = "0.4.3", default-features = false, features = ["const_generics"]} + +utralib = { version = "0.1.3", optional = true, default-features = false } + +[features] +precursor = ["utralib/precursor"] +hosted = ["utralib/hosted"] +renode = ["utralib/renode"] +sus_reboot = [] # when selected, suspend triggers an immediate reboot instead of suspend. For testing only. +debugprint = [] +default = [] diff --git a/api/susres/README.md b/api/susres/README.md new file mode 100644 index 000000000..cbbd5d9b8 --- /dev/null +++ b/api/susres/README.md @@ -0,0 +1,17 @@ +# Xous Api: susres + +This crate defines the Xous suspend/resume API. + +The suspend/resume API is responsible for sequencing events before +a system powers down, such that all of the SoC hardware blocks will +lose state, but the RAM will retain its contents. + +Every service that contains hardware state which can be lost when +the SoC is powered down must register with the sequencer, and it +must atomically back up its hardware state to battery-backed RAM +and then call `suspend_until_resume`, which will block until power +is restored. Once power is restored, the service should copy the +hardware state out of battery-backed RAM and resume operations. + +The API also contains hooks for initiating the suspend process, +and for rebooting the device. diff --git a/api/susres/src/api.rs b/api/susres/src/api.rs new file mode 100644 index 000000000..514d2857d --- /dev/null +++ b/api/susres/src/api.rs @@ -0,0 +1,239 @@ +#![cfg_attr(not(target_os = "none"), allow(dead_code))] + +#[cfg(any(feature="precursor", feature="renode"))] +use utralib::generated::*; + +pub const SERVER_NAME_SUSRES: &str = "_Suspend/resume manager_"; + +/// Note: there must be at least one subscriber to the `Last` suspend order event, otherwise +/// the logic will never terminate. There may be multiple `Last` subscribers, but the order at +/// which they finish would be indeterminate. Currently, the `Last` subscriber is the `spinor` +/// block, which is last because you want to make sure all the PDDB commits and other saved +/// data are flushed before turning off access to the SPINOR. +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone, PartialEq, Eq)] +pub enum SuspendOrder { + Early, + Normal, + Late, + Later, + Last, +} +impl SuspendOrder { + pub fn next(&self) -> SuspendOrder { + match self { + SuspendOrder::Early => SuspendOrder::Normal, + SuspendOrder::Normal => SuspendOrder::Late, + SuspendOrder::Late => SuspendOrder::Later, + SuspendOrder::Later => SuspendOrder::Last, + SuspendOrder::Last => SuspendOrder::Last, + } + } +} + +#[derive(num_derive::FromPrimitive, num_derive::ToPrimitive, Debug)] +pub enum Opcode { + /// requests a suspend + SuspendRequest, + /// locks out suspend capability -- meant to be used only to prevent suspend during firmware updates + SuspendDeny, + /// unlocks suspend capability + SuspendAllow, + + /// register a subscriber to the suspend event + /// (if you don't register, you just get suspend without any warning!) + SuspendEventSubscribe, + + /// indicate we're ready to suspend + SuspendReady, + + /// from the timeout thread + SuspendTimeout, + + /// queries if my suspend was clean or not + WasSuspendClean, + + /// reboot opcodes + RebootRequest, + RebootSocConfirm, // all peripherals + CPU + RebootCpuConfirm, // just the CPU, peripherals (in particular the USB debug bridge) keep state + + /// not tested - reboot address + RebootVector, //(u32), + + /// used by processes to indicate they are suspending now; this blocks until resume using the "execution gate" + SuspendingNow, + + /// exit the server + Quit, +} + +#[derive(Debug, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, Copy, Clone)] +pub struct ScalarHook { + pub sid: (u32, u32, u32, u32), + pub id: u32, // ID of the scalar message to send through (e.g. the discriminant of the Enum on the caller's side API) + pub cid: xous::CID, // caller-side connection ID for the scalar message to route to. Created by the caller before hooking. + pub order: SuspendOrder, +} + +#[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)] +pub enum SuspendEventCallback { + Event, // this contains a token as well which must be returned to indicate you're ready for the suspend + Drop, +} + + +///////////////////////////////////////////////////////////////////////// +/////////////////////////// suspend-resume hardware management primitives +///////////////////////////////////////////////////////////////////////// +#[cfg(any(feature="precursor", feature="renode"))] +#[allow(dead_code)] +#[derive(Debug, Copy, Clone)] +pub enum RegOrField { + Field(Field), + Reg(Register), +} +#[cfg(any(feature="precursor", feature="renode"))] +#[allow(dead_code)] +#[derive(Debug, Copy, Clone)] +pub struct ManagedReg { + /// register, or a field of a register + pub item: RegOrField, + /// override the default mask value if Some() - mask is aligned to the register or field (do not shift the mask to the left to correspond to the actual bit position) + pub mask: Option, + /// the saved value of the field or register + pub value: Option, + /// if true, value is static and should not be updated during suspend, but restored to this value ta resume + pub fixed_value: bool, +} + +#[derive(Debug)] +#[allow(dead_code)] +#[cfg(any(feature="precursor", feature="renode"))] +pub struct RegManager { + pub csr: CSR, + pub registers: [Option; N], +} +#[allow(dead_code)] +#[cfg(any(feature="precursor", feature="renode"))] +impl RegManager:: where ManagedReg: core::marker::Copy { + pub fn new(reg_base: *mut u32) -> RegManager:: { + RegManager:: { + csr: CSR::new(reg_base), + registers: [None; N], + } + } + pub fn push_fixed_value(&mut self, mr: RegOrField, value: usize) { + let mrt = ManagedReg { + item: mr, + mask: None, + value: Some(value), + fixed_value: true, + }; + for entry in self.registers.iter_mut() { + if entry.is_none() { + *entry = Some(mrt); + return; + } + } + panic!("Ran out of space pushing to suspend/resume manager structure. Please increase the allocated size!"); + } + // push registers into the manager in the order that you would normally initialized them + pub fn push(&mut self, mr: RegOrField, mask_override: Option) { + let mrt = ManagedReg { + item: mr, + mask: mask_override, + value: None, + fixed_value: false, + }; + for entry in self.registers.iter_mut() { + if entry.is_none() { + *entry = Some(mrt); + return; + } + } + // A panic! is most appropriate here, because there is really no graceful + // remedy to this. It is a straight-up programmer error that needs to be fixed. + panic!("Ran out of space pushing to suspend/resume manager structure. Please increase the allocated size!"); + } +} +#[cfg(any(feature="precursor", feature="renode"))] +pub trait SuspendResume { + fn suspend(&mut self); + fn resume(&mut self); +} +#[cfg(any(feature="precursor", feature="renode"))] +impl SuspendResume for RegManager { + fn suspend(&mut self) { + for entry in self.registers.iter_mut().rev() { + if let Some(reg) = entry { + if !reg.fixed_value { + // masking is done on the write side + match reg.item { + RegOrField::Field(field) => reg.value = Some(self.csr.rf(field) as usize), + RegOrField::Reg(r) => reg.value = Some(self.csr.r(r) as usize), + } + *entry = Some(*reg); + } + } + } + /* + log::trace!("suspend csr: {:?}", self.csr); + for entry in self.registers.iter().rev() { + log::trace!("suspend: {:?}", entry); + }*/ + } + fn resume(&mut self) { + for entry in self.registers.iter() { // this is in reverse order to the suspend + if let Some(reg) = entry { + if let Some(mut value) = reg.value { + if let Some(mask) = reg.mask { + value &= mask; + } + match reg.item { + RegOrField::Field(field) => self.csr.rmwf(field, value as u32), + RegOrField::Reg(r) => self.csr.wo(r, value as u32), + } + } + } + } + /* + log::trace!("resume csr: {:?}", self.csr); + for entry in self.registers.iter() { + log::trace!("resume: {:?}", entry); + }*/ + } +} + +// because the volatile memory regions can be potentially large (128kiB), but fewer (maybe 5-6 total in the system), +// we allocate these as stand-alone structures and manage them explicitly. +#[derive(Debug)] +#[cfg(any(feature="precursor", feature="renode"))] +pub struct ManagedMem { + pub mem: xous::MemoryRange, + pub backing: [u32; N], +} +#[allow(dead_code)] +#[cfg(any(feature="precursor", feature="renode"))] +impl ManagedMem { + pub fn new(src: xous::MemoryRange) -> Self { + ManagedMem { + mem: src, + backing: [0; N], + } + } +} +#[cfg(any(feature="precursor", feature="renode"))] +impl SuspendResume for ManagedMem { + fn suspend(&mut self) { + let src = self.mem.as_ptr() as *const u32; + for words in 0..(N / core::mem::size_of::()) { + self.backing[words] = unsafe{src.add(words).read_volatile()}; + } + } + fn resume(&mut self) { + let dst = self.mem.as_ptr() as *mut u32; + for words in 0..(N / core::mem::size_of::()) { + unsafe{dst.add(words).write_volatile(self.backing[words])}; + } + } +} diff --git a/api/susres/src/lib.rs b/api/susres/src/lib.rs new file mode 100644 index 000000000..5a2f821ff --- /dev/null +++ b/api/susres/src/lib.rs @@ -0,0 +1,220 @@ +#![cfg_attr(target_os = "none", no_std)] +#![cfg_attr(not(target_os = "none"), allow(dead_code))] +#![cfg_attr(not(target_os = "none"), allow(unused_imports))] +#![cfg_attr(not(target_os = "none"), allow(unused_variables))] + +pub mod api; +pub use api::*; + +use xous::{send_message, CID, Message, msg_scalar_unpack}; +use xous_ipc::Buffer; +use num_traits::{ToPrimitive, FromPrimitive}; + +#[derive(Debug)] +pub struct Susres { + conn: CID, + suspend_cb_sid: Option, +} +impl Susres { + #[cfg(any(feature="precursor", feature="renode"))] + /// When created, the `susres` object can be configured with a `SuspendOrder` to enforce + /// sequencing rules in shutdown. It also requires arguments to define a callback which is + /// pinged when a suspend event arrives. The callback takes the form of a `CID, discriminant` + /// pair, where the CID is the local connection ID to the caller (in other words, a self-connection + /// to the caller), and the discriminant is the number placed into the Xous message's `body.id()` + /// field. This is typically just the descriminant of the main loop's opcode enum for the + /// suspend-resume opcode. + pub fn new(order: Option, xns: &xous_names::XousNames, cb_discriminant: u32, cid: CID) -> Result { + REFCOUNT.fetch_add(1, Ordering::Relaxed); + let conn = xns.request_connection_blocking(api::SERVER_NAME_SUSRES).expect("Can't connect to SUSRES"); + + let sid = xous::create_server().unwrap(); + let sid_tuple = sid.to_u32(); + xous::create_thread_4(suspend_cb_server, sid_tuple.0 as usize, sid_tuple.1 as usize, sid_tuple.2 as usize, sid_tuple.3 as usize).unwrap(); + let hookdata = ScalarHook { + sid: sid_tuple, + id: cb_discriminant, + cid, + order: order.unwrap_or(SuspendOrder::Normal), + }; + log::debug!("hooking {:?}", hookdata); + let buf = Buffer::into_buf(hookdata).or(Err(xous::Error::InternalError))?; + buf.lend(conn, Opcode::SuspendEventSubscribe.to_u32().unwrap())?; + + Ok(Susres { + conn, + suspend_cb_sid: Some(sid), + }) + } + // suspend/resume is not implemented in hosted mode, and will break if you try to do it. + // the main reason this was done is actually it seems hosted mode can't handle the level + // of concurrency introduced by suspend/resume, as its underlying IPC mechanisms are quite + // different and have a lot of overhead; it seems like the system goes into a form of deadlock + // during boot when all the hosted mode servers try to connect. This isn't an issue on real hardware. + #[cfg(any(feature="hosted", + not(any(feature="precursor", feature="renode", feature="hosted")) + ))] + pub fn new(_ordering: Option, xns: &xous_names::XousNames, cb_discriminant: u32, cid: CID) -> Result { + REFCOUNT.fetch_add(1, Ordering::Relaxed); + Ok(Susres { + conn: 0, + suspend_cb_sid: None, + }) + } + /// Creates a connection to the `susres` server, but without a callback. This is useful + /// for services that are suspend-insensitive, but need to manipulate the state of + /// the machine (such as initiating a suspend). + pub fn new_without_hook(xns: &xous_names::XousNames) -> Result { + REFCOUNT.fetch_add(1, Ordering::Relaxed); + let conn = xns.request_connection_blocking(api::SERVER_NAME_SUSRES)?; + Ok(Susres { + conn, + suspend_cb_sid: None, + }) + } + /// This call initiates a suspend. It will sequence through the suspend events; and + /// if any services are unable to suspend within a defined time-out window, the call + /// will fail with a `xous::Error::Timeout`. + /// + /// NB: services such as the SHA engine and + /// the Curve25519 engine can deny a suspend because they have large internal state + /// that can't be saved to battery-backed RAM. + pub fn initiate_suspend(&self) -> Result<(), xous::Error> { + log::trace!("suspend initiated"); + match send_message(self.conn, + Message::new_blocking_scalar(Opcode::SuspendRequest.to_usize().unwrap(), 0, 0, 0, 0) + ) { + Ok(xous::Result::Scalar1(result)) => { + if result == 1 { + Ok(()) + } else { + // indicate that we couldn't initiate the suspend + Err(xous::Error::Timeout) + } + }, + _ => Err(xous::Error::InternalError) + } + } + + /// This call is used by services that are suspend-sensitive. They are used to + /// acknowledge the callback from the suspend sequencer; calling this function + /// basically tells the sequencer "I'm ready to suspend immediately". Likewise, + /// this call blocks until the system resumes. + /// + /// Note that from the perspective of the caller, this call magically appears + /// like it returns almost immediately, because, the time spent in suspend does + /// not increment the ticktimer or system time. The only evidence of a suspend + /// would be a difference in the current RTC timestamp. + pub fn suspend_until_resume(&mut self, token: usize) -> Result { + if self.suspend_cb_sid.is_none() { // this happens if you created without a hook + return Err(xous::Error::UseBeforeInit) + } + log::debug!("token {} pid {} suspending", token, xous::process::id()); // <-- use this to debug s/r + xous::yield_slice(); + // first tell the susres server that we're ready to suspend + send_message(self.conn, + Message::new_scalar(Opcode::SuspendReady.to_usize().unwrap(), token, 0, 0, 0) + ).map(|_|())?; + log::trace!("blocking until suspend"); + + // sometime between here and when this next message unblocks, the power went out... + + // now block until we've resumed + send_message(self.conn, + Message::new_blocking_scalar(Opcode::SuspendingNow.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|())?; + + let response = send_message(self.conn, + Message::new_blocking_scalar(Opcode::WasSuspendClean.to_usize().unwrap(), token, 0, 0, 0) + ).expect("couldn't query if my suspend was successful"); + if let xous::Result::Scalar1(result) = response { + if result != 0 { + log::debug!("resume pid {} clean", xous::process::id()); // <-- use this to debug s/r + Ok(true) + } else { + log::debug!("resume pid {} dirty", xous::process::id()); // <-- use this to debug s/r + Ok(false) + } + } else { + Err(xous::Error::InternalError) + } + } + + /// This is a call that a service can make to inform the suspend sequencer that + /// it is currently suspendable (or not suspendable). This is typically used to + /// book-end calls to hardware that contains large amount of state that cannot + /// be efficiently saved to battery-backed RAM. + pub fn set_suspendable(&mut self, allow_suspend: bool) -> Result<(), xous::Error> { + if allow_suspend { + send_message(self.conn, + Message::new_scalar(Opcode::SuspendAllow.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|()) + } else { + send_message(self.conn, + Message::new_scalar(Opcode::SuspendDeny.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|()) + } + } + + /// Passing `true` causes the whole SOC including peripherals to receive a reset signal + /// `false` causes only the CPU to reboot, while the peripherals retain state. Generally you want `true`. + pub fn reboot(&self, whole_soc: bool) -> Result<(), xous::Error> { + send_message(self.conn, + Message::new_scalar(Opcode::RebootRequest.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|())?; + + if whole_soc { + send_message(self.conn, + Message::new_scalar(Opcode::RebootSocConfirm.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|()) + } else { + send_message(self.conn, + Message::new_scalar(Opcode::RebootCpuConfirm.to_usize().unwrap(), 0, 0, 0, 0) + ).map(|_|()) + } + } +} +fn drop_conn(sid: xous::SID) { + let cid = xous::connect(sid).unwrap(); + xous::send_message(cid, + Message::new_scalar(SuspendEventCallback::Drop.to_usize().unwrap(), 0, 0, 0, 0)).unwrap(); + unsafe{xous::disconnect(cid).unwrap();} +} +use core::sync::atomic::{AtomicU32, Ordering}; +static REFCOUNT: AtomicU32 = AtomicU32::new(0); +impl Drop for Susres { + fn drop(&mut self) { + if let Some(sid) = self.suspend_cb_sid.take() { + drop_conn(sid); + } + if REFCOUNT.fetch_sub(1, Ordering::Relaxed) == 1 { + unsafe{xous::disconnect(self.conn).unwrap();} + } + } +} + +fn suspend_cb_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); + let mut print_once = false; + loop { + let msg = xous::receive_message(sid).unwrap(); + match FromPrimitive::from_usize(msg.body.id()) { + Some(SuspendEventCallback::Event) => msg_scalar_unpack!(msg, cid, id, token, _, { + // directly pass the scalar message onto the CID with the ID memorized in the original hook + if !print_once { + // dump this only once so we have a PID->token map in the debug logs, but don't dump it every time as it slows down the suspend + log::info!("PID {} has s/r token {}", xous::current_pid().unwrap().get(), token); // <-- use this to debug s/r + print_once = true; + } + send_message(cid as u32, + Message::new_scalar(id, token, 0, 0, 0) + ).unwrap(); + }), + Some(SuspendEventCallback::Drop) => { + break; // this exits the loop and kills the thread + } + None => (), + } + } + xous::destroy_server(sid).unwrap(); +} \ No newline at end of file