split out ticktimer API

This commit is contained in:
bunnie 2022-10-03 03:02:38 +08:00
parent 0aaf64781f
commit efc0c30171
4 changed files with 314 additions and 0 deletions

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

@ -0,0 +1,27 @@
[package]
authors = ["bunnie <bunnie@kosagi.com>", "Sean Cross <sean@xobs.io>"]
description = "Provide high-resolution, non-rollover system time"
edition = "2018"
name = "xous-api-ticktimer"
version = "0.1.0"
license = "MIT OR Apache-2.0"
repository = "https://github.com/betrusted-io/xous-core/"
homepage = "https://betrusted.io/xous-book/"
# Dependency versions enforced by Cargo.lock.
[dependencies]
log = "0.4.14"
log-server = {version = "0.1.3", package = "xous-api-log"}
xous = "0.9.9"
xous-ipc = "0.9.9"
rkyv = {version = "0.4.3", default-features = false, features = ["const_generics"]}
num-derive = {version = "0.3.3", default-features = false}
num-traits = {version = "0.2.14", default-features = false}
susres = {version = "0.9.0", package = "xous-api-susres"}
xous-names = {version = "0.9.3", package = "xous-api-names"}
xous-semver = "0.1.2"
[features]
debug-print = []
no-timestamp = [] # turns off embedded timestamp for reproducible builds
default = []

21
api/ticktimer/README.md Normal file
View file

@ -0,0 +1,21 @@
# Xous API: ticktimer
The Xous `ticktimer` helps other processes track the passage of time through several mechanisms:
- It can report the elapsed uptime since boot in milliseconds.
- It can block a process for a specified number of milliseconds.
- It can block a process until a condition is met (i.e., condvar)
Processes that are blocked by `ticktimer` are entirely de-scheduled and consume no CPU
quantum; the only overhead is a few instructions to check the processes' runnability
state in the kernel's simple round-robin thread scheduler. Thus `sleep` and `condvar`
blocking states are very efficient.
`ticktimer`'s perception of time stops when a system goes into the suspend state;
thus on resume, the elapsed time picks up exactly where it left off. Wall-clock time
during suspend is tracked by the RTC module.
Xous currently has no notions of thread priority, but if it were to develop one,
the `ticktimer` would be the logical place to implement such a feature, as it has
a full view of all the waiting and runnable threads, and it can influence which ones
should be unblocked at a given quantum.

56
api/ticktimer/src/api.rs Normal file
View file

@ -0,0 +1,56 @@
/// Do not modify the discriminants in this structure. They are used in `libstd` directly.
#[derive(num_derive::FromPrimitive, num_derive::ToPrimitive, Debug)]
pub enum Opcode {
/// Get the elapsed time in milliseconds
ElapsedMs = 0,
/// Sleep for the specified numer of milliseconds
SleepMs = 1,
/// Recalculate the sleep time
RecalculateSleep = 2,
/// Suspend/resume callback
SuspendResume = 3,
/// force a WDT update
PingWdt = 4,
/// Return the version string of Xous. We bury it here because this is a small, lightweight server we can rebuild on every run.
GetVersion = 5,
/// Lock the given Mutex, blocking if it is already locked.
///
/// # Arguments
///
/// *arg1*: An integer of some sort, such as the address of the Mutex
LockMutex = 6,
/// Unlock the given Mutex
///
/// # Arguments
///
/// *arg1*: An integer of some sort, such as the address of the Mutex
UnlockMutex = 7,
/// Wait for a given condition to be signalled
///
/// # Arguments
///
/// *arg1*: An integer of some sort, such as the address of the Condvar
/// *arg2*: The number of milliseconds to wait, or 0 to wait forever
WaitForCondition = 8,
/// Notify a condition
///
/// # Arguments
///
/// *arg1*: An integer of some sort, such as the address of the Condvar
/// *arg2*: The number of conditions to notify
NotifyCondition = 9,
}
#[derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]
pub struct VersionString {
pub version: xous_ipc::String::<512>,
}

210
api/ticktimer/src/lib.rs Normal file
View file

