Debug Module

Overview

The debug module implements a subset of the RISC-V Debug Specification, providing external debug support for the Kelvin core. It allows a debugger to halt, resume, and single-step the core, as well as read and write core registers and memory.

Architecture

The debug module is a standalone module that connects to the core via a dedicated debug interface. It communicates with an external debugger through a simple request/response protocol.

The following diagram illustrates the high-level architecture of the debug module:

Interfaces

The following table describes the inputs and outputs of the debug module:

Name	Direction	Type	Width	Description
ext.req	Input	Decoupled		External debugger request.
↳ valid		Bool	1	The request is valid.
↳ ready		Bool	1	The module is ready for a request.
↳ bits		DebugModuleReqIO		The request payload.
↳ address		UInt	32	The address of the register to access.
↳ data		UInt	32	The data to write.
↳ op		DmReqOp	2	The operation to perform (NOP, READ, WRITE).
ext.rsp	Output	Decoupled		External debugger response.
↳ valid		Bool	1	The response is valid.
↳ ready		Bool	1	The debugger is ready for a response.
↳ bits		DebugModuleRspIO		The response payload.
↳ data		UInt	32	The data read from the register.
↳ op		DmRspOp	2	The result of the operation (SUCCESS, FAILED, BUSY).
csr	Output	Valid		CSR command.
↳ valid		Bool	1	The command is valid.
↳ bits		CsrCmd		The command payload.
csr_rd	Input	Valid		CSR read data.
↳ valid		Bool	1	The read data is valid.
↳ bits		UInt	32	The read data.
scalar_rd	Output	Decoupled		Scalar register file write command.
↳ valid		Bool	1	The write command is valid.
↳ ready		Bool	1	The register file is ready.
↳ bits		RegfileWriteDataIO		The write command payload.
scalar_rs		Bundle		Scalar register file read interface.
↳ idx	Output	UInt	5	Scalar register file read address.
↳ data	Input	UInt	32	Scalar register file read data.
float_rd	Output	Valid		Floating-point register file write command.
↳ valid		Bool	1	The write command is valid.
↳ bits		FRegfileWrite		The write command payload.
float_rs		Bundle		Floating-point register file read interface.
↳ valid	Input	Bool	1	Floating-point register file read valid.
↳ addr	Input	UInt	5	Floating-point register file read address.
↳ data	Input	UInt	32	Floating-point register file read data.
haltreq	Output	Bool	1	Request to halt the core.
resumereq	Output	Bool	1	Request to resume the core.
resumeack	Input	Bool	1	Core has resumed.
ndmreset	Output	Bool	1	Reset the debug module.
halted	Input	Bool	1	Core is halted.
running	Input	Bool	1	Core is running.
havereset	Input	Bool	1	Core has been reset.

Command Protocol

An external debugger communicates with the debug module by reading and writing its internal registers. The ext.req and ext.rsp interfaces are used for this purpose.

To issue a command, the debugger sends a request on the ext.req interface. The address field specifies the register to access, and the op field specifies the operation (read or write). For write operations, the data field contains the value to write.

The debug module responds on the ext.rsp interface. The op field indicates the status of the operation, and for read operations, the data field contains the value read from the register.

All debug operations, including halting the core, resuming the core, and executing abstract commands, are performed by reading and writing the debug module's registers via this protocol.

Registers

The debug module implements a set of registers that are accessible to an external debugger. These registers are used to control and monitor the core.

The following table lists the debug module registers:

Address	Name	Description
0x04	data0	Data register for abstract commands.
0x10	dmcontrol	Debug module control register.
0x11	dmstatus	Debug module status register.
0x12	hartinfo	Hart information register.
0x16	abstractcs	Abstract command status register.
0x17	command	Abstract command register.

dmcontrol (0x10)

The dmcontrol register is used to control the debug module and the core.

Bits	Name	Description
31	haltreq	Request to halt the core.
30	resumereq	Request to resume the core.
29:2	reserved	Reserved for future use.
1	ndmreset	Reset the debug module.
0	dmactive	Activate the debug module.

dmstatus (0x11)

The dmstatus register provides the status of the debug module and the core.

Bits	Name	Description
11	allrunning	All harts are running.
10	anyrunning	Any hart is running.
9	allhalted	All harts are halted.
8	anyhalted	Any hart is halted.
7:4	reserved	Reserved for future use.
3:0	version	Debug module version.

abstractcs (0x16)

The abstractcs register provides the status of abstract commands.

Bits	Name	Description
12	busy	The abstract command is currently executing.
11	reserved	Reserved for future use.
10:8	cmderr	Abstract command error code.
7:0	reserved	Reserved for future use.

command (0x17)

The command register is used to issue abstract commands to the core.

Bits	Name	Description
31:24	cmdtype	The type of abstract command.
23:0	control	Command-specific control information.

Abstract Commands

Abstract commands are used to perform complex operations on the core, such as reading and writing registers.

To issue an abstract command, the debugger writes to the command register. The cmdtype field specifies the type of command, and the control field contains command-specific information.

Access Register Command (cmdtype=0)

The Access Register command is used to read and write core registers.

The control field for the Access Register command is formatted as follows:

Bits	Name	Description
16	write	1 for a write, 0 for a read.
15:0	regno	The number of the register to access.

The register numbers are defined as follows:

• 0x0000-0x0FFF: CSRs
• 0x1000-0x101F: Scalar GPRs
• 0x1020-0x103F: Floating-point GPRs

Command Examples

Reading a GPR (a0)

1. Issue the read command: Write to the command register (address 0x17) with the following value:
   • cmdtype (bits 31:24): 0x0 (Access Register)
   • write (bit 16): 0 (read)
   • regno (bits 15:0): 0x100A (for a0)
2. Wait for completion: Poll the abstractcs register (address 0x16) until the busy bit (bit 12) is cleared.
3. Check for errors: Read the abstractcs register again and check that the cmderr field (bits 10:8) is 0.
4. Read the result: If there are no errors, read the value of GPR a0 from the data0 register (address 0x04).

Writing a GPR (a0)

1. Write the value: Write the desired value for GPR a0 to the data0 register (address 0x04).
2. Issue the write command: Write to the command register (address 0x17) with the following value:
   • cmdtype (bits 31:24): 0x0 (Access Register)
   • write (bit 16): 1 (write)
   • regno (bits 15:0): 0x100A (for a0)
3. Wait for completion: Poll the abstractcs register (address 0x16) until the busy bit (bit 12) is cleared.
4. Check for errors: Read the abstractcs register again and check that the cmderr field (bits 10:8) is 0.