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

[David Spickett via lldb-commits]

================
@@ -298,3 +298,151 @@ 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. Which 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
+
+Anything like AArch64's Scalable Matrix Extension (SME) `ZA` register. This
+register can be switched off when not in use. At the moment we do not show
+this accurately. When the register is off, we show the user a fake zero
----------------
DavidSpickett wrote:

Good question but I have a feeling I got away with this tactic once and will have to implement a proper solution one day. So I don't want to make it policy.

For instance if you had 2 execution modes where you could not use certain registers at all, showing them as zeros is not ideal. You could teach users what it means, but it's not great.

....in fact maybe I should start with that generic scenario instead.

And remove the "at the moment" part as you suggested.

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