mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-15 08:30:02 +00:00
split out ticktimer API
This commit is contained in:
parent
0aaf64781f
commit
efc0c30171
4 changed files with 314 additions and 0 deletions
27
api/ticktimer/Cargo.toml
Normal file
27
api/ticktimer/Cargo.toml
Normal 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
21
api/ticktimer/README.md
Normal 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
56
api/ticktimer/src/api.rs
Normal 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
210
api/ticktimer/src/lib.rs
Normal 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();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue