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` # `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: Settings currently stored here:
- keymap - keymap

View file

@ -6,9 +6,16 @@ pub const SERVER_NAME_ES: &str = "_EARLY_SETTINGS";
#[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)] #[derive(Debug, num_derive::FromPrimitive, num_derive::ToPrimitive)]
pub enum Opcode { pub enum Opcode {
/// Sets the keymap in early settings.
SetKeymap, SetKeymap,
/// Retrieves keymap from early settings.
GetKeymap, GetKeymap,
/// Retrieves the status of the early sleep flag.
EarlySleep, EarlySleep,
/// Sets early sleep flag in early settings.
SetEarlySleep, SetEarlySleep,
} }
@ -26,6 +33,8 @@ impl EarlySettings {
Ok(EarlySettings { conn }) 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> { pub fn set_keymap(&self, map: usize) -> Result<(), xous::Error> {
send_message( send_message(
self.conn, self.conn,
@ -40,6 +49,8 @@ impl EarlySettings {
.map(|_| ()) .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> { pub fn get_keymap(&self) -> Result<usize, xous::Error> {
match send_message( match send_message(
self.conn, 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> { pub fn set_early_sleep(&self, value: bool) -> Result<(), xous::Error> {
send_message( send_message(
self.conn, self.conn,
@ -64,6 +76,7 @@ impl EarlySettings {
.map(|_| ()) .map(|_| ())
} }
/// early_sleep retrieves the early sleep flag from the early settings FLASH section.
pub fn early_sleep(&self) -> Result<bool, xous::Error> { pub fn early_sleep(&self) -> Result<bool, xous::Error> {
match send_message( match send_message(
self.conn, self.conn,
@ -73,7 +86,7 @@ impl EarlySettings {
0 => Ok(false), 0 => Ok(false),
1 => Ok(true), 1 => Ok(true),
_ => Ok(false), // instead of doing `value != 0` we're explicitly matching against specific values, because _ => 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), _ => Err(xous::Error::InternalError),
} }

View file

@ -1,8 +1,36 @@
use std::ops::Range;
use early_settings::{Opcode, SERVER_NAME_ES}; use early_settings::{Opcode, SERVER_NAME_ES};
use num_traits::FromPrimitive; use num_traits::FromPrimitive;
use spinor::Spinor; use spinor::Spinor;
use xous::{msg_blocking_scalar_unpack, MemoryRange}; 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 { struct State {
settings_page: MemoryRange, settings_page: MemoryRange,
spinor: Spinor, spinor: Spinor,
@ -31,13 +59,13 @@ fn main() -> ! {
.expect("can't register server"); .expect("can't register server");
loop { 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); log::trace!("Message: {:?}", msg);
match FromPrimitive::from_usize(msg.body.id()) { match FromPrimitive::from_usize(msg.body.id()) {
Some(Opcode::GetKeymap) => { Some(Opcode::GetKeymap) => {
let settings: &[u8] = state.settings_page.as_slice(); 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(); xous::return_scalar(msg.sender, code as usize).unwrap();
} }
@ -47,7 +75,7 @@ fn main() -> ! {
state state
.spinor .spinor
.patch(settings, xous::EARLY_SETTINGS, &code, 0) .patch(settings, xous::EARLY_SETTINGS, &code, KEYMAP.offset)
.expect("couldn't patch our keyboard code"); .expect("couldn't patch our keyboard code");
log::info!("writing early keymap: {}", map); log::info!("writing early keymap: {}", map);
@ -60,7 +88,7 @@ fn main() -> ! {
state state
.spinor .spinor
.patch(settings, xous::EARLY_SETTINGS, &code, 4) .patch(settings, xous::EARLY_SETTINGS, &code, EARLY_SLEEP.offset)
.expect("couldn't patch early reboot flag"); .expect("couldn't patch early reboot flag");
log::info!("writing must sleep on reboot: {}", value); log::info!("writing must sleep on reboot: {}", value);
@ -70,7 +98,7 @@ fn main() -> ! {
Some(Opcode::EarlySleep) => { Some(Opcode::EarlySleep) => {
let settings: &[u8] = state.settings_page.as_slice(); 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); log::info!("value read for early sleep: {}", value);