Skip to content

feat: add riscv debugger support #1650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jvlegod wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

feat: add riscv debugger support #1650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88ca4d4
feat: add riscv gdb support
Jvlegod Aug 3, 2026
493e1f0
fix: flush gdb tb cache
Jvlegod Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion qiling/debugger/gdb/gdb.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,7 @@ def handle_qmark(subcmd: str) -> Reply:
from unicorn.arm64_const import UC_ARM64_REG_X29
from unicorn.mips_const import UC_MIPS_REG_INVALID
from unicorn.ppc_const import UC_PPC_REG_31
from unicorn.riscv_const import UC_RISCV_REG_S0

arch_uc_bp = {
QL_ARCH.X86 : UC_X86_REG_EBP,
Expand All @@ -193,7 +194,9 @@ def handle_qmark(subcmd: str) -> Reply:
QL_ARCH.MIPS : UC_MIPS_REG_INVALID, # skipped
QL_ARCH.A8086 : UC_X86_REG_EBP,
QL_ARCH.CORTEX_M : UC_ARM_REG_R11,
QL_ARCH.PPC : UC_PPC_REG_31
QL_ARCH.PPC : UC_PPC_REG_31,
QL_ARCH.RISCV : UC_RISCV_REG_S0,
QL_ARCH.RISCV64 : UC_RISCV_REG_S0
}[self.ql.arch.type]

def __get_reg_idx(ucreg: int) -> int:
Expand Down
17 changes: 17 additions & 0 deletions qiling/debugger/gdb/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,12 @@ def __init__(self, ql: Qiling, entry_point: int, exit_point: int):
self.exit_point = exit_point
self.swbp = set()
self.last_bp = None
self._need_flush_tb = False

def __entry_point_hook(ql: Qiling):
ql.hook_del(ep_hret)
ql.hook_code(self.dbg_hook)
self._need_flush_tb = True

ql.log.info(f'{PROMPT} stopped at entry point: {ql.arch.regs.arch_pc:#x}')
ql.stop()
Expand All @@ -32,6 +34,13 @@ def __entry_point_hook(ql: Qiling):
# that hook will be used to set up the breakpoint handling hook
ep_hret = ql.hook_address(__entry_point_hook, entry_point)

def flush_tb(self):
"""Flush Unicorn translation blocks after GDB hook or breakpoint updates."""
flush_tb = getattr(self.ql.uc, 'ctl_flush_tb', None)

if flush_tb is not None:
flush_tb()

def dbg_hook(self, ql: Qiling, address: int, size: int):
if getattr(ql.arch, 'is_thumb', False):
address |= 1
Expand All @@ -56,6 +65,8 @@ def bp_insert(self, addr: int, size: int):
for bp in targets:
self.swbp.add(bp)

self._need_flush_tb = True

self.ql.log.info(f'{PROMPT} breakpoint added at {addr:#x}')

return True
Expand All @@ -69,6 +80,8 @@ def bp_remove(self, addr: int, size: int) -> bool:
for bp in targets:
self.swbp.remove(bp)

self._need_flush_tb = True

self.ql.log.info(f'{PROMPT} breakpoint removed from {addr:#x}')

return True
Expand All @@ -80,6 +93,10 @@ def resume_emu(self, address: Optional[int] = None, steps: int = 0):
if getattr(self.ql.arch, 'is_thumb', False):
address |= 0b1

if self._need_flush_tb:
self.flush_tb()
self._need_flush_tb = False

op = f'stepping {steps} instructions' if steps else 'resuming'
self.ql.log.info(f'{PROMPT} {op} from {address:#x}')

Expand Down
47 changes: 47 additions & 0 deletions qiling/debugger/gdb/xml/riscv/riscv-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!-- Register numbers are hard-coded in order to maintain backward
compatibility with older versions of tools that didn't use xml
register descriptions. -->

