Debug spec v1.0 implementation

bin/installation/openocd-install.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+###########################################
+## openocd debug install script.
+##
+## Written: James Stine, james.stine@okstate.edu
+## Created: Oct 16, 2025
+##
+## Purpose: openocd installation script
+##
+## A component of the CORE-V-WALLY configurable RISC-V project.
+## https://github.com/openhwgroup/cvw
+##
+## Copyright (C) 2021-24 Harvey Mudd College & Oklahoma State University
+##
+## SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+##
+## Licensed under the Solderpad Hardware License v 2.1 (the “License”); you may not use this file
+## except in compliance with the License, or, at your option, the Apache License version 2.0. You
+## may obtain a copy of the License at
+##
+## https:##solderpad.org/licenses/SHL-2.1/
+##
+## Unless required by applicable law or agreed to in writing, any work distributed under the
+## License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+## either express or implied. See the License for the specific language governing permissions
+## and limitations under the License.
+################################################################################################
+
+OPENOCD_VERSION=eb01c632a4bb1c07d2bddb008d6987c809f1c496 # Last commit as of 2025-10-09T10:08:18Z
+
+set -e # break on error
+# If run standalone, check environment. Otherwise, use info from main install script
+if [ -z "$FAMILY" ]; then
+    dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    WALLY="$(dirname $(dirname "$dir"))"
+    export WALLY
+    source "${dir}"/../wally-environment-check.sh
+fi
+
+# openocd (https://github.com/riscv-collab/riscv-openocd)
+# openocd is OpenOCD stands for Open On-Chip Debugger and is an open-source tool that provides
+# on-chip programming, debugging, and boundary-scan testing for embedded systems.
+section_header "Installing/Updating OpenOCD"
+STATUS="openocd"
+cd "$RISCV"
+if check_tool_version $OPENOCD_VERSION; then
+    git_checkout "riscv-openocd" "https://github.com/riscv-collab/riscv-openocd.git" "$OPENOCD_VERSION"
+    cd "$RISCV"/riscv-openocd
+    git submodule update --init --recursive
+    ./bootstrap
+    ./configure --enable-ftdi --enable-dummy --enable-jimtcl --prefix="$RISCV"
+    make -j "${NUM_THREADS}" 2>&1 | logger; [ "${PIPESTATUS[0]}" == 0 ]
+    sudo make install 2>&1 | logger; [ "${PIPESTATUS[0]}" == 0 ]
+    echo "$OPENOCD_VERSION" > "$RISCV"/versions/$STATUS.version # Record installed version
+    echo -e "${SUCCESS_COLOR}openocd successfully installed/updated!${ENDC}"
+else
+    echo -e "${SUCCESS_COLOR}openocd already up to date.${ENDC}"
+fi

bin/wally-package-install.sh

@@ -5,6 +5,7 @@
 ## Written: Jordan Carlin, jcarlin@hmc.edu
 ## Created: 30 June 2024
 ## Modified: May 30 2025
+## Modified: 24 Jan 2026, James Stine james.stine@okstate.edu
 ##
 ## Purpose: Package manager installation for open source tool chain installation script
 ##
@@ -48,6 +49,20 @@ SAIL_PACKAGES+=(cmake)
 VERILATOR_PACKAGES+=(autoconf flex bison help2man perl ccache numactl gtkwave) # gtkwave is not needed for verilator, but useful for viewing waveforms
 BUILDROOT_PACKAGES+=(patchutils perl cpio bc)
 
+# OPENOCD packages are distro-specific
+# OpenOCD build dependencies (Jim Tcl + FTDI + USB)
+case "$FAMILY" in
+  rhel)
+    OPENOCD_PACKAGES+=(jimtcl jimtcl-devel libftdi-devel libusb1-devel pkgconf-pkg-config)
+    ;;
+  ubuntu|debian)
+    OPENOCD_PACKAGES+=(libjim-dev libftdi1-dev libusb-1.0-0-dev pkg-config)
+    ;;
+  suse)
+    OPENOCD_PACKAGES+=(jimtcl jimtcl-devel libftdi-devel libusb-1_0-devel pkg-config)
+    ;;
+esac
+
 # Distro specific packages and package manager
 case "$FAMILY" in
     rhel)
