riscv / riscv-debug-spec

Working Draft of the RISC-V Debug Specification Standard

RISC-V Debug Specification

You may be looking for one of the following pre-built PDFs:

• Latest release candidate
• Latest release (This is outdated at this point, and only of historical interest.)

Build Instructions

sudo apt-get install git make python3 python3-sympy graphviz texlive-full
make

There are two other interesting make targets:

1. make debug_defines creates a C header and implementation files containing constants for addresses and fields of all the registers and abstract commands, as well as function and structures used to decode register values. An implementation of such decoder can be seen in debug_reg_printer.c/h.
2. make chisel creates scala files for DM registers and abstract commands with the same information.

Contributing

There are various ways to contribute to this spec. You can use a combination of them to get your idea across. Please note that pull requests will only be reviewed/accepted from RISC-V Foundation members.

1. Make a PR. This is the best way to deal with minor typos and edits.
2. File an issue with something that you want to know or see.
3. Discuss higher-level questions or ideas on the riscv-debug-group mailing list: https://lists.riscv.org/g/tech-debug

For More Information

Additional information can be found at https://github.com/riscv/debug-taskgroup

riscv-debug-spec's Issues

Add "read" bit as well as "write" and "execute" bits to Access Register

Currently there is no way to do a "just execute the program buffer" command. Suggest we add a "read" bit as well as "write" bit.

The alternative is that implementations can just do a "write to x0" to implement a NOP.

Clarify NDMRESET functionality

At minimum, it should NOT reset the Debug Module, it is permissible for it to do absolutely nothing (this is somewhat stated already but is not super clear)

sw_registers.txt

Hello,

I'm starting to merge my security stuff but I can't build with the latest pull.
0512f5d

I get the following error:
$ make
./registers.py --custom --definitions jtag_registers.tex.inc --cheader jtag_registers.h xml/jtag_registers.xml > jtag_registers.tex
./registers.py --custom --definitions core_registers.tex.inc --cheader core_registers.h xml/core_registers.xml > core_registers.tex
./registers.py --custom --definitions hwbp_registers.tex.inc --cheader hwbp_registers.h xml/hwbp_registers.xml > hwbp_registers.tex
./registers.py --custom --definitions dm_registers.tex.inc --cheader dm_registers.h xml/dm_registers.xml > dm_registers.tex
./registers.py --custom --definitions trace_registers.tex.inc --cheader trace_registers.h xml/trace_registers.xml > trace_registers.tex
./registers.py --custom --definitions sample_registers.tex.inc --cheader sample_registers.h xml/sample_registers.xml > sample_registers.tex
./registers.py --custom --definitions abstract_commands.tex.inc --cheader abstract_commands.h xml/abstract_commands.xml > abstract_commands.tex
make: *** No rule to make target 'sw_registers.tex', needed by 'riscv-debug-spec.pdf'. Stop.

Disallow writing DATA/PROGBUF while BUSY

The spec is unclear on whether you can write DATA and PROGBUF registers while ABSTRACTCS.busy is true. You certainly get ABSTRACTCS.cmderr=BUSY if you do, but it's not clear whether the reads/writes go through.

It's important for debuggers to know that a Previous command will complete cleanly even if the following command results in cmderr.BUSY. So we should not allow DATA/PROGBUF to be written while busy.

Resume "should" use resumereq and halt "should" use haltreq

In my opinion, the description for haltreq and resumereq is not clear enough now.
They mention that haltreq could halt the core when it's set to 1, but what happen when it is set to 0?
Unsetting haltreq actually won't make the core resume, and we need the resumereq to resume. However, this fact is not written on the spec, and we probably need to clarify that.
How does everyone think?

Hart Array Mask Register TODO

Address this TODO item.

Remove pre-exec bit

Pre-exec bit adds a lot of HW complexity without much benefit. Let's remove it.

Reset value of DMCONTROL.hartstatus

The reset value of DMCONTROL.hartstatus is '-'. What does that mean exactly, just "unknown, but meaningful"? Or does it not become valid until we start writing to CONTROL register?

"Serial_select" description bug

First thank you for working on it.

In ver 0.12, Serial_port_select is part of , but in 0.13, it is moved to .

The description in 7.11.17 is not correct now.

JTAG Connector Suggestion