<!DOCTYPE feature SYSTEM "gdb-target.dtd">
<feature name="org.gnu.gdb.riscv.cpu">
<reg name="zero" bitsize="32" type="int" regnum="0"/>
<reg name="ra" bitsize="32" type="code_ptr"/>
<reg name="sp" bitsize="32" type="data_ptr"/>
<reg name="gp" bitsize="32" type="data_ptr"/>
<reg name="tp" bitsize="32" type="data_ptr"/>
<reg name="t0" bitsize="32" type="int"/>
<reg name="t1" bitsize="32" type="int"/>
<reg name="t2" bitsize="32" type="int"/>
<reg name="fp" bitsize="32" type="data_ptr"/>
<reg name="s1" bitsize="32" type="int"/>
<reg name="a0" bitsize="32" type="int"/>
<reg name="a1" bitsize="32" type="int"/>
<reg name="a2" bitsize="32" type="int"/>
<reg name="a3" bitsize="32" type="int"/>
<reg name="a4" bitsize="32" type="int"/>
<reg name="a5" bitsize="32" type="int"/>
<reg name="a6" bitsize="32" type="int"/>
<reg name="a7" bitsize="32" type="int"/>
<reg name="s2" bitsize="32" type="int"/>
<reg name="s3" bitsize="32" type="int"/>
<reg name="s4" bitsize="32" type="int"/>
<reg name="s5" bitsize="32" type="int"/>
<reg name="s6" bitsize="32" type="int"/>
<reg name="s7" bitsize="32" type="int"/>
<reg name="s8" bitsize="32" type="int"/>
<reg name="s9" bitsize="32" type="int"/>
<reg name="s10" bitsize="32" type="int"/>
<reg name="s11" bitsize="32" type="int"/>
<reg name="t3" bitsize="32" type="int"/>
<reg name="t4" bitsize="32" type="int"/>
<reg name="t5" bitsize="32" type="int"/>
<reg name="t6" bitsize="32" type="int"/>
<reg name="pc" bitsize="32" type="code_ptr"/>
</feature>
54 changes: 54 additions & 0 deletions qiling/debugger/gdb/xml/riscv/riscv-fpu.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!-- Register numbers are hard-coded in order to maintain backward
compatibility with older versions of tools that didn't use xml
register descriptions. -->

<!DOCTYPE feature SYSTEM "gdb-target.dtd">
<feature name="org.gnu.gdb.riscv.fpu">

<union id="riscv_double">
<field name="float" type="ieee_single"/>
<field name="double" type="ieee_double"/>
</union>

<reg name="ft0" bitsize="64" type="riscv_double" regnum="33"/>
<reg name="ft1" bitsize="64" type="riscv_double"/>
<reg name="ft2" bitsize="64" type="riscv_double"/>
<reg name="ft3" bitsize="64" type="riscv_double"/>
<reg name="ft4" bitsize="64" type="riscv_double"/>
<reg name="ft5" bitsize="64" type="riscv_double"/>
<reg name="ft6" bitsize="64" type="riscv_double"/>
<reg name="ft7" bitsize="64" type="riscv_double"/>
<reg name="fs0" bitsize="64" type="riscv_double"/>
<reg name="fs1" bitsize="64" type="riscv_double"/>
<reg name="fa0" bitsize="64" type="riscv_double"/>
<reg name="fa1" bitsize="64" type="riscv_double"/>
<reg name="fa2" bitsize="64" type="riscv_double"/>
<reg name="fa3" bitsize="64" type="riscv_double"/>
<reg name="fa4" bitsize="64" type="riscv_double"/>
<reg name="fa5" bitsize="64" type="riscv_double"/>
<reg name="fa6" bitsize="64" type="riscv_double"/>
<reg name="fa7" bitsize="64" type="riscv_double"/>
<reg name="fs2" bitsize="64" type="riscv_double"/>
<reg name="fs3" bitsize="64" type="riscv_double"/>
<reg name="fs4" bitsize="64" type="riscv_double"/>
<reg name="fs5" bitsize="64" type="riscv_double"/>
<reg name="fs6" bitsize="64" type="riscv_double"/>
<reg name="fs7" bitsize="64" type="riscv_double"/>
<reg name="fs8" bitsize="64" type="riscv_double"/>
<reg name="fs9" bitsize="64" type="riscv_double"/>
<reg name="fs10" bitsize="64" type="riscv_double"/>
<reg name="fs11" bitsize="64" type="riscv_double"/>
<reg name="ft8" bitsize="64" type="riscv_double"/>
<reg name="ft9" bitsize="64" type="riscv_double"/>
<reg name="ft10" bitsize="64" type="riscv_double"/>
<reg name="ft11" bitsize="64" type="riscv_double"/>

