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
# PDDB for mtxcli (only for testing in hosted mode)
/kernel/mtxcli
# performance monitoring page table
tools/ct_data/v2p.txt
@ -72,4 +75,3 @@ share/python-wheels/
.installed.cfg
*.egg
MANIFEST

View file

@ -2,70 +2,40 @@
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
with `cargo xtask app-image mtxcli` or `cargo xtask run mtxcli`.
![screenshot](mtxcli_screenshot.png)
# Inherited from REPL
## Background
A simple demo application that provides a bare-bones REPL framework.
## Copying This Demo to a New App
This is a simple [Matrix chat](https://matrix.org/) application based on the REPL framework.
1. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`.
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
## Setup
![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
style interface (stacking bubbles of text, with user input right-aligned
and shell feedback left-aligned) to facilitate interactions.
* Create a new Matrix user:
* https://matrix.org/faq/#how-do-i-get-an-account-and-get-started%3F
* 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`
- Graphical output is rendered via the `gam`
The following commands are available in **mtxcli**:
* `/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
messages between an Xous application and the Xous Services.
## Chatting
The one demo command provisioned in the `repl` app plays a tone via
the `codec` service. This was chosen because it is about one of the most complicated
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.
Any line not starting with a slash ('/') will be sent to the current room.
New messages from the current room will be displayed.
To make your own command, copy the `audio.rs` template
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.
_NOTE:_ chatting is not implemented yet

View file

@ -5,10 +5,16 @@
"zh": "简单的 mtxcli 演示活动",
"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": {
"en": "help [cmd]",
"ja": "TBD help [cmd]",
"zh": "TBD help [cmd]",
"en": "/help [cmd]",
"ja": "TBD /help [cmd]",
"zh": "TBD /help [cmd]",
"en-tts": "help [cmd]"
},
"mtxcli.help.overview": {
@ -17,6 +23,24 @@
"zh": "TBD 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": {
"en": "unknown command",
"ja": "TBD unknown command",

View file

@ -1,15 +1,22 @@
use xous::{MessageEnvelope};
use xous_ipc::String;
use xous_ipc::String as XousString;
use core::fmt::Write;
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
pub trait ShellCmdApi<'a> {
// user implemented:
// 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
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);
Ok(None)
}
@ -46,25 +53,49 @@ pub struct CommonEnv {
codec: codec::Codec,
ticktimer: ticktimer_server::Ticktimer,
gam: gam::Gam,
cb_registrations: HashMap::<u32, String::<256>>,
cb_registrations: HashMap::<u32, XousString::<256>>,
trng: Trng,
xns: xous_names::XousNames,
}
impl CommonEnv {
/* currently unused
pub fn register_handler(&mut self, verb: String::<256>) -> u32 {
let mut key: u32;
loop {
key = self.trng.get_u32().unwrap();
// reserve the bottom 1000 IDs for the main loop enums.
if !self.cb_registrations.contains_key(&key) && (key > 1000) {
break;
}
}
self.cb_registrations.insert(key, verb);
key
pub fn set(&mut self, key: &str, value: &str) -> Result<(), Error> {
log::info!("set '{}' = '{}'", key, value);
let mut keypath = PathBuf::new();
keypath.push(MTXCLI_DICT);
std::fs::create_dir_all(&keypath)?;
keypath.push(key);
File::create(keypath)?.write_all(value.as_bytes())?;
Ok(())
}
*/
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
mod get; use get::*;
mod help; use help::*;
mod set; use set::*;
mod status; use status::*;
mod unset; use unset::*;
pub struct CmdEnv {
common_env: CommonEnv,
lastverb: String::<256>,
lastverb: XousString::<256>,
///// 2. declare storage for your command here.
get_cmd: Get,
help_cmd: Help,
set_cmd: Set,
status_cmd: Status,
unset_cmd: Unset,
}
impl CmdEnv {
pub fn new(xns: &xous_names::XousNames) -> CmdEnv {
@ -105,59 +144,75 @@ impl CmdEnv {
log::info!("done creating CommonEnv");
CmdEnv {
common_env: common,
lastverb: String::<256>::new(),
lastverb: XousString::<256>::new(),
///// 3. initialize your storage, by calling new()
get_cmd: Get::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> {
let mut ret = String::<1024>::new();
pub fn dispatch(&mut self, maybe_cmdline: Option<&mut XousString::<1024>>, maybe_callback: Option<&MessageEnvelope>) -> Result<Option<XousString::<1024>>, xous::Error> {
let mut ret = XousString::<1024>::new();
let commands: &mut [& mut dyn ShellCmdApi] = &mut [
///// 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.set_cmd,
&mut self.status_cmd,
&mut self.unset_cmd,
];
if let Some(cmdline) = maybe_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 {
let verb = verb_string.to_str();
// search through the list of commands linearly until one matches,
// then run it.
let mut match_found = false;
for cmd in commands.iter_mut() {
if cmd.matches(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 verb starts with a slash then it's a command (else chat)
if verb.starts_with("/") {
// search through the list of commands linearly until one
// matches, then run it.
let command = &verb[1..];
let mut match_found = false;
for cmd in commands.iter_mut() {
if cmd.matches(command) {
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("/")?;
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))
} else {
cmd_ret
}
} else {
Ok(None)
}
} 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
let verb = match self.common_env.cb_registrations.get(&(callback.body.id() as u32)) {
Some(verb) => {
@ -190,9 +245,9 @@ impl CmdEnv {
/// extract the first token, as delimited by spaces
/// modifies the incoming line by removing the token and returning the remainder
/// returns the found token
pub fn tokenize(line: &mut String::<1024>) -> Option<String::<1024>> {
let mut token = String::<1024>::new();
let mut retline = String::<1024>::new();
pub fn tokenize(line: &mut XousString::<1024>) -> Option<XousString::<1024>> {
let mut token = XousString::<1024>::new();
let mut retline = XousString::<1024>::new();
let lineiter = line.as_str().unwrap().chars();
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 xous_ipc::String;
use xous_ipc::String as XousString;
use core::fmt::Write;
use locales::t;
@ -16,20 +16,39 @@ impl Help {
impl<'a> ShellCmdApi<'a> for Help {
cmd_api!(help);
fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result<Option<String::<1024>>, xous::Error> {
let mut ret = String::<1024>::new();
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(' ');
// write!(ret, "{}", t!("mtxcli.help.helpting", xous::LANG)).unwrap();
if let Some(cmd) = tokens.next() {
if let Some(slashcmd) = tokens.next() {
let cmd = if slashcmd.starts_with("/") {
&slashcmd[1..]
} else {
slashcmd
};
match cmd {
"get" => {
write!(ret, "{}", t!("mtxcli.get.help", xous::LANG)).unwrap();
}
"help" => {
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, "{}", 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, "{}: {}",

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))
}
}