Tips and Tricks

Code Samples

• checkout the README.md in apps/ball apps/hello and apps/repl
• numerous basic commands in services/shellchat/src/cmsd/*.rs
• modals in services/modals/src/tests.rs
• tls in libs/tls/src/cmds.rs

xtask Switches of Note

• --no-verify will disable verification of crates downloaded from crates.io against the source code. Useful for when you are updating a crate that is sourced from crates.io
• Cargo.toml contains numerous commented out patch options to configure the build to refer to local source instead of crates.io
• --gdb-stub adds GDB support
• --no-timestamp will suppress timestamping. Can improve build times and/or aid with reproduceable builds on the same build host.
• generate-locales is required after any change to any i18n.json file.

Turn on Debug Logs

Almost every server has a line similar to this near the top of main:

fn main() -> ! {
    log_server::init_wait().unwrap();
    log::set_max_level(log::LevelFilter::Info);
    log::info!("my PID is {}", xous::process::id());

Change log::set_max_level to log::LevelFilter::Debug. In most servers, this will cause the current message code to be printed to the debug console.

• You can call log::set_max_level at any time. Use this to your advantage if you are getting too much debug spew, by wrapping the region of interest in a call that toggles to Debug and then back to Info when leaving the region.
• There is an even more verbose level, Trace, that can be configured as well
• Remember that lib code runs in the space of your server, so any log calls in the lib stubs will also be affected by the configuration of the logging level in your server.

Access logs on Precursor hardware

You can connect your PC to Precursor with a usb cable and use a terminal emulator to input with the PC keyboard and read logs real-time.

• connect Precursor with usb cable
• shellchat: usb console
• linux cli:
  • the current user will need to belong to the dialout group
  • mincom: use minicom -s to configure Serial Device : /dev/ttyACM0 Hardware Flow Control : No Add carriage return : Yes and then Save setup as dfl. Start mincom with mincom and quit with ctrl-A q enter

Run GDB

GDB works on Xous, both from Renode and on real hardware.

See "Debugging Programs" in the Xous book.

• This does require a custom firmware build with GDB support. It is not on by default for security reasons.
• Pay attention that thread IDs in GDB are different from those in Xous.
• You can only attach to one process at a time with GDB.
• Debugging real hardware requires a Pi-HAT and debug cable attachment.

Analysis Tools

• analyze-bloat.sh will generate annotated assembly listings of every file. It does add symbols to the binaries, which changes their size. If you want assembly listings without symbols (which lines up with actual hardware) see the script for examples of how to generate the listings.
• backalyzer can dump the entire PDDB contents, given the cryptographic keys for your PDDB and a backup image.

Unicode characters available

README latin hanzi and emoji

Moving an app into it's own repository.

You have been developing a xous app in xous-core/apps/ and the time has come to move it into it's own repository.

There is a relatively straight-forward git way to make the move and keep the commit history.

xous-core
└ api
└ apps
  └ ball
  └ hello
  └myapp
    └ Cargo.toml
    └ locales
    └ README.md
    └ src
  ...
└ .git
  ...

myapp
└ Cargo.toml
└ locales
└ README.md
└ src
└ .git
  ...

The first step is to clone both repositories into a temp working directory - to give yourself the opportunity to back out and try again if things don't work out.

mkdir temp
cd temp
git clone [email protected]:betrusted-io/xous-core.git
git clone [email protected]:owner/myapp.git

The second step is to filter the clone of xous-core such that only myapp remains. Get into the xous-core clone with cd xous-core then

git checkout filter-source
git filter-repo --subdirectory-filter apps/myapp --force

If this doesn't work out, then you can simply git checkout main and git branch --delete filter-source and then try again.

The third step is to bring filter-source into your new myapp repository. Get into the myapp clone with cd ../myapp then

git checkout -b filter-target
git remote add repo-source ../xous-core
git fetch repo-source
git branch branch-source remotes/repo-source/filter-source
git merge branch-source --allow-unrelated-histories

At this point you may have some merge conflicts to resolve. When you have checked everything is as you would expect then you can git push back to the repository and discard the temp working directory.