[Lldb-commits] [lldb] [lldb][docs] Add hardware feature considerations to target doc (PR #211213)

[David Spickett via lldb-commits]

================
@@ -298,3 +298,172 @@ As you have seen above, there are a lot of moving parts to a debugger. So
 having some set of results to measure progress is very important.
 Sometimes a change will get one test to pass, sometimes hundreds, and it
 is easy to regress if you are not careful.
+
+## Target Hardware Features
+
+Some hardware features can make porting easier or harder. Below is a
+non-exhaustive list of features and their impacts on porting LLDB.
+
+### Hardware Single Step
+
+If the target lacks this feature, you will have to implement software single
+stepping. This is much more complex and involves emulating any instruction that
+could modify the program counter.
+
+### Instruction Bundles and Sequences
+
+This is any situation where to resume the program you have to replay some
+previous instructions. LLDB needs to know the extent of the sequence.
+
+For example, an atomic sequence may implement an atomic operation by looping
+until success. When stepping through the sequence normally, this check will
+always fail (due to the debug exceptions) and cause it to loop forever.
+
+You can teach LLDB to find the sequence start point, and replay the whole thing
+as if it were one step.
+
+If you have instruction bundles, check how breakpoints behave and where in the
+bundles they can be placed.
+
+### Single Instruction Equivalents of Sequences
+
+The opposite of the previous point. If your target has single instructions
+for what is normally a sequence, this reduces the work needed in LLDB. Single
+instruction atomics are a common example.
+
+### Runtime Register Resizing
+
+Anything like AArch64's Scalable Vector Extension (SVE) registers. At each stop
+event the registers may have a different size.
+
+Support for this is currently SVE specific as it requires `lldb` to know which
+registers scale and what to derive their size from.
+
+### Registers That Come And Go At Runtime
+
+If you have registers that are not present for the entire program runtime you
+will need to decide how to present that.
+
+The one example we support right now is AArch64's Scalable Matrix Extension
+(SME) `ZA` register. This register can be switched off when not in use.
+We handle this by showing a fake zero value at these times, with a separate
+mode bit in another register so users can tell a real zero from a fake zero.
+
+The more fundemental and the more numerous the registers are, the more
+likely you are to confuse users by showing them even when they are unusable.
+For instance if you have two execution modes that use separate register sets,
+showing both all the time may be confusing for users.
+
+### Registers With The Same Name In Different Contexts
+
+When you have banked registers or a copy of a register for each execution mode,
+it usually only has one name. You need to decide if it makes sense to
+allow users to access each one separately.
+
+For example, AArch64's SME extension adds a "streaming mode". SVE registers
+exist in the normal mode and the streaming mode. However programs only ever use
+one or the other, and the values are cleared when the mode is switched. So there
+is no reason to let users write to the inactive mode's registers and we just
+show 1 set with the normal naming. That set always refers to the active mode.
+
+However if you have overlapping sets that can hold their own values, you may
+want to make the normal register name the active set, and have a way to address
+the other sets.
+
+### Execution Modes That Change Instruction Encoding
+
+Arm (meaning Armv7 and prior) has 2 execution modes: Arm and Thumb. If you
+attempt to execute Thumb mode code in Arm mode, it will not work. Programs can
+mix the two modes by using special mode switching branches.
+
+The debugger has to be aware of what mode the inferior is in so that it can
+correctly compare addresses, place breakpoints and use the correct breakpoint
+instruction encoding.
+
+In Arm's case, the information comes from markers in the program file, and the
+bottom bit of the program counter. This is often a source of bugs because many
+parts of the debugger have to know that this bit is not part of the instruction
+address.
+
+### Variable Length Instruction Encoding
+
+LLDB already supports a wide variety of encoding strategies, so variable length
+encoding is not much more work than fixed length.
+
+Of the current targets we have:
+* Intel which is variable length.
+* Arm (Armv7 and prior) with Arm (32-bit), Thumb 1 (16-bit) and Thumb 2
+  (a mix of 16 and 32-bit).
+* RISC-V which is variable, usually 32-bit or the 16-bit compressed
+  instructions.
+* AArch64 which is fixed length, always 32-bit.
+
+### Hardware Breakpoints and Watchpoints
+
+Code breakpoints can be implemented in software by replacing an instruction with
+a software breakpoint instruction.
+
+However, if you want to only stop in certain situations (a single address space,
+a single execution mode, and so on), code breakpoints implemented in hardware
+will be much faster.
+
+Doing it in software means you have to return into the debugger to filter
----------------
DavidSpickett wrote:

Done.

https://github.com/llvm/llvm-project/pull/211213