It's not clear, as reported in #760.

It doesn't matter what the values are after write/nop, so explicitly
state that.

Fixes #755.

* Clarify dcsr.cause when halt groups are used.

* Mention that cause can be 3 on haltgroup.

The side effects only really occur in an extreme corner case.

I think. I don't remember anything about why this section was written,
and I wonder if I'm forgetting about something.

CC BY 4.0 is incompatible with the GPL, meaning the file could not be
used in GPL projects like OpenOCD. RISC-V has plans to address this, but
the lawyers are working on other issues right now. Until that is
properly resolved, we're reverting to the way things were before #641
and removing the license line.

Specifically, it wasn't true for abstractauto.

* Clarify dcsr.cause priorities for #691

* Apply suggestions from code review

Co-authored-by: Tim Newsome <tim@sifive.com>

* Review feedback: Incorporate table 5.2 by reference.

* Minor wording change

Co-authored-by: Tim Newsome <tim@sifive.com>

* Recommend the new dcsr.cause priority but allow the old priority.

* Explain why dcsr.cause priorities can vary

Co-authored-by: Tim Newsome <tim@sifive.com>

Co-authored-by: Tim Newsome <tim@sifive.com>

* add auto release CI.

* CI should verify more targets in Makefile

Those values are fixed, and there's no need to send somebody looking for
a different document just to see the very short description.

Leave the descriptions empty, and change registers.py to not emit
anything for values whose descriptions are empty.

I'm not a huge fan of the duplication of those values in the XML file,
but I don't want to invent a new mechanism to avoid it right now. (Ooh,
we could use M4 to generate the XML and use an existing mechanism...)

* Add field values to XML register description.

Generate constants in the C header for the values. E.g.
```
 #define CSR_TDATA1_TYPE_NONE                0
 #define CSR_TDATA1_TYPE_LEGACY              1
 #define CSR_TDATA1_TYPE_MCONTROL            2
 #define CSR_TDATA1_TYPE_ICOUNT              3
 ...
```
Make formatting slightly more consistent in the PDF.

* Use \unspecified instead of "undefined values"

* Rename a bunch of field values based on review.

* Rename field values that specify a number of bits

* stop{time,count} values are called normal/freeze

* Abstract command write value arg->arg0

* Name field values <n>bit

This allows a more efficient implementation, especially on FPGAs.
See #717.

* Make data registers Message Registers.

Message Registers allow data to be sent to the other side, but not to be
read back by the side that wrote the data.

This allows smaller FPGA implementations by duplicating the storage and
removing muxes in the design.

It is incompatible with old debuggers, if they use these registers in
surprising ways.

* Clarify MRs in datasize

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* flip-flops -> bits

Bits is more general, assuming less about the implementation.

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* Describe debug_defines.h.

To make that fit in a reasonable section, combine the separate
external/native debug implementation chapters into a single debugger
implementation chapter.

* Point people at the repo

This doc might be stale when it comes to how to generate
debug_defines.h.

* Add arguments to C macros that need them.

Previously no macros took arguments, even those that depended on e.g.
XLEN.

Old:
 #define CSR_TDATA1_TYPE_OFFSET              (XLEN-4)
 #define CSR_TDATA1_TYPE_LENGTH              4
 #define CSR_TDATA1_TYPE                     (0xfULL << CSR_TDATA1_TYPE_OFFSET)

New:
 #define CSR_TDATA1_TYPE_OFFSET(XLEN)        (XLEN + -4)
 #define CSR_TDATA1_TYPE_LENGTH              4
 #define CSR_TDATA1_TYPE(XLEN)               (0xf * (1ULL<<(XLEN + -4)))

The new syntax can be a little awkward, but it's correct and works in
OpenOCD at least. The most awkward new version is this one:
 #define DTM_DMI_ADDRESS_OFFSET              0x22
 #define DTM_DMI_ADDRESS_LENGTH(abits)       abits
 #define DTM_DMI_ADDRESS(abits)              ((0x400000000ULL * (1ULL<<abits)) + -17179869184)