@@ -121,11 +136,11 @@ esac
 if [ "${1}" == "--check" ]; then
     section_header "Checking Dependencies from Package Manager"
     if [[ "$FAMILY" == rhel || "$FAMILY" == suse ]]; then
-        for pack in "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}"; do
+        for pack in "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}" "${OPENOCD_PACKAGES[@]}"; do
             rpm -q "$pack" > /dev/null || (echo -e "${FAIL_COLOR}Missing packages detected (${WARNING_COLOR}$pack${FAIL_COLOR}). Run as root to auto-install or run wally-package-install.sh first.${ENDC}" && exit 1)
         done
     elif [[ "$FAMILY" == ubuntu || "$FAMILY" == debian ]]; then
-        for pack in "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}"; do
+        for pack in "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}" "${OPENOCD_PACKAGES[@]}"; do
             dpkg -l "$pack" | grep "ii" > /dev/null || (echo -e "${FAIL_COLOR}Missing packages detected (${WARNING_COLOR}$pack${FAIL_COLOR}). Run as root to auto-install or run wally-package-install.sh first." && exit 1)
         done
     fi
@@ -155,7 +170,7 @@ else
     # Update and Upgrade tools
     eval "$UPDATE_COMMAND"
     # Install packages listed above using appropriate package manager
-    eval $PACKAGE_MANAGER install "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}" "${VIVADO_PACKAGES[@]}"
+    eval $PACKAGE_MANAGER install "${GENERAL_PACKAGES[@]}" "${GNU_PACKAGES[@]}" "${QEMU_PACKAGES[@]}" "${SPIKE_PACKAGES[@]}" "${SAIL_PACKAGES[@]}" "${VERILATOR_PACKAGES[@]}" "${BUILDROOT_PACKAGES[@]}" "${OPENOCD_PACKAGES[@]}" "${VIVADO_PACKAGES[@]}"
 
     # Post install steps
     # Vivado looks for ncurses5 libraries, but Ubuntu 24.04 only has ncurses6

bin/wally-tool-chain-install.sh

@@ -5,6 +5,7 @@
 ## Written: Rose Thompson rose@rosethompson.net
 ## Modified: 30 June 2024, Jordan Carlin jcarlin@hmc.edu
 ## Modified: 30 May 2025
+## Modified: 24 Jan 2206, James Stine james.stine@okstate.edu
 ##
 ## Purpose: Open source tool chain installation script
 ##
@@ -110,6 +111,12 @@ source "$WALLY"/bin/installation/verilator-install.sh
 source "$WALLY"/bin/installation/skywater-lib-install.sh
 
 
+# OpenOCD installation for RISC-V debug support
+# OpenOCD is used to provide JTAG-based debugging and programming support
+# for the Wally RISC-V processor during bring-up and validation.
+source "$WALLY"/bin/installation/openocd-install.sh
+
+
 # Buildroot and Linux testvectors
 # Buildroot is used to boot a minimal version of Linux on Wally.
 # Testvectors are generated using QEMU.

config/derivlist.txt

@@ -58,6 +58,18 @@ EXT_MEM_RANGE       64'h7FFFFFFF
 SDC_SUPPORTED       1
 PLIC_SDC_ID         32'd20
 BPRED_SIZE          32'd12
+DEBUG_SUPPORTED     1
+TRIG_SUPPORTED      1
+
+# RV32GC with Debug Mode supported
+deriv debug32 rv32gc
+DEBUG_SUPPORTED 1
+TRIG_SUPPORTED 1
+
+# RV64GC with Debug Mode supported
+deriv debug64 rv64gc
+DEBUG_SUPPORTED 1
+TRIG_SUPPORTED 1
 
 deriv fpgaArtyA7 fpga
 EXT_MEM_RANGE       64'h0FFFFFFF

