From 90486c3a2a71da3ef96709df3e158ccb61fe3278 Mon Sep 17 00:00:00 2001 From: Andy Chan Date: Fri, 13 Mar 2026 23:29:01 -0700 Subject: [PATCH 1/2] docs: add pddbci testing instructions to tools README Replace the _TBD_ testing section with concrete steps for running pddbci.py, including Python venv setup and dependency installation. --- tools/README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/tools/README.md b/tools/README.md index f54bdb88c..7d76f0f98 100644 --- a/tools/README.md +++ b/tools/README.md @@ -80,7 +80,52 @@ For more about `i18n_helper.py` please see the locales [README](../locales/READM ## Testing -_TBD_ +### Running `pddbci.py` (PDDB Regression Tests) + +`pddbci.py` drives the PDDB regression suite. It calls `cargo xtask pddb-ci` +to generate test images and then runs `pddbdbg.py` to verify them. The +analysis step requires Python 3 and several third-party packages. + +#### 1. Create a Python virtual environment + +```sh +# From the repository root +python3 -m venv venv +source venv/bin/activate +``` + +#### 2. Install system build tools + +`pyaesni` is a native extension compiled from source. Make sure `cmake` +and `yasm` are installed on your system before proceeding. + +#### 3. Install Python dependencies + +`pyaesni` must be installed from its Git repository (the PyPI tarball is +missing build files): + +```sh +pip install pycryptodome cryptography six +pip install git+https://github.com/painor/pyaesni.git +``` + +#### 4. Run the regression tests + +Choose the `--name` of a database image from `tools/pddb-images` + +```sh +# From the repository root, with the venv active +python3 tools/pddbci.py --name full +``` + +The `--runs` flag controls iteration count (default 501). Use a smaller +value for a quick smoke test: + +```sh +python3 tools/pddbci.py --name full --runs 5 +``` + +You can adjust verbosity with `--loglevel DEBUG`. ## Contribution Guidelines From 19bffd52f50cc1faaf44bc0e7b7fbda007e61678 Mon Sep 17 00:00:00 2001 From: bunnie Date: Wed, 6 May 2026 15:38:45 +0800 Subject: [PATCH 2/2] Update README.md update with a little more detail on how to run & use --- tools/README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/tools/README.md b/tools/README.md index 7d76f0f98..d9292d5e3 100644 --- a/tools/README.md +++ b/tools/README.md @@ -80,9 +80,11 @@ For more about `i18n_helper.py` please see the locales [README](../locales/READM ## Testing -### Running `pddbci.py` (PDDB Regression Tests) +The director is overloaded with some Python scripts used for PDDB tests. These probably should be moved to a more appropriate location in the future. However, it is what it is for now. -`pddbci.py` drives the PDDB regression suite. It calls `cargo xtask pddb-ci` +### Running `pddbci.py` (PDDB Regression/Fuzzing Tests) + +`pddbci.py` drives the PDDB regression & fuzzing suite. It calls `cargo xtask pddb-ci` to generate test images and then runs `pddbdbg.py` to verify them. The analysis step requires Python 3 and several third-party packages. @@ -106,23 +108,30 @@ missing build files): ```sh pip install pycryptodome cryptography six -pip install git+https://github.com/painor/pyaesni.git ``` +Note: `pyaesni` was deprecated because the package does not install on all operating systems. The AES routine has been reverted to the standard Python AES routine which causes the test loop to run a bit slower. + #### 4. Run the regression tests Choose the `--name` of a database image from `tools/pddb-images` +The database images are generated by code that runs here: + +https://github.com/betrusted-io/xous-core/blob/c105531e48c59159c4051fdd9c5e539a5c36377e/services/pddb/src/tests.rs#L592-L596 + +The images are incremental snapshots of various tests working through the PDDB. In practice, the final test (`basis2`) is the test one would run the fuzzing/regression suite on, and in case of a regression, then one would analyze earlier snapshots to work out the root cause of the regression. + ```sh # From the repository root, with the venv active -python3 tools/pddbci.py --name full +python3 tools/pddbci.py --name basis2 ``` The `--runs` flag controls iteration count (default 501). Use a smaller value for a quick smoke test: ```sh -python3 tools/pddbci.py --name full --runs 5 +python3 tools/pddbci.py --name basis2 --runs 5 ``` You can adjust verbosity with `--loglevel DEBUG`.