@ -0,0 +1,210 @@
#![cfg_attr(target_os = "none", no_std)]
pub mod api;
use num_traits::ToPrimitive;
use xous::{send_message, Error, CID};
use xous_semver::SemVer;
#[derive(Debug)]
pub struct Ticktimer {
conn: CID,
}
impl Ticktimer {
pub fn new() -> Result<Self, Error> {
REFCOUNT.fetch_add(1, Ordering::Relaxed);
let conn = xous::connect(xous::SID::from_bytes(b"ticktimer-server").unwrap())?;
Ok(Ticktimer { conn })
}
/// Return the number of milliseconds that have elapsed since boot. The returned
/// value is guaranteed to always be the same or greater than the previous value,
/// even through suspend/resume cycles. During suspend, the counter does not
/// advance, so loops which rely on this value will not perceive any extra time
/// passing through a suspend/resume cycle.
///
/// This call is expected to be infalliable, and removing the error handling
/// path makes it a little more efficient in a tight loop.
///
/// # Returns:
///
/// * A `u64` that is the number of milliseconds elapsed since boot.
pub fn elapsed_ms(&self) -> u64 {
let response = send_message(
self.conn,
xous::Message::new_blocking_scalar(
api::Opcode::ElapsedMs.to_usize().unwrap(),
0,
0,
0,
0,
),
)
.expect("Ticktimer: failure to send message to Ticktimer");
if let xous::Result::Scalar2(upper, lower) = response {
upper as u64 | ((lower as u64) << 32)
} else {
panic!(
"Ticktimer elapsed_ms(): unexpected return value."
);
}
}
/// Sleep for at least `ms` milliseconds. Blocks until the requested time has passed.
///
/// # Arguments:
///
/// * ms: A `usize` specifying how many milliseconds to sleep for
pub fn sleep_ms(&self, ms: usize) -> Result<(), Error> {
send_message(
self.conn,
xous::Message::new_blocking_scalar(
api::Opcode::SleepMs.to_usize().unwrap(),
ms,
0,
0,
0,
),
)
.map(|_| ())
}
/// Ping the watchdog timer. Processes may use this to periodically ping the WDT to prevent
/// the system from resetting itself. Note that every call to `sleep_ms()` also implicitly
/// pings the WDT, so in more complicated systems an explicit call is not needed.
pub fn ping_wdt(&self) {
send_message(
self.conn,
xous::Message::new_scalar(api::Opcode::PingWdt.to_usize().unwrap(), 0, 0, 0, 0),
)
.expect("Couldn't send WDT ping");
}
/// Query version information embedded in this implementation crate by the build system.
///
/// # Returns:
///
/// * A `String` containing the version information of the latest build
pub fn get_version(&self) -> String {
let alloc = api::VersionString {
version: xous_ipc::String::new(),
};
let mut buf = xous_ipc::Buffer::into_buf(alloc).expect("couldn't convert version request");
buf.lend_mut(self.conn, api::Opcode::GetVersion.to_u32().unwrap())
.expect("couldn't get version");
let v = buf
.to_original::<api::VersionString, _>()
.expect("couldn't revert buffer");
String::from(v.version.as_str().unwrap())
}
pub fn get_version_semver(&self) -> SemVer {
SemVer::from_str(self.get_version().lines().next().unwrap()).unwrap()
}
/// Lock the given Mutex. Blocks until the Mutex is locked.
///
/// Note that Mutexes start out in a `Locked` state and move into an `Unlocked` state by calling
/// `Unlock` on their pointer. For example, the following will probably block forever:
///
/// `TickTimer.lock_mutex(1)`
///
/// In order to create a new Mutex, you must first `Unlock` it. For example, the following is
/// allowed:
///
/// `TickTimer.unlock_mutex(1)`
/// `TickTimer.lock_mutex(1)`
/// `TickTimer.unlock_mutex(1)`
///
/// # Arguments:
///
/// * mtx: A `usize` referring to the Mutex. This is probably a pointer, but can be any `usize`
pub fn lock_mutex(&self, mtx: usize) {
send_message(
self.conn,
xous::Message::new_blocking_scalar(
api::Opcode::LockMutex.to_usize().unwrap(),
mtx,
0,
0,
0,
),
)
.expect("couldn't lock mutex");
}
/// Unlock the given Mutex. Does not block. If the Mutex is not locked, then it will be
/// "doubly-unlocked". That is, if you Unlock a mutex twice, then you can Lock it twice
/// without blocking.
///
/// # Arguments:
///
/// * mtx: A `usize` referring to the Mutex. This is probably a pointer, but can be any `usize`
pub fn unlock_mutex(&self, mtx: usize) {
send_message(
self.conn,
xous::Message::new_scalar(api::Opcode::UnlockMutex.to_usize().unwrap(), mtx, 0, 0, 0),
)
.expect("couldn't unlock mutex");
}
/// Wait for a Condition on the given condvar, with an optional Duration
///
/// # Arguments:
///
/// * condvar: A `usize` referring to the Condvar. This is probably a pointer, but can be any `usize`
/// * duration: The amount of time to wait for a signal, if any
///
/// # Returns:
///
/// * true: the condition was successfully received
/// * false: the condition was not received and the operation itmed out
pub fn wait_condition(&self, condvar: usize, duration: Option<core::time::Duration>) -> bool {
send_message(
self.conn,
xous::Message::new_scalar(
api::Opcode::WaitForCondition.to_usize().unwrap(),
condvar,
duration.map(|d| d.as_millis() as usize).unwrap_or(0),
0,
0,
),
)
.map(|r| r == xous::Result::Scalar1(0))
.expect("couldn't wait for condition")
}
/// Notify a condition to one or more Waiters
///
/// # Arguments:
///
/// * condvar: A `usize` referring to the Condvar. This is probably a pointer, but can be any `usize`
/// * count: The number of Waiters to wake up
///
pub fn notify_condition(&self, condvar: usize, count: usize) {
send_message(
self.conn,
xous::Message::new_scalar(
api::Opcode::NotifyCondition.to_usize().unwrap(),
condvar,
count,
0,
0,
),
)
.map(|r| r == xous::Result::Scalar1(0))
.expect("couldn't notify condition");
}
}
use core::sync::atomic::{AtomicU32, Ordering};
static REFCOUNT: AtomicU32 = AtomicU32::new(0);
impl Drop for Ticktimer {
fn drop(&mut self) {
// de-allocate myself. It's unsafe because we are responsible to make sure nobody else is using the connection.
if REFCOUNT.fetch_sub(1, Ordering::Relaxed) == 1 {
unsafe {
xous::disconnect(self.conn).unwrap();
}
}
}
}