config/rv32e/config.vh

@@ -225,4 +225,10 @@ localparam DIVCOPIES = 32'd4;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/rv32gc/config.vh

@@ -227,4 +227,10 @@ localparam DIVCOPIES = 32'd2;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/rv32i/config.vh

@@ -225,4 +225,10 @@ localparam DIVCOPIES = 32'd4;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/rv32imc/config.vh

@@ -225,4 +225,10 @@ localparam DIVCOPIES = 32'd4;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/rv64gc/config.vh

@@ -228,4 +228,10 @@ localparam DIVCOPIES = 32'd4;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/rv64i/config.vh

@@ -225,4 +225,10 @@ localparam DIVCOPIES = 32'd4;
 // Memory synthesis configuration
 localparam logic USE_SRAM = 0;
 
+// Debug
+localparam logic DEBUG_SUPPORTED = 0;
+
+// Trig
+localparam logic TRIG_SUPPORTED = 0;
+
 `include "config-shared.vh"

config/shared/config-shared.vh

@@ -122,3 +122,8 @@ localparam FMALEN = 3*NF + 6;
 localparam NORMSHIFTSZ = `max(`max((CVTLEN+NF+1), (DIVb + 1 + NF + 1)), (FMALEN + 2));
 
 localparam LOGNORMSHIFTSZ = ($clog2(NORMSHIFTSZ));                  // log_2(NORMSHIFTSZ)
+
+// Debug Specification (if enabled)
+localparam JEDEC = 32'h1002ac05;
+localparam ABITS = 6'd7;
+localparam DTM_INSTR_WIDTH = 32'd5;

config/shared/parameter-defs.vh

@@ -197,5 +197,10 @@ localparam cvw_t P = '{
   DURLEN      : DURLEN,
   DIVb        : DIVb,
   DIVBLEN     : DIVBLEN,
-  INTDIVb     : INTDIVb
+  INTDIVb     : INTDIVb,
+  DEBUG_SUPPORTED : DEBUG_SUPPORTED,
+  JEDEC : JEDEC,
+  ABITS : ABITS,
+  DTM_INSTR_WIDTH : DTM_INSTR_WIDTH,
+  TRIG_SUPPORTED : TRIG_SUPPORTED
 };

docs/debug/README.md

@@ -0,0 +1,124 @@
+# Wally Debug Support
+
+This repository documents debug support for **Wally**, an open-source RISC-V processor platform. The goal of this effort is to support the RISC-V Debug Specification while enabling reliable debugging in both simulation and hardware environments. Wally integrates debug functionality compatible with OpenOCD, Spike remote bitbang simulation, and physical JTAG debug adapters.
+
+## OpenOCD for RISC-V
+
+This repository uses a separate fork of OpenOCD maintained by the RISC-V
+community, available at:
+```
+https://github.com/riscv/riscv-openocd
+```
+## Installation
+
+OpenOCD for RISC-V is installed as part of the Wally toolchain. To install,
+run the provided installation script:
+```bash
+$RISCV/bin/wally-tool-chain-install.sh
+```
+
+This script will automatically download, build, and install `riscv-openocd`
+along with the rest of the Wally toolchain components. The `$RISCV` environment
+variable should be set per `setup.sh` to your toolchain installation directory
+before running the script.
+
+### Why a Separate Fork?
+
+The official OpenOCD mainline was slow to merge RISC-V support, so the
+RISC-V community (primarily SiFive) maintained an independent fork to track
+the evolving RISC-V debug specification. Key reasons the fork exists:
+
+- **Evolving debug spec** — the RISC-V External Debug Support specification
+  went through significant revisions (0.11 → 0.13 → 1.0) while hardware was
+  already being shipped, requiring frequent implementation updates that
+  mainline OpenOCD could not absorb quickly enough
+- **Hardware availability** — SiFive and others were shipping silicon that
+  needed a working debugger before upstream review cycles could complete
+- **Slow upstream process** — mainline OpenOCD has a small maintainer team
+  and large feature sets take considerable time to review and merge
+
+RISC-V support has since been progressively upstreamed into mainline OpenOCD,
+so the gap between the two has narrowed. However, `riscv-openocd` may still
+carry newer debug spec features or bug fixes ahead of mainline.
+
+### Key Components
+
+**DTM (Debug Transport Module)** — sits between JTAG and the debug module.
+It exposes a small set of JTAG registers (`dtmcs`, `dmi`) that OpenOCD uses
+to issue DMI transactions. The DTM handles the clock domain crossing between
+the JTAG TCK domain and the core's system clock domain.
+
+**DMI (Debug Module Interface)** — a simple address/data/op bus. OpenOCD
+reads and writes DMI registers to control the debug module. Key registers
+include `dmcontrol` (halt/resume), `dmstatus` (hart state), `abstractcs`
+(abstract command control), `data0`/`data1` (data exchange), and
+`progbuf0`–`progbufN` (program buffer for executing arbitrary instructions).
+
+**Debug Module (DM)** — the on-chip hardware block that implements the debug
+spec. It can:
+- Halt and resume harts
+- Reset harts or the whole system
+- Execute abstract commands (read/write GPRs and CSRs directly)
+- Execute arbitrary instructions via the Program Buffer
+- Trigger hardware breakpoints via the Trigger Module
+
+**Program Buffer** — a small instruction memory (typically 2–16 instructions)
+that the debug module can fill with arbitrary RISC-V instructions and execute
+on the halted hart. This is the mechanism used to access Debug Mode-only CSRs
+(`dcsr`, `dscratch0`, `dscratch1`) and to perform memory access, since those
+CSRs are only accessible when the hart is in Debug Mode.
+
+**Trigger Module** — a set of hardware comparators that can fire on
+instruction addresses (breakpoints) or data addresses/values (watchpoints),
+causing the hart to enter Debug Mode without software intervention. Configured
+via the `tselect`, `tdata1`, and `tdata2` CSRs from M-mode.
+
+
+## Supported RISC-V Debug Specification
+
+Wally currently targets:
+
+**RISC-V Debug Specification — Version 1.0 (Revised 2025-02-21)**
+
+Development continues toward expanded functionality and improved
+tool interoperability.
+
+---
+
+## Note on Spike Debug Compatibility
+
+The current Wally debug implementation does **not** include an initial Debug Module *program buffer* (`progbufsize = 0`). While this is allowed by the RISC-V Debug Specification (which permits implementations to rely on abstract register access instead of a program buffer), some debugger workflows assume program-buffer execution is available.
+
+A recent Spike update (https://github.com/riscv-software-src/riscv-isa-sim/commit/5397899bb9eddba8c2f87d7d62e6303629ebed90) introduced stricter debug checks, including an assertion (around line 122 of riscv/debug_module.cc) that may trigger when debugging a target that does not implement a program buffer.
+
+As a result, users may observe assertion failures or unexpected debugger behavior when using newer versions of Spike together with Wally debug.
+
+This limitation is temporary. Future Wally debug revisions will include program buffer support, improving compatibility with Spike, OpenOCD, and standard RISC-V debug workflows.
+
+---
+
+## OpenOCD udev Rules Installation (Linux)
+
+USB debug adapters typically require root privileges. Installing the OpenOCD udev rules allows OpenOCD to access supported debug probes without using `sudo`.
+
+The rules file is provided with OpenOCD:
+
+```
+contrib/60-openocd.rules
+```
+
+Install it with:
+
+```bash
+sudo cp openocd-code/contrib/60-openocd.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+After installation, unplug and reconnect the debug adapter.  You may also need to log out and back in if group permissions change.
+
+OpenOCD should then run normally as a user as an example here:
+
+```bash
+openocd -f tests/debug/openocd.cfg
+```