Initial conversion

Added a document header adoc file.
Initial conversion of the tex to adoc using pandoc.

Author: wmat

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs-resources"]
+	path = docs-resources
+	url = https://github.com/riscv/docs-resources.git

Sdext.adoc

@@ -0,0 +1,234 @@
+[[sec:core_debug]]
+== Sdext (ISA Extension)
+
+This chapter describes the Sdext ISA extension. It must be implemented
+to make external debug work, and is only useful in conjunction with
+external debug.
+
+Modifications to the RISC-V core to support debug are kept to a minimum.
+There is a special execution mode (Debug Mode) and a few extra CSRs. The
+DM takes care of the rest.
+
+In order to be compatible with this specification an implementation must
+implement everything described in this chapter that is not explicitly
+listed as optional.
+
+If Sdext is implemented and Sdtrig is not implemented, then accessing
+any of the Sdtrig CSRs must raise an illegal instruction exception.
+
+[[debugmode]]
+=== Debug Mode
+
+Debug Mode is a special processor mode used only when a hart is halted
+for external debugging. Because the hart is halted, there is no forward
+progress in the normal instruction stream. How Debug Mode is implemented
+is not specified here.
+
+When executing code due to an abstract command, the hart stays in Debug
+Mode and the following apply:
+
+All implemented instructions operate just as they do in M-mode, unless
+an exception is mentioned in this list.
+
+All operations are executed with machine mode privilege, except that
+additional Debug Mode CSRs are accessible and in may be ignored
+according to . Full permission checks, or a relaxed set of permission
+checks, will apply according to .
+
+All interrupts (including NMI) are masked.
+
+Traps don’t take place. Instead, they end execution of the program
+buffer and the hart remains in Debug Mode. Because they do not trap to
+M-mode, they do not update registers such as , `mepc`, `mcause`,
+` mtval`, `mtval2`, and `mtinst`. The same is true for the equivalent
+privileged registers that are updated when trapping to other modes.
+Registers that may be updated as part of execution before the exception
+are allowed to be updated. For example, vector load/store instructions
+which raise exceptions may partially update the destination register and
+set `vstart` appropriately.
+
+Triggers don’t match or fire.
+
+If is 0 then counters continue. If it is 1 then counters are stopped.
+
+If is 0 then continues to update. If it is 1 then will not update. It
+will resynchronize with after leaving Debug Mode.
+
+Instructions that place the hart into a stalled state act as a `nop`.
+This includes `wfi`, `wrs.sto`, and `wrs.nto`.
+
+Almost all instructions that change the privilege mode have  behavior.
+This includes `ecall`, `mret`, `sret`, and `uret`. (To change the
+privilege mode, the debugger can write and in ). The only exception is
+`ebreak`, which ends execution of the Program Buffer when executed.
+
+All control transfer instructions may act as illegal instructions if
+their destination is in the Program Buffer. If one such instruction acts
+as an illegal instruction, all such instructions must act as illegal
+instructions.
+
+All control transfer instructions may act as illegal instructions if
+their destination is outside the Program Buffer. If one such instruction
+acts as an illegal instruction, all such instructions must act as
+illegal instructions.
+
+Instructions that depend on the value of the PC (e.g. `auipc`) may act
+as illegal instructions.
+
+Effective XLEN is DXLEN.
+
+Forward progress is guaranteed.
+
+When , the external debugger can set MPRV and MPP appropriately to have
+hardware perform memory accesses with the appropriate endianness,
+address translation, permission checks, and PMP/PMA checks (subject to
+). This is also the only way to access all of physical memory when
+34-bit physical addresses are supported on a Sv32 hart. If hardware ties
+to 0 then the external debugger is expected to simulate all the effects
+of MPRV, including any extensions that affect memory accesses. For these
+reasons it is recommended to tie to 1.
+
+=== Load-Reserved/Store-Conditional Instructions
+
+The reservation registered by an `lr` instruction on a memory address
+may be lost when entering Debug Mode or while in Debug Mode. This means
+that there may be no forward progress if Debug Mode is entered between
+`lr` and ` sc` pairs.
+
+This is a behavior that debug users must be aware of. If they have a
+breakpoint set between a `lr` and `sc` pair, or are stepping through
+such code, the `sc` may never succeed. Fortunately in general use there
+will be very few instructions in such a sequence, and anybody debugging
+it will quickly notice that the reservation is not occurring. The
+solution in that case is to set a breakpoint on the first instruction
+after the `sc` and run to it. A higher level debugger may choose to
+automate this.
+
+=== Wait for Interrupt Instruction
+
+If halt is requested while `wfi` is executing, then the hart must leave
+the stalled state, completing this instruction’s execution, and then
+enter Debug Mode.
+
+=== Wait-on-Reservation-Set Instructions
+
+If halt is requested while `wrs.sto` or `wrs.nto` is executing, then the
+hart must leave the stalled state, completing this instruction’s
+execution, and then enter Debug Mode.
+
+=== Single Step
+
+[[stepBit]]
+==== Step Bit In Dcsr
+
+This method is only available to external debuggers, and is the
+preferred way to single step.
+
+An external debugger can cause a halted hart to execute a single
+instruction or trap and then re-enter Debug Mode by setting before
+resuming. If is set when a hart resumes then it will single step,
+regardless of the reason for resuming.
+
+If control is transferred to a trap handler while executing the
+instruction, then Debug Mode is re-entered immediately after the PC is
+changed to the trap handler, and the appropriate `tval` and `cause`
+registers are updated. In this case none of the trap handler is
+executed, and if the cause was a pending interrupt no instructions might
+be executed at all.
+
+If executing or fetching the instruction causes a trigger to fire with
+action=1, Debug Mode is re-entered immediately after that trigger has
+fired. In that case is set to 2 (trigger) instead of 4 (single step).
+Whether the instruction is executed or not depends on the specific
+configuration of the trigger.
+
+If the instruction that is executed causes the PC to change to an
+address where an instruction fetch causes an exception, that exception
+does not occur until the next time the hart is resumed. Similarly, a
+trigger at the new address does not fire until the hart actually
+attempts to execute that instruction.
+
+If the instruction being stepped over would normally stall the hart,
+then instead the instruction is treated as a `nop`. This includes `wfi`,
+`wrs.sto`, and `wrs.nto`.
+
+[[stepIcount]]
+==== Icount Trigger
+
+Native debuggers won’t have access to , but can use the trigger by
+setting to 1.
+
+This approach does have some limitations:
+
+Interrupts will fire as usual. Debuggers that want to disable interrupts
+while stepping must disable them by changing , and specially handle
+instructions that read .
+
+`wfi` instructions are not treated specially and might take a very long
+time to complete.
+
+This mechanism cleanly supports a system which supports multiple
+privilege levels, where the OS or a debug stub runs in M-Mode while the
+program being debugged runs in a less privileged mode. Systems that only
+support M-Mode can use as well, but count must be able to count several
+instructions (depending on the software implementation). See Section
+link:#nativestep[[nativestep]].
+
+=== Reset
+
+If the halt signal (driven by the hart’s halt request bit in the Debug
+Module) or are asserted when a hart comes out of reset, the hart must
+enter Debug Mode before executing any instructions, but after performing
+any initialization that would usually happen before the first
+instruction is executed.
+
+=== Halt
+
+When a hart halts:
+
+is updated.
+
+and are set to reflect current privilege mode.
+
+is set to the next instruction that should be executed.
+
+If the current instruction can be partially executed and should be
+restarted to complete, then the relevant state for that is updated. E.g.
+if a halt occurs during a partially executed vector instruction, then
+`vstart` is updated, and is updated to the address of the partially
+executed instruction. This is analogous to how vector instructions
+behave for exceptions.
+
+The hart enters Debug Mode.
+
+=== Resume
+
+When a hart resumes:
+
+changes to the value stored in .
+
+The current privilege mode and virtualization mode are changed to that
+specified by and .
+
+If the new privilege mode is less privileged than M-mode, in is cleared.
+
+The hart is no longer in debug mode.
+
+=== XLEN
+
+While in Debug Mode, XLEN is DXLEN. It is up to the debugger to
+determine the XLEN during normal program execution (by looking at ) and
+to clearly communicate this to the user.
+
+[[debreg]]
+=== Core Debug Registers
+
+The supported Core Debug Registers must be implemented for each hart
+that can be debugged. They are CSRs, accessible using the RISC-V `csr`
+opcodes and optionally also using abstract debug commands.
+
+Attempts to access an unimplemented Core Debug Register raise an illegal
+instruction exception.
+
+[[virtreg]]
+=== Virtual Debug Registers