<reg name="fcsr" bitsize="32" type="int" regnum="68"/>
</feature>
15 changes: 15 additions & 0 deletions qiling/debugger/gdb/xml/riscv/target.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!DOCTYPE target SYSTEM "gdb-target.dtd">
<target xmlns:xi="http://www.w3.org/2001/XInclude">
<architecture>riscv:rv32</architecture>
<osabi>GNU/Linux</osabi>

<xi:include href="riscv-core.xml"/>
<xi:include href="riscv-fpu.xml"/>
</target>
47 changes: 47 additions & 0 deletions qiling/debugger/gdb/xml/riscv64/riscv64-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!-- Register numbers are hard-coded in order to maintain backward
compatibility with older versions of tools that didn't use xml
register descriptions. -->

<!DOCTYPE feature SYSTEM "gdb-target.dtd">
<feature name="org.gnu.gdb.riscv.cpu">
<reg name="zero" bitsize="64" type="int" regnum="0"/>
<reg name="ra" bitsize="64" type="code_ptr"/>
<reg name="sp" bitsize="64" type="data_ptr"/>
<reg name="gp" bitsize="64" type="data_ptr"/>
<reg name="tp" bitsize="64" type="data_ptr"/>
<reg name="t0" bitsize="64" type="int"/>
<reg name="t1" bitsize="64" type="int"/>
<reg name="t2" bitsize="64" type="int"/>
<reg name="fp" bitsize="64" type="data_ptr"/>
<reg name="s1" bitsize="64" type="int"/>
<reg name="a0" bitsize="64" type="int"/>
<reg name="a1" bitsize="64" type="int"/>
<reg name="a2" bitsize="64" type="int"/>
<reg name="a3" bitsize="64" type="int"/>
<reg name="a4" bitsize="64" type="int"/>
<reg name="a5" bitsize="64" type="int"/>
<reg name="a6" bitsize="64" type="int"/>
<reg name="a7" bitsize="64" type="int"/>
<reg name="s2" bitsize="64" type="int"/>
<reg name="s3" bitsize="64" type="int"/>
<reg name="s4" bitsize="64" type="int"/>
<reg name="s5" bitsize="64" type="int"/>
<reg name="s6" bitsize="64" type="int"/>
<reg name="s7" bitsize="64" type="int"/>
<reg name="s8" bitsize="64" type="int"/>
<reg name="s9" bitsize="64" type="int"/>
<reg name="s10" bitsize="64" type="int"/>
<reg name="s11" bitsize="64" type="int"/>
<reg name="t3" bitsize="64" type="int"/>
<reg name="t4" bitsize="64" type="int"/>
<reg name="t5" bitsize="64" type="int"/>
<reg name="t6" bitsize="64" type="int"/>
<reg name="pc" bitsize="64" type="code_ptr"/>
</feature>
54 changes: 54 additions & 0 deletions qiling/debugger/gdb/xml/riscv64/riscv64-fpu.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!-- Register numbers are hard-coded in order to maintain backward
compatibility with older versions of tools that didn't use xml
register descriptions. -->

<!DOCTYPE feature SYSTEM "gdb-target.dtd">
<feature name="org.gnu.gdb.riscv.fpu">

<union id="riscv_double">
<field name="float" type="ieee_single"/>
<field name="double" type="ieee_double"/>
</union>

