document how everything works a little more

This commit is contained in:
Gianguido Sorà 2023-04-24 20:18:57 +02:00
parent f95ae6c042
commit 7062c46032
3 changed files with 51 additions and 8 deletions

View file

@ -1,6 +1,8 @@
# `early_settings`
This crate provides a service and API to access some settings stored in the first 4096 bytes of FLASH.
This crate provides a service and API to access settings stored in the first 4096 bytes of FLASH.
Settings stored there do not contain any personal identifiable information.
Settings currently stored here:
- keymap
@ -12,4 +14,4 @@ This scratch area is provided for extreme edge cases:
- keymap must live here because users need to write their password in order to mount PDDB
- early sleep is used in the "lock device" lifecycle, placing it here is the most convenient thing to do to achieve that use-case
If you're thinking of placing something in here please open an issue or shoot us a Matrix message on `#xous-apps:matrix.org`.
If you're thinking of placing something in here please open an issue or shoot us a Matrix message on `#xous-apps:matrix.org`.

View file

@ -6,9 +6,16 @@ pub const SERVER_NAME_ES: &str = "_EARLY_SETTINGS";
#[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)]
pub enum Opcode {
/// Sets the keymap in early settings.
SetKeymap,
/// Retrieves keymap from early settings.
GetKeymap,
/// Retrieves the status of the early sleep flag.
EarlySleep,
/// Sets early sleep flag in early settings.
SetEarlySleep,
}
@ -26,6 +33,8 @@ impl EarlySettings {
Ok(EarlySettings { conn })
}
/// set_keymap sets map as keymap in the early settings FLASH section.
/// No validation on map is done, use with caution.
pub fn set_keymap(&self, map: usize) -> Result<(), xous::Error> {
send_message(
self.conn,
@ -40,6 +49,8 @@ impl EarlySettings {
.map(|_| ())
}
/// get_keymap gets the keymap from the early settings FLASH section.
/// No validation is done on the return value, use with caution.
pub fn get_keymap(&self) -> Result<usize, xous::Error> {
match send_message(
self.conn,
@ -50,6 +61,7 @@ impl EarlySettings {
}
}
/// set_early_sleep sets value in the early settings FLASH section.
pub fn set_early_sleep(&self, value: bool) -> Result<(), xous::Error> {
send_message(
self.conn,
@ -64,6 +76,7 @@ impl EarlySettings {
.map(|_| ())
}
/// early_sleep retrieves the early sleep flag from the early settings FLASH section.
pub fn early_sleep(&self) -> Result<bool, xous::Error> {
match send_message(
self.conn,
@ -73,7 +86,7 @@ impl EarlySettings {
0 => Ok(false),
1 => Ok(true),
_ => Ok(false), // instead of doing `value != 0` we're explicitly matching against specific values, because
// reading off FLASH can yield a true value otherwise, even if it wasn't set before
// reading off FLASH can yield a true value otherwise, even if it wasn't set before
},
_ => Err(xous::Error::InternalError),
}

View file

@ -1,8 +1,36 @@
use std::ops::Range;
use early_settings::{Opcode, SERVER_NAME_ES};
use num_traits::FromPrimitive;
use spinor::Spinor;
use xous::{msg_blocking_scalar_unpack, MemoryRange};
/*
!!!! EARLY SETTINGS ALLOCATED SLOTS !!!!
If you'll ever need a data slot in the early settings FLASH section,
please document it here for reference and use the Slot struct!
Thanks!
Keymap: offset 0, size 4
Early sleep: offset 4, size 4
*/
const KEYMAP: Slot = Slot { offset: 0, size: 4 };
const EARLY_SLEEP: Slot = Slot { offset: 4, size: 4 };
struct Slot {
offset: u32,
size: u32,
}
impl Slot {
fn range(&self) -> Range<usize> {
(self.offset as usize)..((self.offset + self.size) as usize)
}
}
struct State {
settings_page: MemoryRange,
spinor: Spinor,
@ -31,13 +59,13 @@ fn main() -> ! {
.expect("can't register server");
loop {
let msg = xous::receive_message(sid).unwrap(); // this blocks until we get a message
let msg = xous::receive_message(sid).unwrap();
log::trace!("Message: {:?}", msg);
match FromPrimitive::from_usize(msg.body.id()) {
Some(Opcode::GetKeymap) => {
let settings: &[u8] = state.settings_page.as_slice();
let code = u32::from_le_bytes(settings[..4].try_into().unwrap());
let code = u32::from_le_bytes(settings[KEYMAP.range()].try_into().unwrap());
xous::return_scalar(msg.sender, code as usize).unwrap();
}
@ -47,7 +75,7 @@ fn main() -> ! {
state
.spinor
.patch(settings, xous::EARLY_SETTINGS, &code, 0)
.patch(settings, xous::EARLY_SETTINGS, &code, KEYMAP.offset)
.expect("couldn't patch our keyboard code");
log::info!("writing early keymap: {}", map);
@ -60,7 +88,7 @@ fn main() -> ! {
state
.spinor
.patch(settings, xous::EARLY_SETTINGS, &code, 4)
.patch(settings, xous::EARLY_SETTINGS, &code, EARLY_SLEEP.offset)
.expect("couldn't patch early reboot flag");
log::info!("writing must sleep on reboot: {}", value);
@ -70,7 +98,7 @@ fn main() -> ! {
Some(Opcode::EarlySleep) => {
let settings: &[u8] = state.settings_page.as_slice();
let value = u32::from_le_bytes(settings[4..8].try_into().unwrap());
let value = u32::from_le_bytes(settings[EARLY_SLEEP.range()].try_into().unwrap());
log::info!("value read for early sleep: {}", value);