Some of the awkwardness stems from the fact that sympy doesn't support a
<< operator, so I use ** internally and then print it out strangely.
It's correct, just not idiomatic.

* Tweak how we represent numbers.

Add appropriate U and ULL prefix on large hex constants that we negate.

* mte/mpte apply only to breakpoint traps

This makes it possible to use triggers to debug some of the exception
handling code as well.

See 2022 email subject:"trigger questions"

* Mention backwards incompatibility.

* Tighten up language around icount matching.

Specifically, now icount triggers on M-Mode only systems are more
useful, because the count might not decrement while in an interrupt
handler.

See 2022 email discussion subject:"trigger questions"

* Document that this change is backwards incompatible.

It is not necessary to first select and then issue the command in
dmcontrol. The old language could have been interpreted that way.

* Add disabled trigger type.

Also clarify tdata2/tdata3 behavior when a trigger is disabled.
Add a paragraph about context restoring triggers.

* Change trigger type 15 to mean disabled.

Nobody can remember why a trigger might be unavailable, or imagine what
that even means.

* Formatting

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* Clarifications/bug fixes: mscontext and tselect
mscontext is accessible in S mode.
tselect is WARL.  This was in the XML but not in the final PDF.

* Address review feedback.

* Clarify behavior of low bits of tdata2 when match=1.
As discussed in the TG meeting.

* Update xml/hwbp_registers.xml

Co-authored-by: Tim Newsome <tim@sifive.com>

Co-authored-by: Paul Donahue <paul@pauldonahue.com>
Co-authored-by: Tim Newsome <tim@sifive.com>

Also describe where this structure is mentioned in the priv spec.

Fixes #710

* Fix contradiction in icount description.

Specifically, after we added the pending bit, the description of a
possible 1-bit implementation of this register was not updated. As a
result the count description said that decrementing resulted in a
trigger, while in the introductory part we said that decrementing
resulted in pending getting set.

Rewrote it a bit, so it's hopefully easier to read.

Fixes #662.

* Explain 2 icount use cases.

Are there others? Is this clear?

* eret is now mret

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* Language

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* Small clarification.

* Move single step example code into Appendix.

* Language cleanups.

* Make things less ambiguous.

Remove explanation about how icount can be done in a single bit.

The single-bit implementation can work, but only if you tie all mode
bits together and have max count of 1. If all mode bits are enabled
together, there is no case where the existence of a pending bit can make
a different. But this is only useful for an external debugger, and we
already say that for external debuggers dcsr.step is the preferred
solution.

For native debugging, the least hardware I can think of is 2 bits,
because there are effectively 3 states: disabled, pending, and enabled.
This assumes the mode bits are tied together in such a way that there is
only one sensible option. I'm not sure if that's even worth mentioning
anywhere. It would be a long explanation with little benefit.

* Clarify the icount always decrements.

Even if the chosen action cannot be taken.

Also use proper field macros for most action=0 instances.

* Refer to precise instructions in icount.count.

Co-authored-by: Paul Donahue <48959409+pdonahue-ventana@users.noreply.github.com>

* Mention textra in the trigger types that it affects.

* Clarify textra is implemented for *this* trigger

* Slight rewording.

This value does not end up in the actual document, but it should be
right in the source anyway.

* Move nmi from etrigger to itrigger.

Per mailing list discussion subject:"etrigger.nmi".

* Add this PR number to the new feature.

* nmi is subject to mode bits.

Based on subject:"NMI trigger and tdata2/tdata3" discussion.

The privileged spec says that medeleg only delegates synchronous exceptions
so clarify that in the case of tmexttrigger medeleg is delegating an
asynchronous exception.
Also clarify what happens to tmexttrigger events that happen while the trigger
is prevented from firing.