Riscue-D（正式名称 RiescueD）は、Tenstorrent が提供する RISC-V 向け Directed Test Framework である。 単なる ISA 命令列テストの生成ツールではなく、特権レベル、仮想メモリ、例外処理、OS ライクな実行環境まで含めたシステムレベルのテストを、アセンブリ記述とディレクティブ指定によって構築できる点が特徴となっている。
Directed Test Generator
Riscue-D は “Directed Test” を強く意識した設計になっている。
- テストシナリオは人間が制御する
- 面倒な初期化・環境構築はツールに任せる
- 境界条件や揺らぎはランダム化で埋める
アセンブリコードにコメント形式のディレクティブを記述することで、テストの環境や制約を宣言的に指定できる。
テスト記述の基本構造
Riscue-D のテストは .s 形式のアセンブリファイルとして記述する。
ファイル冒頭には Test Header と呼ばれるディレクティブ群を置き、テストの前提条件を定義する。
以下のような指定が可能である：
- 対象アーキテクチャ（rv32 / rv64）
- 実行特権（Machine / Supervisor / User）
- ページング方式（SV39 など）
- 使用する拡張命令セット
- 仮想化の有無
ランダム化の扱い方
Riscue-D は局所的なランダム化を強力にサポートしている。
- レジスタにロードするランダムデータ
- マスク付きのランダム値
- ページ境界を意識したランダムアドレス
これらはディレクティブとして宣言し、アセンブリ中から名前で参照する形になる。
仮想メモリとページテーブル生成
Riscue-D の中核機能の一つが、ページテーブルの自動生成である。
SV39 / SV48 といった RISC-V のページング方式に対し、
- ページサイズ
- R/W/X 権限
- 有効ビット
- 仮想アドレスと物理アドレスの対応
をディレクティブで指定すると、必要なページテーブル構造が自動生成される。
例外・トラップハンドリングの検証
Riscue-D は例外テストを「発生させるだけ」ではなく、例外ハンドラへの遷移、mepc/sepc の更新、復帰後の制御フローまでを含めて検証対象としている。
ECALL、不正命令、ページフォルトなどを明示的に発生させ、
- 正しい例外コードが立つか
- 想定したラベルに復帰するか
といった点をテストシナリオとして記述できる。
実行フローとツールチェーン
テストの生成と実行は CLI から行う。
- アセンブリ＋ディレクティブを入力
- CPU 構成を JSON で指定
- ELF および展開済みアセンブリを生成
- Spike や Whisper で実行
という流れになる。
Riscue-Dのインストール
python3 -m venv .venv source .venv/bin/activate pip install git+https://github.com/tenstorrent/riescue.git
Collecting coretp@ git+https://git@github.com/tenstorrent/riscv-coretp@df220d2e446e2f5dc03148791894bdfd83d9cfff
Cloning https://****@github.com/tenstorrent/riscv-coretp (to revision df220d2e446e2f5dc03148791894bdfd83d9cfff) to /tmp/pip-install-e3o81t_p/coretp_b08005dff5e04bf997511c2375cf6e93
Running command git clone --filter=blob:none --quiet 'https://****@github.com/tenstorrent/riscv-coretp' /tmp/pip-install-e3o81t_p/coretp_b08005dff5e04bf997511c2375cf6e93
Running command git rev-parse -q --verify 'sha^df220d2e446e2f5dc03148791894bdfd83d9cfff'
Running command git fetch -q 'https://****@github.com/tenstorrent/riscv-coretp' df220d2e446e2f5dc03148791894bdfd83d9cfff
Running command git checkout -q df220d2e446e2f5dc03148791894bdfd83d9cfff
Resolved https://****@github.com/tenstorrent/riscv-coretp to commit df220d2e446e2f5dc03148791894bdfd83d9cfff
Installing build dependencies ... done
Getting requirements to build wheel ... done
Preparing metadata (pyproject.toml) ... done
Collecting sphinxcontrib.mermaid
Downloading sphinxcontrib_mermaid-1.2.3-py3-none-any.whl (13 kB)
Collecting pyyaml
Downloading pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (770 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 770.3/770.3 KB 29.1 MB/s eta 0:00:00
Collecting sphinx-rtd-theme
Downloading sphinx_rtd_theme-3.0.2-py2.py3-none-any.whl (7.7 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.7/7.7 MB 87.8 MB/s eta 0:00:00
Collecting sphinx>=7.4.0
Downloading sphinx-8.1.3-py3-none-any.whl (3.5 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.5/3.5 MB 90.1 MB/s eta 0:00:00
Collecting sortedcontainers
Downloading sortedcontainers-2.4.0-py2.py3-none-any.whl (29 kB)
Collecting flake8
Downloading flake8-7.3.0-py2.py3-none-any.whl (57 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 57.9/57.9 KB 12.3 MB/s eta 0:00:00
Collecting intervaltree
Downloading intervaltree-3.1.0.tar.gz (32 kB)
Preparing metadata (setup.py) ... done
Collecting pyright[nodejs]
Downloading pyright-1.1.407-py3-none-any.whl (6.0 MB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.0/6.0 MB 91.7 MB/s eta 0:00:00
Collecting numpy
Downloading numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (16.8 MB)
...
Building wheel for coretp (pyproject.toml) ... done
Created wheel for coretp: filename=coretp-0.1.0-py3-none-any.whl size=132766 sha256=93b5dca0506d80b903168a07e6977c387b960043801eb5130585ec640c22963d
Stored in directory: /home/msyksphinz/.cache/pip/wheels/c3/79/95/4c5990a88201d306e8a26c75dd68812cbb56339bfc8045cef
Successfully built riescue coretp
Installing collected packages: sortedcontainers, urllib3, typing-extensions, tomli, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-jsmath, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, snowballstemmer, pyyaml, Pygments, pyflakes, pycodestyle, platformdirs, pillow, pathspec, packaging, numpy, node
js-wheel-binaries, nodeenv, mypy-extensions, mccabe, MarkupSafe, intervaltree, imagesize, idna, et-xmlfile, docutils, coverage, click, charset_normalizer, certifi, babel, alabaster, requests, reportlab, pyright, openpyxl, Jinja2, flake8, black, sphinx, sphinxcontrib.mermaid, sphinxcontrib-jquery, coretp, sphinx-rtd-theme, riescue
Running setup.py install for intervaltree ... done
Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.3 Pygments-2.19.2 alabaster-1.0.0 babel-2.17.0 black-25.1.0 certifi-2025.11.12 charset_normalizer-3.4.4 click-8.3.1 coretp-0.1.0 coverage-7.13.0 docutils-0.21.2 et-xmlfile-2.0.0 flake8-7.3.0 idna-3.11 imagesize-1.4.1 intervaltree-3.1.0 mccabe-0.7.0 mypy-extensions-1.1.0 nodeenv-1.9.1 nodejs-
wheel-binaries-24.12.0 numpy-2.2.6 openpyxl-3.1.5 packaging-25.0 pathspec-0.12.1 pillow-12.0.0 platformdirs-4.5.1 pycodestyle-2.14.0 pyflakes-3.4.0 pyright-1.1.407 pyyaml-6.0.3 reportlab-4.4.6 requests-2.32.5 riescue-1.7.0 snowballstemmer-3.0.1 sortedcontainers-2.4.0 sphinx-8.1.3 sphinx-rtd-theme-3.0.2 sphinxcontrib-applehelp-2.0.0 sphinxcon
trib-devhelp-2.0.0 sphinxcontrib-htmlhelp-2.1.0 sphinxcontrib-jquery-4.1 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-2.0.0 sphinxcontrib-serializinghtml-2.0.0 sphinxcontrib.mermaid-1.2.3 tomli-2.3.0 typing-extensions-4.15.0 urllib3-2.6.2
Helpを表示させて確認してみる。
msyksphinz$ riescued -h
fpgen unavailable, skipping
usage: riescued [-h] [--testfile TESTFILE] [--testname TESTNAME] [--run_dir RUN_DIR] [--seed SEED] [--cpuconfig CPUCONFIG] [--conf CONF] [--elaborate_only] [--run_iss]
[--tohost_nonzero_terminate] [--counter_event_path COUNTER_EVENT_PATH] [--max_logger_file_gb MAX_LOGGER_FILE_GB] [--test_priv_mode TEST_PRIV_MODE]
[--test_paging_mode TEST_PAGING_MODE] [--test_paging_g_mode TEST_PAGING_G_MODE] [--test_env {bare_metal,virtualized}] [--test_env_any]
[--test_secure_mode {on,off,random,any}] [--supported_priv_modes {MSU,MS,MU,M}] [--tohost TOHOST] [--eot_pass_value EOT_PASS_VALUE]
[--eot_fail_value EOT_FAIL_VALUE] [--mp MP] [--mp_mode MP_MODE] [--parallel_scheduling_mode PARALLEL_SCHEDULING_MODE] [--num_cpus NUM_CPUS]
[--single_assembly_file] [--force_alignment] [--c_used] [--small_bss] [--big_bss] [--big_endian] [--more_os_pages] [--add_gcc_cstdlib_sections]
[--addrgen_limit_indices] [--code_offset CODE_OFFSET] [--randomize_code_location] [--repeat_times REPEAT_TIMES] [--private_maps] [--cfile CFILE]
[--enable_machine_paging] [--fe_tb] [--wysiwyg] [--linux_mode] [--bringup_pagetables] [--reserve_partial_phys_memory] [--all_4kb_pages] [--disallow_mmio]
[--addrgen_limit_way_predictor_multihit] [--deleg_excp_to {machine,super}] [--switch_to_machine_page SWITCH_TO_MACHINE_PAGE]
[--switch_to_super_page SWITCH_TO_SUPER_PAGE] [--switch_to_user_page SWITCH_TO_USER_PAGE] [--user_interrupt_table] [--excp_hooks] [--interrupts_enabled]
[--interrupts_disabled] [--skip_instruction_for_unexpected] [--disable_wfi_wait] [--setup_pmp] [--needs_pma] [--num_pmas NUM_PMAS] [--vmm_hooks]
[--setup_stateen] [--csr_init CSR_INIT] [--csr_init_mask CSR_INIT_MASK] [--no_random_csr_reads] [--max_random_csr_reads MAX_RANDOM_CSR_READS]
[--random_machine_csr_list RANDOM_MACHINE_CSR_LIST] [--random_supervisor_csr_list RANDOM_SUPERVISOR_CSR_LIST]
[--random_user_csr_list RANDOM_USER_CSR_LIST] [--medeleg MEDELEG] [--mideleg MIDELEG] [--hedeleg HEDELEG] [--hideleg HIDELEG] [--menvcfg MENVCFG]
[--henvcfg HENVCFG] [--senvcfg SENVCFG] [--secure_access_probability SECURE_ACCESS_PROBABILITY] [--secure_pt_probability SECURE_PT_PROBABILITY]
[--a_d_bit_randomization A_D_BIT_RANDOMIZATION] [--pbmt_ncio_randomization PBMT_NCIO_RANDOMIZATION] [--logger_level {DEBUG,INFO,WARNING,ERROR}]
[--logger_file LOGGER_FILE] [--logger_no_tee] [--logger_no_timestamp] [--logger_max_file_size_gb LOGGER_MAX_FILE_SIZE_GB] [--logger_verbose]
[--iss {whisper,spike}] [--compiler_path COMPILER_PATH] [--compiler_opts [COMPILER_OPTS ...]] [--compiler_march COMPILER_MARCH]
[--compiler_mabi COMPILER_MABI] [--test_equates TEST_EQUATES] [--disassembler_path DISASSEMBLER_PATH] [--disassembler_opts [DISASSEMBLER_OPTS ...]]
[--spike_path SPIKE_PATH] [--spike_args [SPIKE_ARGS ...]] [--spike_isa SPIKE_ISA] [--third_party_spike] [--spike_max_instr SPIKE_MAX_INSTR]
[--whisper_path WHISPER_PATH] [--whisper_args [WHISPER_ARGS ...]] [--whisper_config_json WHISPER_CONFIG_JSON] [--whisper_max_instr WHISPER_MAX_INSTR]
[--whisper_memory_size WHISPER_MEMORY_SIZE] [--whisper_dumpmem WHISPER_DUMPMEM] [--whisper_startpc WHISPER_STARTPC]
options:
-h, --help show this help message and exit
--testfile TESTFILE, -t TESTFILE
Testname with path to be compiled with RiESCUE-D
--testname TESTNAME Legacy switch to be deprecated, use --testfile instead.
--run_dir RUN_DIR, -rd RUN_DIR
Run directory where the test will be run
