riscv-mcu-debug

Name: riscv-mcu-debug
Author: easyzoom

22stars2forks

How to install riscv-mcu-debug?

easyzoom/aix-skills/riscv-mcu-debug

$npx -y skills add easyzoom/aix-skills --skill riscv-mcu-debug

Installs into the current project.

Summary

Use when debugging RISC-V microcontrollers, bare-metal firmware, RTOS bring-up, OpenOCD or GDB sessions, traps, CSRs, startup code, or flashing failures

Files · 1

View on GitHub

SKILL.md

1	# RISC-V MCU Debug
2
3	## Overview
4
5	Use this skill to debug RISC-V MCU firmware systematically. Identify the exact core, SoC, debug module, toolchain, memory map, and trap state before changing startup code, linker scripts, flash settings, or machine-mode configuration.
6
7	## When To Use
8
9	Use this skill when:
10
11	- The target is a RISC-V MCU or bare-metal RISC-V SoC.
12	- The user mentions OpenOCD, GDB, JTAG, RISC-V debug module, `mstatus`, `mcause`, `mepc`, `mtvec`, trap handlers, startup code, or linker scripts.
13	- Firmware cannot flash, stops before `main`, traps, hangs, or has no UART/log output.
14
15	Do not use this skill for Cortex-M, 8051, embedded Linux application debugging, or general C code review without target evidence.
16
17	## First Questions
18
19	Ask for:
20
21	- Exact chip, board, and core if known, such as RV32IMAC, RV32E, RV64, F/D extension, or vendor core name.
22	- Toolchain: GCC, LLVM, vendor IDE, Zephyr, RT-Thread, or bare metal.
23	- Debug path: OpenOCD, vendor GDB server, J-Link, WCH-Link, onboard probe, or UART bootloader.
24	- Current symptom: cannot connect, cannot flash, no boot, trap, hang, no log, or peripheral failure.
25	- Available artifacts: ELF, MAP, linker script, startup file, OpenOCD config, UART log, trap dump, or GDB transcript.
26
27	## Workflow
28
29	1. Confirm the target profile.
30	RISC-V MCU behavior depends on XLEN, extensions, privilege mode, vendor CSRs, debug module, and memory map.
31
32	1. Classify the failure phase.
33	Use connect, flash, reset/startup, trap, runtime hang, peripheral bring-up, or RTOS scheduling.
34
35	1. Establish a non-destructive debug session.
36	Prefer halt/reset-halt and symbol loading before flash erase or startup rewrites.
37
38	1. Collect trap and reset evidence.
39	Record `pc`, `sp`, `mstatus`, `mcause`, `mepc`, `mtval`, `mtvec`, and key memory addresses.
40
41	1. Check linker and startup alignment.
42	Confirm reset address, vector/trap base, RAM origin, stack top, `.data` copy, `.bss` zeroing, and `main` call path.
43
44	1. Ask before risky operations.
45	Mass erase, option bytes, boot mode, security locks, and vendor flash config changes require explicit approval.
46
47	## OpenOCD And GDB Checks
48
49	Useful patterns:
50
51	```bash
52	openocd -f interface/<probe>.cfg -f target/<target>.cfg
53	riscv64-unknown-elf-gdb build/firmware.elf
54	riscv-none-elf-gdb build/firmware.elf
55	```
56
57	GDB baseline:
58
59	```gdb
60	target extended-remote :3333
61	monitor reset halt
62	info registers
63	p/x $pc
64	p/x $sp
65	p/x $mcause
66	p/x $mepc
67	p/x $mtval
68	p/x $mtvec
69	bt
70	```
71
72	Check:
73
74	- `pc` points to a valid executable region.
75	- `sp` points inside RAM and is aligned.
76	- `mtvec` points to the intended trap handler.
77	- `mepc` maps to source or disassembly.
78	- OpenOCD target config matches the exact chip or debug module.
79
80	## Trap Debugging
81
82	When a trap occurs:
83
84	1. Preserve state before reset.
85	1. Read `mcause`, `mepc`, `mtval`, `mstatus`, and `mtvec`.
86	1. Decode whether the cause is interrupt or exception.
87	1. Map `mepc` to a symbol and instruction.
88	1. Check whether `mtval` contains a bad address or instruction.
89
90	Common causes:
91
92	- Illegal instruction due to wrong ISA flags, such as compiling for `rv32imac` but running on a core without compressed instructions.
93	- Misaligned access or unsupported unaligned loads/stores.
94	- Executing from erased flash or wrong boot address.
95	- Stack pointer outside RAM.
96	- Trap vector not initialized or not aligned as required.
97	- Accessing peripheral addresses before clocks or bus bridges are ready.
98	- M-mode interrupt enable or PLIC/CLIC setup mismatch.
99
100	## Startup And Linker Checks
101
102	If firmware fails before `main()`:
103
104	- Confirm linker script flash/RAM origins match the exact SoC.
105	- Confirm reset entry address agrees with boot ROM or flash mapping.
106	- Confirm stack top is valid and aligned.
107	- Confirm global pointer `gp` and small data sections are initialized if used.
108	- Confirm `.data` and `.bss` initialization.
109	- Confirm trap handler is installed before enabling interrupts.
110	- Confirm compiler ABI, ISA string, and startup assembly agree.
111
112	## Flashing Checks
113
114	If flashing fails:
115
116	- Separate connect, erase, program, and verify failures.
117	- Check probe wiring, target voltage, reset, and JTAG/SWD-equivalent pin mux.
118	- Lower adapter speed.
119	- Confirm flash algorithm and target config match the chip.
120	- Ask before mass erase or security unlock.
121
122	## Verification
123
124	Before claiming progress:
125
126	- State chip/core, XLEN, ISA string if known, probe, debug server, and toolchain.
127	- Confirm whether GDB can halt and read registers.
128	- Report `pc`, `sp`, `mcause`, `mepc`, `mtval`, and `mtvec` when trap-related.
129	- Confirm flash erase/program/verify status separately if flashing was attempted.
130	- List destructive actions skipped or awaiting approval.
131
132	## Common Failures
133
134	- Using the wrong `-march` or `-mabi` for the actual core.
135	- Assuming all RISC-V MCUs have the same interrupt controll

