add susres to the external APIs

This commit is contained in:
bunnie 2022-10-03 01:54:31 +08:00
parent 679ad9b75f
commit 6a14b6d54f
4 changed files with 503 additions and 0 deletions

27
api/susres/Cargo.toml Normal file
View file

@ -0,0 +1,27 @@
[package]
name = "xous-api-susres"
version = "0.9.0"
authors = ["bunnie <bunnie@kosagi.com>"]
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 = []

17
api/susres/README.md Normal file
View file

@ -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.

239
api/susres/src/api.rs Normal file
View file

@ -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<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
pub fixed_value: bool,
}
#[derive(Debug)]
#[allow(dead_code)]
#[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],
}
}
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<usize>) {
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<const N: usize> SuspendResume for RegManager<N> {
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<const N: usize> {
pub mem: xous::MemoryRange,
pub backing: [u32; N],
}
#[allow(dead_code)]
#[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],
}
}
}
#[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()};
}
}
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])};
}
}
}

220
api/susres/src/lib.rs Normal file
View file

@ -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<xous::SID>,
}
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<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();
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<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,
})
}
/// 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,
})
}
/// 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<bool, xous::Error> {
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();
}