format xous-api-susres

This commit is contained in:
bunnie 2024-01-14 18:51:30 +08:00
parent 80938fe488
commit 6439ea44d3
2 changed files with 128 additions and 109 deletions

View file

@ -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<usize>,
/// the saved value of the field or register
pub value: Option<usize>,
/// 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<const N: usize> {
pub csr: CSR<u32>,
pub registers: [Option<ManagedReg>; N],
}
#[allow(dead_code)]
#[cfg(any(feature="precursor", feature="renode"))]
impl<const N: usize> RegManager::<N> where ManagedReg: core::marker::Copy {
pub fn new(reg_base: *mut u32) -> RegManager::<N> {
RegManager::<N> {
csr: CSR::new(reg_base),
registers: [None; N],
}
#[cfg(any(feature = "precursor", feature = "renode"))]
impl<const N: usize> RegManager<N>
where
ManagedReg: core::marker::Copy,
{
pub fn new(reg_base: *mut u32) -> RegManager<N> {
RegManager::<N> { 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<usize>) {
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<const N: usize> RegManager::<N> 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<const N: usize> SuspendResume for RegManager<N> {
fn suspend(&mut self) {
for entry in self.registers.iter_mut().rev() {
@ -185,8 +185,10 @@ impl<const N: usize> SuspendResume for RegManager<N> {
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<const N: usize> SuspendResume for RegManager<N> {
}
}
// 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<const N: usize> {
pub mem: xous::MemoryRange,
pub backing: [u32; N],
}
#[allow(dead_code)]
#[cfg(any(feature="precursor", feature="renode"))]
#[cfg(any(feature = "precursor", feature = "renode"))]
impl<const N: usize> ManagedMem<N> {
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<const N: usize> SuspendResume for ManagedMem<N> {
fn suspend(&mut self) {
let src = self.mem.as_ptr() as *const u32;
for words in 0..(N / core::mem::size_of::<u32>()) {
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::<u32>()) {
unsafe{dst.add(words).write_volatile(self.backing[words])};
unsafe { dst.add(words).write_volatile(self.backing[words]) };
}
}
}

View file

@ -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<xous::SID>,
}
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<SuspendOrder>, xns: &xous_names::XousNames, cb_discriminant: u32, cid: CID) -> Result<Self, xous::Error> {
pub fn new(
order: Option<SuspendOrder>,
xns: &xous_names::XousNames,
cb_discriminant: u32,
cid: CID,
) -> Result<Self, xous::Error> {
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<SuspendOrder>, xns: &xous_names::XousNames, cb_discriminant: u32, cid: CID) -> Result<Self, xous::Error> {
pub fn new(
_ordering: Option<SuspendOrder>,
xns: &xous_names::XousNames,
cb_discriminant: u32,
cid: CID,
) -> Result<Self, xous::Error> {
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<Self, xous::Error> {
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<bool, xous::Error> {
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();
}
}