<reg name="ft0" bitsize="64" type="riscv_double" regnum="33"/>
<reg name="ft1" bitsize="64" type="riscv_double"/>
<reg name="ft2" bitsize="64" type="riscv_double"/>
<reg name="ft3" bitsize="64" type="riscv_double"/>
<reg name="ft4" bitsize="64" type="riscv_double"/>
<reg name="ft5" bitsize="64" type="riscv_double"/>
<reg name="ft6" bitsize="64" type="riscv_double"/>
<reg name="ft7" bitsize="64" type="riscv_double"/>
<reg name="fs0" bitsize="64" type="riscv_double"/>
<reg name="fs1" bitsize="64" type="riscv_double"/>
<reg name="fa0" bitsize="64" type="riscv_double"/>
<reg name="fa1" bitsize="64" type="riscv_double"/>
<reg name="fa2" bitsize="64" type="riscv_double"/>
<reg name="fa3" bitsize="64" type="riscv_double"/>
<reg name="fa4" bitsize="64" type="riscv_double"/>
<reg name="fa5" bitsize="64" type="riscv_double"/>
<reg name="fa6" bitsize="64" type="riscv_double"/>
<reg name="fa7" bitsize="64" type="riscv_double"/>
<reg name="fs2" bitsize="64" type="riscv_double"/>
<reg name="fs3" bitsize="64" type="riscv_double"/>
<reg name="fs4" bitsize="64" type="riscv_double"/>
<reg name="fs5" bitsize="64" type="riscv_double"/>
<reg name="fs6" bitsize="64" type="riscv_double"/>
<reg name="fs7" bitsize="64" type="riscv_double"/>
<reg name="fs8" bitsize="64" type="riscv_double"/>
<reg name="fs9" bitsize="64" type="riscv_double"/>
<reg name="fs10" bitsize="64" type="riscv_double"/>
<reg name="fs11" bitsize="64" type="riscv_double"/>
<reg name="ft8" bitsize="64" type="riscv_double"/>
<reg name="ft9" bitsize="64" type="riscv_double"/>
<reg name="ft10" bitsize="64" type="riscv_double"/>
<reg name="ft11" bitsize="64" type="riscv_double"/>

<reg name="fcsr" bitsize="32" type="int" regnum="68"/>
</feature>
15 changes: 15 additions & 0 deletions qiling/debugger/gdb/xml/riscv64/target.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<?xml version="1.0"?>
<!-- Copyright (C) 2018-2025 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. -->

<!DOCTYPE target SYSTEM "gdb-target.dtd">
<target xmlns:xi="http://www.w3.org/2001/XInclude">
<architecture>riscv:rv64</architecture>
<osabi>GNU/Linux</osabi>

<xi:include href="riscv64-core.xml"/>
<xi:include href="riscv64-fpu.xml"/>
</target>
10 changes: 9 additions & 1 deletion qiling/debugger/gdb/xmlregs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@
reg_map as ppc_regs
)

from qiling.arch.riscv_const import (
reg_csr_map as riscv_regs_csr,
reg_float_map as riscv_regs_float,
reg_map as riscv_regs
)

from qiling.const import QL_ARCH, QL_OS

RegEntry = Tuple[Optional[int], int, int]
Expand Down Expand Up @@ -147,7 +153,9 @@ def __load_regsmap(archtype: QL_ARCH, xmltree: ElementTree.ElementTree) -> Seque
QL_ARCH.CORTEX_M: dict(**cortex_m_regs),
QL_ARCH.ARM64: dict(**arm64_regs, **arm64_regs_v, **arm64_reg_map_fp),
QL_ARCH.MIPS: dict(**mips_regs_gpr),
QL_ARCH.PPC: dict(**ppc_regs)
QL_ARCH.PPC: dict(**ppc_regs),
QL_ARCH.RISCV: dict(**riscv_regs, **riscv_regs_float, **riscv_regs_csr),
QL_ARCH.RISCV64: dict(**riscv_regs, **riscv_regs_float, **riscv_regs_csr)
}[archtype]

regsinfo = sorted(QlGdbFeatures.__walk_xml_regs(xmltree))
Expand Down