Just filing this as a "TODO" we discussed in the WG meeting / mailing list but no one has taken up the task yet. There was general consensus that the connector we specify/suggest should support an optional TRST, which the current one does not.

Use SHOULD/SHALL Language

Do a cleanup pass and use language as suggested by RFC2119
(https://www.ietf.org/rfc/rfc2119.txt)

Clarification - Reference dmstatus for anynonexistent

In section 3.3, the dmstatus field anynonexistent is introduced. Suggest reference dmstatus here since it (and anynonexistent) has not been previously noted.

Config String: Abstract command or DMI Registers

Should config string be communicated via abstract command or DMI Registers. my preference is for the latter. If we really are concerned about registers, we could alias the registers to give VENDOR / VERSION ids if there is no config string (since config string has the same information)

Clarify actual current requirements on JTAG Header

Right now there are statements about the current supply the JTAG header must supply. NOt sure we are ready to make such a strong requirement

Remove Serial Ports?

Are serial ports really part of debugging, or just a convenient re-use of the debug transport pins? Are they covered by authentication protection? If not, should this just be removed from the debug spec?

"Debug mode" should be changed to "Halt mode".

When I reviewed the reset in 8.3, the term Debug Mode showed up:
"If the halt signal is asserted when a core comes out of reset, the core must enter Debug Mode before executing any instructions "
However, the "debug mode" should be "halt mode".
So, every reference to debug mode should be changed to halt mode.
Moreover, the privileged spec use the term "debug mode" so we will need to sync with privileged spec for the term.

Quick Access -- Define it in a useful way

I think as it is the Quick Access Abstract Command is not useful. There is a race condition that is not handled -- what if a hart halts due to a breakpoint? Do you really intend it to resume? Is the Quick Access command then an error?

Define numbers for "nonstandard" versions

From the mailing list (@asb):

Currently, the concept of the 'version' of debug support is accessible
via the version field in dmcontrol, the version field in dtmcontrol,
and xdebugver in in dcsr.

I propose that in all of those cases, we reserve and specify a version
number to indicate "non-standard debug is present". If nothing else,
this allows debug software to give a more useful error message.

File `jtag_registers.tex.inc' not found.

Hash: 9f3ec7e

...
(./hwbp_registers.tex.inc) (./core_registers.tex.inc)

! LaTeX Error: File `jtag_registers.tex.inc' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: tex.inc)

Clarify example for Quick Access Memory

Are these backwards:

progbuf5: transfer arg1,S1
progbuf6: transfer arg0,S0

It says above this that
transfer dest,src

Clarify Exceptions during Step

If you set the 'step' bit, then get an exception on the instruction that you step over, should you immediately halt again (once you get the exception), or should you wait until an instruction is committed?

This needs to be clarified in the spec. Right now it says "after executing one instruction", which is a bit vague.

Clarification - Address (type) for dpc

In chapter 4, section 4.4, it is not specified whether the dpc shall contain a virtual or physical address. One might presume this is contextual based on whether the dpc is triggered at various privilege levels, but it should probably be made explicit here.

Clarification - Use of term Spontaneous

In chapter 2 paragraph 4 the term "spontaneous" is used, which implies a lack of premeditation. I suggest to use s/spontaneously and/without intervention, then shall/

Inconstistency in DATACOUNT

ABSTRACTCS.datacount says 0-8 are the allowed values, but there is space for 12 words. It should say 0-12 here

Get rid of Resumereq race condition

Consider the case where a debugger would like to single step. The spec implies that they should:

1. Set 'step' bit in DCSR
2. Resume the hart
3. Wait for the hart to be halted again
4. Check DCSR to see if it was because of single-step

The problem with this is that between steps 2 and 3, the debugger should really wait for the hart to have definitely resumed before checking DCSR. It may have just not resumed yet. We really should have a bit which the SW writes and the HW clears upon resume. This could be resumereq, but really it should be another pair of status bits:

resumedany
resumedall

Is it sufficient to just have these bits cleared by the write to resumereq?

Add Contribution Tips to README

Should we add instructions for potential contributors to the README?

Also, if you make commits without a PR, Watchers don't get notified. Should we require PRs for groups of changes, for this reason if nothing else?

stoptime/stopcycle misnamed

stoptime/stopcycle bits are misnamed as their functionality is really 'keepcountingtime', 'keepcountingcycle'. Either their name or functionality should be inverted.

Note that their names reflect what their functionality used to be.

Clarification - Section 1.4 list

Can the language in the list in section 1.4 be changed so that it is more clear which lines are optional? When a line reads "can do X", is the intent to say "is capable of" or "can choose to"? If an extension is optional, it should occupy a line at the end of the list to group optional lines together. Otherwise, upon reading "option" in line 4 the perception of "can do X" can waver by the reader's perception.

Support more than 1024 harts

Feedback from the workshop

Two typo or problems of description

1. Table of page 40 is out of boundary and it's probably a latex problem.
2. In page 29 for serial port, the spec said "Overflow state is sticky, and can be reset by writing 0 to this bit.". What does it mean by sticky?

Table 2 is running off the page

Table 2 (Debug Module Interface Address Space) is running off the page

Clarify the type of "address" triggers applies to

The proposal is that triggers match on virtual addresses (which are equivalent to physical in some scenarios). But this is not clear in the specification either way.

Reorganize addresses for future expansion / easier HW decoding

Right now the address map is densely packed, which means everything moves around if we add/remove a register. It is also harder than it needs to be to decode the address space or split up the functionalities into submodules. Below is a proposed re organization.

0x00 & DM Control : dmactive, resume, haltreq, reset req, hartsel, \
0x01 & DM Status : authenticated, hart status, etc&
0x02 & Hart Info : Capabilities for given hart\
0x03 & Halt Summary \
0x04
0x05
0x06 Abstract Control & Status + Prog Buffer Control & Status (combine) \
0x07 Abstract Command
0x08
0x0a
0x0b (optional hart array registers in this region somewhere)
0x0c
0x0d
0x0e
0x0f

0x10 & Abstract Data 0 \
0x11 & Abstract Data 1 \
0x12 & Abstract Data 2 \
0x13 & Abstract Data 3 \
0x14 & Abstract Data 4 \
0x15 & Abstract Data 5 \
0x16 & Abstract Data 6 \
0x17 & Abstract Data 7 \
0x18 & Abstract Data 8 \
0x19 & Abstract Data 9 \
0x1a & Abstract Data 10 \
0x1b & Abstract Data 11 \
0x1c
0x1d
0x1e
0x1f

0x20 & Program Buffer 0 \
0x21 & Program Buffer 1 \
0x22 & Program Buffer 2 \
0x23 & Program Buffer 3 \
0x24 & Program Buffer 4 \
0x25 & Program Buffer 5 \
0x26 & Program Buffer 6 \
0x27 & Program Buffer 7 \
0x28 & Program Buffer 8 \
0x29 & Program Buffer 9 \
0x2a & Program Buffer 10 \
0x2b & Program Buffer 11 \
0x2a
0x2b
0x2c
0x2d
0x2e
0x2f

0x30 & Authentication Data \

0x34 & Serial Control and Status \
0x35 & Serial Send Data \
0x36 & Serial Rx Data \

0x38 & System Bus Access Control and Status \
0x39 & System Bus Address 31:0 \
0x3a & System Bus Address 63:32 \
0x3b & System Bus Address 95:64 \
0x3c & System Bus Data 31:0 \
0x3d & System Bus Data 63:32 \
0x3e & System Bus Data 95:64 \
0x3f & System Bus Data 127:96 \

ICount Trigger Type TODO

There is still a TODO about icount trigger type, also related to sorear/riscv-specs#21

sw_registers.tex is missing

$ make -j1
make: *** No rule to make target 'sw_registers.tex', needed by 'riscv-debug-spec.pdf'.  Stop.

It looks like this is from 0512f5d.

debugInterrupt in dcsr.cause

Debug Interrupt is not described in the spec anymore (it is perhaps an implementation detail). But it is listed as cause 3 in DCSR description. It's unclear what is the difference between cause 3 and 5 ("\Fhaltreq was asserted").

define 'dret' again

'dret' was removed since it's now an "implementation detail". But if we are to have any sort of reusable components, we should define the dret instruction, even if it is optional to implement.

Should SBERROR be W1-to-Clear?

SBCS.sberror says write 0 to clear the error, but all the error bits are write 1 to clear. Should make it consistent

Match Control table runs off the bottom of the page

Match Control 9.1.5, the "action" field is too long and I can't read the bottom

Missing advice on when triggers should fire

The spec currently states:

    Address and data trigger implementation are heavily dependent on how
    the processor core is implemented. To accommodate various
    implementations, load and store address and data triggers may fire at
    whatever point in time is most convenient for the implementation.
    Following the suggestions in the definitions of \Fstore and \Fload will
    lead to the best user experience, however.

However I can't see any such advice around the definition of store and load (https://github.com/sifive/riscv-debug-spec/blob/0.13/hwbp_registers.xml#L182). I think we discussed this issue in a call some time ago, and the consensus was that triggering before the store/load was most useful, especially when considering memory-mapped I/O.

Reserve more bits in DCSR for XDEBUGVER

2 bits is not a lot.

Clarify relationship between XLEN and Supported Abstract Command Sizes

Right now, it is unclear if there is a relationship between XLEN and supported Abstract Command Size. In other words, it's unclear if debugger could do the following:

1. Read MISA CSR with Abstract Command Size = 32bits
2. Learn that XLEN is 64 from the value of $misa
3. Read S0 with size 64 (and confidently expect it to succeed).

Currently, debugger might have to do this less predictable thing:

1. Read S0 with size 128, it fails. XLEN is not 128.
2. Read S0 with size 64, it succeeds, we now know that GPR reads of size 64 work, but don't really know XLEN
3. Read S0 with size 32 --- does it succeed or fail?

Abstract command accesses of size <= XLEN will succeed (if that regno is supported).

Should not "write 0 to clear" status bits

In one of our meetings, it was generally agreed that we should not write 0 to clear status bits, as it is too easy to inadvertently clear something that way.

Places the spec currently states to write 0 to clear:
-serial error
-system bus master error
-abstract command error

Anywhere else?

Just logging this here so that we can clear this up as now there are starting to be implementations we don't want this to hang around for too long.

Add table of Abstract Command Types

Even though we only have 2 commands right now, there is no concise table of abstract command types

Clarification - 1.4 #11,13 Hart vs Core

In section 1.4, list numbers 11 and 13, does the author mean hart or all available harts? Presuming "all available harts" because the term "core" is used, but is it desirable for all harts to be stopped on a breakpoint? How does the masking of certain harts in a (core) affect these list items?

Move description of $prv register

The description of the $prv register should be moved to a "software conventions" section. Since it has no meaning for a HW developer, it is confusing where it is now.

Clarify upper bits of JTAG IR encoding

JTAG instruction is allowed to be > 5 bits, but we only specify the lower bits. Need to clarify what the upper bits would be. The correct thing would be that they are 0.

So, 0x10, or 0x00010, are the same JTAG DTM instruction.

0x0030 is not the same as 0x10.

Clarify: abstract command for $PC access

There is no abstract command for accessing the $PC. Perhaps $DPC is the intended alias for the $PC at all times (even when hart is not halted), but this is currently unclear

Can 'busy' be set without 'halted'?

With the current encoding, if debugger writes a command that has prehalt and postexec bits set, there is no way to distinguish between "hart hasn't halted yet" and "hart already did the command". Or is it meant that 'busy' would be set immediately when the command is written, even before the hart halts? I guess that makes sense, since the command is executing. But I want to clarify and then have to update my diagram to match.

Clarify MISA during Debug Mode

Should Hart use MISA during debug mode? Or should it ignore it and always just use the "most capable" version of itself. The latter means debugger would always get a consistent view of the hart's capabilities and not deal with MISA changing.

I think it's useful for MISA to at least report its current contents accurately, otherwise debugging is hard, so "save and restore" in HW is a less appealing option.

The other option is that Debuggers can write MISA to enable all capabilities whenever hart is halted, or whenever something that it expected to work fails, etc etc.

Note that OpenOCD already does something similar for reading/writing the FPRs. In order to read them when hart is halted, it has to enable the bit in MSTATUS (or something) that enables the FPU. When the hart is resumed, it restores MSTATUS to its value.

So this is really a HW/SW tradeoff question. Because there are lots of simlar places where this is an issue (see above), I think it makes sense to keep it in the SW, but I could be convinced otherwise.