Merge branch 'main' of github.com:betrusted-io/xous-core into main

This commit is contained in:
bunnie 2022-10-20 04:46:41 +08:00
commit 00eb09eb48
9 changed files with 362 additions and 118 deletions

4
.gitignore vendored
View file

@ -37,6 +37,9 @@ tools/__pycache__
# PDDB backup files # PDDB backup files
*.pddb *.pddb
# PDDB for mtxcli (only for testing in hosted mode)
/kernel/mtxcli
# performance monitoring page table # performance monitoring page table
tools/ct_data/v2p.txt tools/ct_data/v2p.txt
@ -72,4 +75,3 @@ share/python-wheels/
.installed.cfg .installed.cfg
*.egg *.egg
MANIFEST MANIFEST

View file

@ -2,70 +2,40 @@
This is a new Matrix chat application which will be derived from REPL. This is a new Matrix chat application which will be derived from REPL.
_NOTE_: constant is in gam/src/lib.rs (APP_NAME_MTXCLI) is generated automatically ![screenshot](mtxcli_screenshot.png)
with `cargo xtask app-image mtxcli` or `cargo xtask run mtxcli`.
# Inherited from REPL ## Background
A simple demo application that provides a bare-bones REPL framework. This is a simple [Matrix chat](https://matrix.org/) application based on the REPL framework.
## Copying This Demo to a New App
1. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. ## Setup
2. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml`
3. Edit the `manifest.json` file as documented in its [README](../README.md)
4. Build using `cargo xtask app-image you_new_app` to create a flashable Xous image with your app in it.
## Details
![screenshot](repl_screenshot.png) In order to simplify the **mtxcli** application as much as possible the following
must be setup on a conventional device before using Betrusted (laptop, mobile phone).
`repl` is a baseline demo application for Xous. It uses a chat-client * Create a new Matrix user:
style interface (stacking bubbles of text, with user input right-aligned * https://matrix.org/faq/#how-do-i-get-an-account-and-get-started%3F
and shell feedback left-aligned) to facilitate interactions. * Find (or create) a new room to join for chatting:
* https://doc.matrix.tu-dresden.de/en/rooms/create/
* https://spec.matrix.org/latest/#room-structure
* Join the room
* Save the configuration in the pddb
* `/set user @myname:matrix.org`
* `/set password AbigSecret`
* `/set room #my-chat-room`
It implements the basic envisioned structure of a Xous application, namely: ## Commands
- Text input comes via the `ime-frontend` The following commands are available in **mtxcli**:
- Graphical output is rendered via the `gam` * `/help [cmd]` -- shows help message for all commands (or one cmd if given)
* `/get key` -- shows value of key (from the PDDB)
* `/set key value` -- sets value of key (in the PDDB)
* `/unset key` -- removes key (from the PDDB)
* `/status` -- shows status of the connection
[Push Events and Listeners](https://github.com/betrusted-io/xous-core/wiki/Push-Events-and-Listeners) provides an overview of the flow of ## Chatting
messages between an Xous application and the Xous Services.
The one demo command provisioned in the `repl` app plays a tone via Any line not starting with a slash ('/') will be sent to the current room.
the `codec` service. This was chosen because it is about one of the most complicated New messages from the current room will be displayed.
and comprehensive things you can do in the `repl` environment, as it requires
real-time callbacks to fill the audio buffer with new samples. If you have
specific questions about how the callbacks work, we encourage you to open
an issue in this repo and ask your question. Your questions will help us
direct effort toward building the documentation base.
To make your own command, copy the `audio.rs` template _NOTE:_ chatting is not implemented yet
in the `apps/repl/src/cmds/` directory, or use this very basic `echo`
template:
```Rust
use crate::{ShellCmdApi, CommonEnv};
use xous_ipc::String;
#[derive(Debug)]
pub struct Echo {
}
impl<'a> ShellCmdApi<'a> for Echo {
cmd_api!(echo); // inserts boilerplate for command API
fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result<Option<String::<1024>>, xous::Error> {
Ok(Some(rest))
}
}
```
The "verb" is the name of your command, and it is the argument to the `cmd_api!()` macro.
`process()` is your "main" function, and `args` is a string which contains the
rest of the line that was typed into the chat, minus the verb used to identify
your command (e.g. the arguments, but not tokenized or parsed in
any way). `env` contains some items in a common environment, for example, connections
to the GAM, LLIO server or other resources required by your implementation.
Once you've added your command to the directory, go to the `cmds.rs` file, and follow
the four-step instructions embedded within the file, starting around line 40.

View file

@ -5,10 +5,16 @@
"zh": "简单的 mtxcli 演示活动", "zh": "简单的 mtxcli 演示活动",
"en-tts": "Welcome to the simple MTXCLI demo." "en-tts": "Welcome to the simple MTXCLI demo."
}, },
"mtxcli.get.help": {
"en": "/get key",
"ja": "TBD /get key",
"zh": "TBD /get key",
"en-tts": "get key"
},
"mtxcli.help.help": { "mtxcli.help.help": {
"en": "help [cmd]", "en": "/help [cmd]",
"ja": "TBD help [cmd]", "ja": "TBD /help [cmd]",
"zh": "TBD help [cmd]", "zh": "TBD /help [cmd]",
"en-tts": "help [cmd]" "en-tts": "help [cmd]"
}, },
"mtxcli.help.overview": { "mtxcli.help.overview": {
@ -17,6 +23,24 @@
"zh": "TBD available mtxcli commands:", "zh": "TBD available mtxcli commands:",
"en-tts": "available mtxcli commands:" "en-tts": "available mtxcli commands:"
}, },
"mtxcli.set.help": {
"en": "/set key value",
"ja": "TBD /set key value",
"zh": "TBD /set key value",
"en-tts": "set key value"
},
"mtxcli.status.help": {
"en": "/status",
"ja": "TBD /status",
"zh": "TBD /status",
"en-tts": "status"
},
"mtxcli.unset.help": {
"en": "/unset key",
"ja": "TBD /unset key",
"zh": "TBD /unset key",
"en-tts": "unset key"
},
"mtxcli.unknown.help": { "mtxcli.unknown.help": {
"en": "unknown command", "en": "unknown command",
"ja": "TBD unknown command", "ja": "TBD unknown command",

View file

@ -1,15 +1,22 @@
use xous::{MessageEnvelope}; use xous::{MessageEnvelope};
use xous_ipc::String; use xous_ipc::String as XousString;
use core::fmt::Write; use core::fmt::Write;
use std::collections::HashMap; use std::collections::HashMap;
use std::fs::File;
use std::io::{Read, Write as StdWrite, Error};
use std::path::PathBuf;
/// PDDB Dict for mtxcli keys
const MTXCLI_DICT: &str = "mtxcli";
/////////////////////////// Common items to all commands /////////////////////////// Common items to all commands
pub trait ShellCmdApi<'a> { pub trait ShellCmdApi<'a> {
// user implemented: // user implemented:
// called to process the command with the remainder of the string attached // called to process the command with the remainder of the string attached
fn process(&mut self, args: String::<1024>, env: &mut CommonEnv) -> Result<Option<String::<1024>>, xous::Error>; fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error>;
// called to process incoming messages that may have been origniated by the most recently issued command // called to process incoming messages that may have been origniated by the most recently issued command
fn callback(&mut self, msg: &MessageEnvelope, _env: &mut CommonEnv) -> Result<Option<String::<1024>>, xous::Error> { fn callback(&mut self, msg: &MessageEnvelope, _env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
log::info!("received unhandled message {:?}", msg); log::info!("received unhandled message {:?}", msg);
Ok(None) Ok(None)
} }
@ -46,25 +53,49 @@ pub struct CommonEnv {
codec: codec::Codec, codec: codec::Codec,
ticktimer: ticktimer_server::Ticktimer, ticktimer: ticktimer_server::Ticktimer,
gam: gam::Gam, gam: gam::Gam,
cb_registrations: HashMap::<u32, String::<256>>, cb_registrations: HashMap::<u32, XousString::<256>>,
trng: Trng, trng: Trng,
xns: xous_names::XousNames, xns: xous_names::XousNames,
} }
impl CommonEnv { impl CommonEnv {
/* currently unused
pub fn register_handler(&mut self, verb: String::<256>) -> u32 { pub fn set(&mut self, key: &str, value: &str) -> Result<(), Error> {
let mut key: u32; log::info!("set '{}' = '{}'", key, value);
loop { let mut keypath = PathBuf::new();
key = self.trng.get_u32().unwrap(); keypath.push(MTXCLI_DICT);
// reserve the bottom 1000 IDs for the main loop enums. std::fs::create_dir_all(&keypath)?;
if !self.cb_registrations.contains_key(&key) && (key > 1000) { keypath.push(key);
break; File::create(keypath)?.write_all(value.as_bytes())?;
} Ok(())
}
self.cb_registrations.insert(key, verb);
key
} }
*/
pub fn unset(&mut self, key: &str) -> Result<(), Error> {
log::info!("unset '{}'", key);
let mut keypath = PathBuf::new();
keypath.push(MTXCLI_DICT);
std::fs::create_dir_all(&keypath)?;
keypath.push(key);
if std::fs::metadata(&keypath).is_ok() { // keypath exists
std::fs::remove_file(keypath)?;
}
Ok(())
}
pub fn get(&mut self, key: &str) -> Result<Option<String>, Error> {
let mut keypath = PathBuf::new();
keypath.push(MTXCLI_DICT);
std::fs::create_dir_all(&keypath)?;
keypath.push(key);
if let Ok(mut file)= File::open(keypath) {
let mut value = String::new();
file.read_to_string(&mut value)?;
log::info!("get '{}' = '{}'", key, value);
Ok(Some(value))
} else {
Ok(None)
}
}
} }
/* /*
@ -80,13 +111,21 @@ impl CommonEnv {
*/ */
///// 1. add your module here, and pull its namespace into the local crate ///// 1. add your module here, and pull its namespace into the local crate
mod get; use get::*;
mod help; use help::*; mod help; use help::*;
mod set; use set::*;
mod status; use status::*;
mod unset; use unset::*;
pub struct CmdEnv { pub struct CmdEnv {
common_env: CommonEnv, common_env: CommonEnv,
lastverb: String::<256>, lastverb: XousString::<256>,
///// 2. declare storage for your command here. ///// 2. declare storage for your command here.
get_cmd: Get,
help_cmd: Help, help_cmd: Help,
set_cmd: Set,
status_cmd: Status,
unset_cmd: Unset,
} }
impl CmdEnv { impl CmdEnv {
pub fn new(xns: &xous_names::XousNames) -> CmdEnv { pub fn new(xns: &xous_names::XousNames) -> CmdEnv {
@ -105,59 +144,75 @@ impl CmdEnv {
log::info!("done creating CommonEnv"); log::info!("done creating CommonEnv");
CmdEnv { CmdEnv {
common_env: common, common_env: common,
lastverb: String::<256>::new(), lastverb: XousString::<256>::new(),
///// 3. initialize your storage, by calling new() ///// 3. initialize your storage, by calling new()
get_cmd: Get::new(&xns),
help_cmd: Help::new(&xns), help_cmd: Help::new(&xns),
set_cmd: Set::new(&xns),
status_cmd: Status::new(&xns),
unset_cmd: Unset::new(&xns),
} }
} }
pub fn dispatch(&mut self, maybe_cmdline: Option<&mut String::<1024>>, maybe_callback: Option<&MessageEnvelope>) -> Result<Option<String::<1024>>, xous::Error> { pub fn dispatch(&mut self, maybe_cmdline: Option<&mut XousString::<1024>>, maybe_callback: Option<&MessageEnvelope>) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = String::<1024>::new(); let mut ret = XousString::<1024>::new();
let commands: &mut [& mut dyn ShellCmdApi] = &mut [ let commands: &mut [& mut dyn ShellCmdApi] = &mut [
///// 4. add your command to this array, so that it can be looked up and dispatched ///// 4. add your command to this array, so that it can be looked up and dispatched
&mut self.get_cmd,
&mut self.help_cmd, &mut self.help_cmd,
&mut self.set_cmd,
&mut self.status_cmd,
&mut self.unset_cmd,
]; ];
if let Some(cmdline) = maybe_cmdline { if let Some(cmdline) = maybe_cmdline {
let maybe_verb = tokenize(cmdline); let maybe_verb = tokenize(cmdline);
let mut cmd_ret: Result<Option<String::<1024>>, xous::Error> = Ok(None); let mut cmd_ret: Result<Option<XousString::<1024>>, xous::Error> = Ok(None);
if let Some(verb_string) = maybe_verb { if let Some(verb_string) = maybe_verb {
let verb = verb_string.to_str(); let verb = verb_string.to_str();
// search through the list of commands linearly until one matches, // if verb starts with a slash then it's a command (else chat)
// then run it. if verb.starts_with("/") {
let mut match_found = false; // search through the list of commands linearly until one
for cmd in commands.iter_mut() { // matches, then run it.
if cmd.matches(verb) { let command = &verb[1..];
match_found = true; let mut match_found = false;
cmd_ret = cmd.process(*cmdline, &mut self.common_env); for cmd in commands.iter_mut() {
self.lastverb.clear(); if cmd.matches(command) {
write!(self.lastverb, "{}", verb).expect("couldn't record last verb"); match_found = true;
}; cmd_ret = cmd.process(*cmdline, &mut self.common_env);
} self.lastverb.clear();
write!(self.lastverb, "{}", verb).expect("couldn't record last verb");
// if none match, create a list of available commands };
if !match_found {
let mut first = true;
write!(ret, "Commands: ").unwrap();
for cmd in commands.iter() {
if !first {
ret.append(", ")?;
}
ret.append(cmd.verb())?;
first = false;
} }
// if none match, create a list of available commands
if !match_found {
let mut first = true;
write!(ret, "Commands: ").unwrap();
for cmd in commands.iter() {
if !first {
ret.append(", ")?;
}
ret.append("/")?;
ret.append(cmd.verb())?;
first = false;
}
Ok(Some(ret))
} else {
cmd_ret
}
} else { // chat
write!(ret, "SAY: {} {}", verb, cmdline.to_str()).unwrap();
Ok(Some(ret)) Ok(Some(ret))
} else {
cmd_ret
} }
} else { } else {
Ok(None) Ok(None)
} }
} else if let Some(callback) = maybe_callback { } else if let Some(callback) = maybe_callback {
let mut cmd_ret: Result<Option<String::<1024>>, xous::Error> = Ok(None); let mut cmd_ret: Result<Option<XousString::<1024>>, xous::Error> = Ok(None);
// first check and see if we have a callback registration; if not, just map to the last verb // first check and see if we have a callback registration; if not, just map to the last verb
let verb = match self.common_env.cb_registrations.get(&(callback.body.id() as u32)) { let verb = match self.common_env.cb_registrations.get(&(callback.body.id() as u32)) {
Some(verb) => { Some(verb) => {
@ -190,9 +245,9 @@ impl CmdEnv {
/// extract the first token, as delimited by spaces /// extract the first token, as delimited by spaces
/// modifies the incoming line by removing the token and returning the remainder /// modifies the incoming line by removing the token and returning the remainder
/// returns the found token /// returns the found token
pub fn tokenize(line: &mut String::<1024>) -> Option<String::<1024>> { pub fn tokenize(line: &mut XousString::<1024>) -> Option<XousString::<1024>> {
let mut token = String::<1024>::new(); let mut token = XousString::<1024>::new();
let mut retline = String::<1024>::new(); let mut retline = XousString::<1024>::new();
let lineiter = line.as_str().unwrap().chars(); let lineiter = line.as_str().unwrap().chars();
let mut foundspace = false; let mut foundspace = false;

View file

@ -0,0 +1,47 @@
use crate::{ShellCmdApi,CommonEnv};
use xous_ipc::String as XousString;
use core::fmt::Write;
use locales::t;
#[derive(Debug)]
pub struct Get {
}
impl Get {
pub fn new(_xns: &xous_names::XousNames) -> Self {
Get {
}
}
}
impl<'a> ShellCmdApi<'a> for Get {
cmd_api!(get);
fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = XousString::<1024>::new();
let mut tokens = args.as_str().unwrap().split(' ');
if let Some(key) = tokens.next() {
match key {
"" => {
write!(ret, "{}", t!("mtxcli.get.help", xous::LANG)).unwrap();
}
_ => {
match env.get(key) {
Ok(None) => {
write!(ret, "{} is UNSET", key).unwrap();
},
Ok(Some(value)) => {
write!(ret, "{}", value).unwrap();
}
Err(e) => {
write!(ret, "error getting key {}: {:?}", key, e).unwrap();
log::error!("error getting key {}: {:?}", key, e);
}
}
}
}
}
Ok(Some(ret))
}
}

View file

@ -1,5 +1,5 @@
use crate::{ShellCmdApi,CommonEnv}; use crate::{ShellCmdApi,CommonEnv};
use xous_ipc::String; use xous_ipc::String as XousString;
use core::fmt::Write; use core::fmt::Write;
use locales::t; use locales::t;
@ -16,20 +16,39 @@ impl Help {
impl<'a> ShellCmdApi<'a> for Help { impl<'a> ShellCmdApi<'a> for Help {
cmd_api!(help); cmd_api!(help);
fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result<Option<String::<1024>>, xous::Error> { fn process(&mut self, args: XousString::<1024>, _env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = String::<1024>::new(); let mut ret = XousString::<1024>::new();
let mut tokens = args.as_str().unwrap().split(' '); let mut tokens = args.as_str().unwrap().split(' ');
// write!(ret, "{}", t!("mtxcli.help.helpting", xous::LANG)).unwrap(); if let Some(slashcmd) = tokens.next() {
let cmd = if slashcmd.starts_with("/") {
if let Some(cmd) = tokens.next() { &slashcmd[1..]
} else {
slashcmd
};
match cmd { match cmd {
"get" => {
write!(ret, "{}", t!("mtxcli.get.help", xous::LANG)).unwrap();
}
"help" => { "help" => {
write!(ret, "{}", t!("mtxcli.help.help", xous::LANG)).unwrap(); write!(ret, "{}", t!("mtxcli.help.help", xous::LANG)).unwrap();
} }
"set" => {
write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap();
}
"status" => {
write!(ret, "{}", t!("mtxcli.status.help", xous::LANG)).unwrap();
}
"unset" => {
write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap();
}
"" => { "" => {
write!(ret, "{}\n", t!("mtxcli.help.overview", xous::LANG)).unwrap(); write!(ret, "{}\n", t!("mtxcli.help.overview", xous::LANG)).unwrap();
write!(ret, "{}", t!("mtxcli.help.help", xous::LANG)).unwrap(); write!(ret, "{}\n", t!("mtxcli.get.help", xous::LANG)).unwrap();
write!(ret, "{}\n", t!("mtxcli.help.help", xous::LANG)).unwrap();
write!(ret, "{}\n", t!("mtxcli.set.help", xous::LANG)).unwrap();
write!(ret, "{}\n", t!("mtxcli.status.help", xous::LANG)).unwrap();
write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap();
} }
_ => { _ => {
write!(ret, "{}: {}", write!(ret, "{}: {}",

View file

@ -0,0 +1,57 @@
use crate::{ShellCmdApi,CommonEnv};
use xous_ipc::String as XousString;
use core::fmt::Write;
use locales::t;
#[derive(Debug)]
pub struct Set {
}
impl Set {
pub fn new(_xns: &xous_names::XousNames) -> Self {
Set {
}
}
}
impl<'a> ShellCmdApi<'a> for Set {
cmd_api!(set);
fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = XousString::<1024>::new();
let mut tokens = args.as_str().unwrap().split(' ');
if let Some(key) = tokens.next() {
match key {
"" => {
write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap();
}
_ => {
if let Some(value) = tokens.next() {
match value {
"" => {
write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap();
}
_ => {
match env.set(key, value) {
Ok(()) => {
write!(ret, "set {} = {}", key, value).unwrap();
},
Err(e) => {
write!(ret, "error setting key {}: {:?}",
key, e).unwrap();
log::error!("error setting key {}: {:?}",
key, e);
}
}
}
}
} else {
write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap();
}
}
}
}
Ok(Some(ret))
}
}

View file

@ -0,0 +1,25 @@
use crate::{ShellCmdApi,CommonEnv};
use xous_ipc::String as XousString;
use core::fmt::Write;
// use locales::t;
#[derive(Debug)]
pub struct Status {
}
impl Status {
pub fn new(_xns: &xous_names::XousNames) -> Self {
Status {
}
}
}
impl<'a> ShellCmdApi<'a> for Status {
cmd_api!(status);
fn process(&mut self, _args: XousString::<1024>, _env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = XousString::<1024>::new();
write!(ret, "status: not connected").unwrap();
Ok(Some(ret))
}
}

View file

@ -0,0 +1,45 @@
use crate::{ShellCmdApi,CommonEnv};
use xous_ipc::String as XousString;
use core::fmt::Write;
use locales::t;
#[derive(Debug)]
pub struct Unset {
}
impl Unset {
pub fn new(_xns: &xous_names::XousNames) -> Self {
Unset {
}
}
}
impl<'a> ShellCmdApi<'a> for Unset {
cmd_api!(unset);
fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = XousString::<1024>::new();
let mut tokens = args.as_str().unwrap().split(' ');
if let Some(key) = tokens.next() {
match key {
"" => {
write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap();
}
_ => {
match env.unset(key) {
Ok(()) => {
write!(ret, "unset {}", key).unwrap();
},
Err(e) => {
write!(ret, "error unsetting key {}: {:?}",
key, e).unwrap();
log::error!("error unsetting key {}: {:?}", key, e);
}
}
}
}
}
Ok(Some(ret))
}
}