People who liked this also viewed

6 picks

Type

azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026472k1.3k
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026197k259k
safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026161k507
explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026161k507
minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026161k507
insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 202618k31

riscv-mcu-debug

22stars2forks

View on GitHub

How to install riscv-mcu-debug?

easyzoom/aix-skills/riscv-mcu-debug

$npx -y skills add easyzoom/aix-skills --skill riscv-mcu-debug

Installs into the current project.

Summary

Use when debugging RISC-V microcontrollers, bare-metal firmware, RTOS bring-up, OpenOCD or GDB sessions, traps, CSRs, startup code, or flashing failures

Files · 1

View on GitHub

SKILL.md

1	# RISC-V MCU Debug
2
3	## Overview
4
5	Use this skill to debug RISC-V MCU firmware systematically. Identify the exact core, SoC, debug module, toolchain, memory map, and trap state before changing startup code, linker scripts, flash settings, or machine-mode configuration.
6
7	## When To Use
8
9	Use this skill when:
10
11	- The target is a RISC-V MCU or bare-metal RISC-V SoC.
12	- The user mentions OpenOCD, GDB, JTAG, RISC-V debug module, `mstatus`, `mcause`, `mepc`, `mtvec`, trap handlers, startup code, or linker scripts.
13	- Firmware cannot flash, stops before `main`, traps, hangs, or has no UART/log output.
14
15	Do not use this skill for Cortex-M, 8051, embedded Linux application debugging, or general C code review without target evidence.
16
17	## First Questions
18
19	Ask for:
20
21	- Exact chip, board, and core if known, such as RV32IMAC, RV32E, RV64, F/D extension, or vendor core name.
22	- Toolchain: GCC, LLVM, vendor IDE, Zephyr, RT-Thread, or bare metal.
23	- Debug path: OpenOCD, vendor GDB server, J-Link, WCH-Link, onboard probe, or UART bootloader.
24	- Current symptom: cannot connect, cannot flash, no boot, trap, hang, no log, or peripheral failure.
25	- Available artifacts: ELF, MAP, linker script, startup file, OpenOCD config, UART log, trap dump, or GDB transcript.
26
27	## Workflow
28
29	1. Confirm the target profile.
30	RISC-V MCU behavior depends on XLEN, extensions, privilege mode, vendor CSRs, debug module, and memory map.
31
32	1. Classify the failure phase.
33	Use connect, flash, reset/startup, trap, runtime hang, peripheral bring-up, or RTOS scheduling.
34
35	1. Establish a non-destructive debug session.
36	Prefer halt/reset-halt and symbol loading before flash erase or startup rewrites.
37
38	1. Collect trap and reset evidence.
39	Record `pc`, `sp`, `mstatus`, `mcause`, `mepc`, `mtval`, `mtvec`, and key memory addresses.
40
41	1. Check linker and startup alignment.
42	Confirm reset address, vector/trap base, RAM origin, stack top, `.data` copy, `.bss` zeroing, and `main` call path.
43
44	1. Ask before risky operations.
45	Mass erase, option bytes, boot mode, security locks, and vendor flash config changes require explicit approval.
46
47	## OpenOCD And GDB Checks
48
49	Useful patterns:
50
51	```bash
52	openocd -f interface/<probe>.cfg -f target/<target>.cfg
53	riscv64-unknown-elf-gdb build/firmware.elf
54	riscv-none-elf-gdb build/firmware.elf
55	```
56
57	GDB baseline:
58
59	```gdb
60	target extended-remote :3333
61	monitor reset halt
62	info registers
63	p/x $pc
64	p/x $sp
65	p/x $mcause
66	p/x $mepc
67	p/x $mtval
68	p/x $mtvec
69	bt
70	```
71
72	Check:
73
74	- `pc` points to a valid executable region.
75	- `sp` points inside RAM and is aligned.
76	- `mtvec` points to the intended trap handler.
77	- `mepc` maps to source or disassembly.
78	- OpenOCD target config matches the exact chip or debug module.
79
80	## Trap Debugging
81
82	When a trap occurs:
83
84	1. Preserve state before reset.
85	1. Read `mcause`, `mepc`, `mtval`, `mstatus`, and `mtvec`.
86	1. Decode whether the cause is interrupt or exception.
87	1. Map `mepc` to a symbol and instruction.
88	1. Check whether `mtval` contains a bad address or instruction.
89
90	Common causes:
91
92	- Illegal instruction due to wrong ISA flags, such as compiling for `rv32imac` but running on a core without compressed instructions.
93	- Misaligned access or unsupported unaligned loads/stores.
94	- Executing from erased flash or wrong boot address.
95	- Stack pointer outside RAM.
96	- Trap vector not initialized or not aligned as required.
97	- Accessing peripheral addresses before clocks or bus bridges are ready.
98	- M-mode interrupt enable or PLIC/CLIC setup mismatch.
99
100	## Startup And Linker Checks
101
102	If firmware fails before `main()`:
103
104	- Confirm linker script flash/RAM origins match the exact SoC.
105	- Confirm reset entry address agrees with boot ROM or flash mapping.
106	- Confirm stack top is valid and aligned.
107	- Confirm global pointer `gp` and small data sections are initialized if used.
108	- Confirm `.data` and `.bss` initialization.
109	- Confirm trap handler is installed before enabling interrupts.
110	- Confirm compiler ABI, ISA string, and startup assembly agree.
111
112	## Flashing Checks
113
114	If flashing fails:
115
116	- Separate connect, erase, program, and verify failures.
117	- Check probe wiring, target voltage, reset, and JTAG/SWD-equivalent pin mux.
118	- Lower adapter speed.
119	- Confirm flash algorithm and target config match the chip.
120	- Ask before mass erase or security unlock.
121
122	## Verification
123
124	Before claiming progress:
125
126	- State chip/core, XLEN, ISA string if known, probe, debug server, and toolchain.
127	- Confirm whether GDB can halt and read registers.
128	- Report `pc`, `sp`, `mcause`, `mepc`, `mtval`, and `mtvec` when trap-related.
129	- Confirm flash erase/program/verify status separately if flashing was attempted.
130	- List destructive actions skipped or awaiting approval.
131
132	## Common Failures
133
134	- Using the wrong `-march` or `-mabi` for the actual core.
135	- Assuming all RISC-V MCUs have the same interrupt controll

People who liked this also viewed

6 picks

Type