From 6439ea44d388929a5e8dadfa8401d5e150db2416 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 14 Jan 2024 18:51:30 +0800 Subject: [PATCH] format xous-api-susres --- api/xous-api-susres/src/api.rs | 94 +++++++++++----------- api/xous-api-susres/src/lib.rs | 143 +++++++++++++++++++-------------- 2 files changed, 128 insertions(+), 109 deletions(-) diff --git a/api/xous-api-susres/src/api.rs b/api/xous-api-susres/src/api.rs index b53d1686d..35daeed78 100644 --- a/api/xous-api-susres/src/api.rs +++ b/api/xous-api-susres/src/api.rs @@ -1,9 +1,9 @@ #![cfg_attr(not(target_os = "none"), allow(dead_code))] -#[cfg(any(feature="precursor", feature="renode"))] +#[cfg(any(feature = "precursor", feature = "renode"))] use utralib::generated::*; -pub const SERVER_NAME_SUSRES: &str = "_Suspend/resume manager_"; +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 @@ -60,7 +60,8 @@ pub enum Opcode { /// not tested - reboot address RebootVector, //(u32), - /// used by processes to indicate they are suspending now; this blocks until resume using the "execution gate" + /// used by processes to indicate they are suspending now; this blocks until resume using the "execution + /// gate" SuspendingNow, /// used to power off the system without suspend @@ -73,8 +74,10 @@ pub enum Opcode { #[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 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, } @@ -84,70 +87,65 @@ pub enum SuspendEventCallback { Drop, } - ///////////////////////////////////////////////////////////////////////// /////////////////////////// suspend-resume hardware management primitives ///////////////////////////////////////////////////////////////////////// -#[cfg(any(feature="precursor", feature="renode"))] +#[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"))] +#[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) + /// 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 + /// 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"))] +#[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], - } +#[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, - }; + 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!"); + 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, - }; + 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); @@ -156,15 +154,17 @@ impl RegManager:: where ManagedReg: core::marker::Copy { } // 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!"); + panic!( + "Ran out of space pushing to suspend/resume manager structure. Please increase the allocated size!" + ); } } -#[cfg(any(feature="precursor", feature="renode"))] +#[cfg(any(feature = "precursor", feature = "renode"))] pub trait SuspendResume { fn suspend(&mut self); fn resume(&mut self); } -#[cfg(any(feature="precursor", feature="renode"))] +#[cfg(any(feature = "precursor", feature = "renode"))] impl SuspendResume for RegManager { fn suspend(&mut self) { for entry in self.registers.iter_mut().rev() { @@ -185,8 +185,10 @@ impl SuspendResume for RegManager { log::trace!("suspend: {:?}", entry); }*/ } + fn resume(&mut self) { - for entry in self.registers.iter() { // this is in reverse order to the suspend + 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 { @@ -207,36 +209,32 @@ impl SuspendResume for RegManager { } } -// 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. +// 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"))] +#[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"))] +#[cfg(any(feature = "precursor", feature = "renode"))] impl ManagedMem { - pub fn new(src: xous::MemoryRange) -> Self { - ManagedMem { - mem: src, - backing: [0; N], - } - } + pub fn new(src: xous::MemoryRange) -> Self { ManagedMem { mem: src, backing: [0; N] } } } -#[cfg(any(feature="precursor", feature="renode"))] +#[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()}; + 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])}; + unsafe { dst.add(words).write_volatile(self.backing[words]) }; } } } diff --git a/api/xous-api-susres/src/lib.rs b/api/xous-api-susres/src/lib.rs index 9e01d2f90..98dacf808 100644 --- a/api/xous-api-susres/src/lib.rs +++ b/api/xous-api-susres/src/lib.rs @@ -5,10 +5,9 @@ pub mod api; pub use api::*; - -use xous::{send_message, CID, Message, msg_scalar_unpack}; +use num_traits::{FromPrimitive, ToPrimitive}; +use xous::{msg_scalar_unpack, send_message, Message, CID}; use xous_ipc::Buffer; -use num_traits::{ToPrimitive, FromPrimitive}; #[derive(Debug)] pub struct Susres { @@ -16,7 +15,7 @@ pub struct Susres { suspend_cb_sid: Option, } impl Susres { - #[cfg(any(feature="precursor", feature="renode"))] + #[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` @@ -24,13 +23,25 @@ impl Susres { /// 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 { + 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(); + 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, @@ -41,11 +52,9 @@ impl Susres { 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), - }) + 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 @@ -59,24 +68,25 @@ impl Susres { /// 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(_ordering: Option, xns: &xous_names::XousNames, cb_discriminant: u32, cid: CID) -> Result { + 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, - }) + 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, - }) + 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`. @@ -86,8 +96,9 @@ impl Susres { /// 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) + 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 { @@ -96,8 +107,8 @@ impl Susres { // indicate that we couldn't initiate the suspend Err(xous::Error::Timeout) } - }, - _ => Err(xous::Error::InternalError) + } + _ => Err(xous::Error::InternalError), } } @@ -111,27 +122,34 @@ impl Susres { /// 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) + 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(|_|())?; + 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(|_|())?; + 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"); + 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 @@ -151,46 +169,48 @@ impl Susres { /// 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(|_|()) + 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(|_|()) + 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(|_|())?; + 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(|_|()) + 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(|_|()) + send_message( + self.conn, + Message::new_scalar(Opcode::RebootCpuConfirm.to_usize().unwrap(), 0, 0, 0, 0), + ) + .map(|_| ()) } } /// Pulls power from the SoC without attempting to save state pub fn immediate_poweroff(&self) -> Result<(), xous::Error> { - send_message(self.conn, - Message::new_scalar(Opcode::PowerOff.to_usize().unwrap(), 0, 0, 0, 0) - ).map(|_|()) + send_message(self.conn, Message::new_scalar(Opcode::PowerOff.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();} + 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); @@ -200,7 +220,9 @@ impl Drop for Susres { drop_conn(sid); } if REFCOUNT.fetch_sub(1, Ordering::Relaxed) == 1 { - unsafe{xous::disconnect(self.conn).unwrap();} + unsafe { + xous::disconnect(self.conn).unwrap(); + } } } } @@ -214,13 +236,12 @@ fn suspend_cb_server(sid0: usize, sid1: usize, sid2: usize, sid3: usize) { 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 + // 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(); + 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 @@ -229,4 +250,4 @@ fn suspend_cb_server(sid0: usize, sid1: usize, sid2: usize, sid3: usize) { } } xous::destroy_server(sid).unwrap(); -} \ No newline at end of file +}