[lldb] Unwind through ARM Cortex-M exceptions automatically

When a processor faults/is interrupted/gets an exception, it will
stop running code and jump to an exception catcher routine.  Most
processors will store the pc that was executing in a system register,
and the catcher functions have special instructions to retrieve
that & possibly other registers.  It may then save those values to
stack, and the author can add .cfi directives to tell lldb's unwinder
where to find those saved values.

ARM Cortex-M (microcontroller) processors have a simpler mechanism
where a fixed set of registers are saved to the stack on an exception,
and a unique value is put in the link register to indicate to the
caller that this has taken place.  No special handling needs to be
written into the exception catcher, unless it wants to inspect these
preserved values.  And it is possible for a general stack walker to
walk the stack with no special knowledge about what the catch function
does.

This patch adds an Architecture plugin method to allow an Architecture
to override/augment the UnwindPlan that lldb would use for a stack
frame, given the contents of the return address register.  It
resembles a feature where the LanguageRuntime can replace/augment
the unwind plan for a function, but it is doing it at offset by one
level.  The LanguageRuntime is looking at the local register context
and/or symbol name to decide if it will override the unwind rules.
For the Cortex-M exception unwinds, we need to modify THIS frame's
unwind plan if the CALLER's LR had a specific value.  RegisterContextUnwind
has to retrieve the caller's LR value before it has completely
decided on the UnwindPlan it will use for THIS stack frame.

This does mean that we will need one additional read of stack memory
than we currently use when unwinding.  The unwinder walks the stack
lazily, as stack frames are requested, and so now if you ask for 2
stack frames, we will read enough stack to walk 2 frames, plus we
will read one extra word of memory, the spilled RA value from the
stack (see RegisterContextUnwind::AdoptArchitectureUnwindPlan()).
In practice, with 512-byte memory cache reads, this is unlikely to be
a problem, but I'm wondering if I should add an Architecture method
of "does this Architecture implement `GetArchitectureUnwindPlan`"
method -- and only do the memory read if it does.  So the performance
impact would be limited to armv7/Cortex-M debug sessions.

This PR includes a test with a yaml corefile description and a JSON
ObjectFile, incorporating all of the necessary stack memory and
symbol names from a real debug session I worked on.  The architectural
default unwind plans are used for all stack frames except the 0th
because there's no instructions for the functions, and no unwind
info.  I may need to add an encoding of unwind fules to ObjectFileJSON
in the future as we create more test cases like this.

This PR depends on the yaml2macho-core utility from
llvm#153911

rdar://110663219

Author: jasonmolenda

lldb/include/lldb/Core/Architecture.h

@@ -129,6 +129,15 @@ class Architecture : public PluginInterface {
                                        RegisterContext &reg_context) const {
     return false;
   }
+
+  /// Return an UnwindPlan that allows architecture-defined rules for finding
+  /// saved registers in a specific context (not specific to a function's
+  /// instructions/unwind info).
+  virtual lldb::UnwindPlanSP GetArchitectureUnwindPlan(
+      lldb_private::Thread &thread, lldb::addr_t callers_return_address,
+      lldb::addr_t cfa, std::shared_ptr<const UnwindPlan> current_unwindplan) {
+    return lldb::UnwindPlanSP();
+  }
 };
 
 } // namespace lldb_private

lldb/include/lldb/Target/RegisterContextUnwind.h

@@ -202,6 +202,8 @@ class RegisterContextUnwind : public lldb_private::RegisterContext {
 
   std::shared_ptr<const UnwindPlan> GetFullUnwindPlanForFrame();
 
+  lldb::UnwindPlanSP AdoptArchitectureUnwindPlan();
+
   void UnwindLogMsg(const char *fmt, ...) __attribute__((format(printf, 2, 3)));
 
   void UnwindLogMsgVerbose(const char *fmt, ...)

lldb/source/Plugins/ABI/ARM/ABISysV_arm.cpp

@@ -1921,6 +1921,13 @@ UnwindPlanSP ABISysV_arm::CreateFunctionEntryUnwindPlan() {
 
 UnwindPlanSP ABISysV_arm::CreateDefaultUnwindPlan() {
   // TODO: Handle thumb
+  // If we had a Target argument, could at least check
+  // target.GetArchitecture().GetTriple().isArmMClass()
+  // which is always thumb.
+  // To handle thumb properly, we'd need to fetch the current
+  // CPSR state at unwind time to tell if the processor is
+  // in thumb mode in this stack frame.  There's no way to
+  // express something like that in an UnwindPlan today.
   uint32_t fp_reg_num = dwarf_r11;
   uint32_t pc_reg_num = dwarf_pc;
 

lldb/source/Plugins/Architecture/Arm/ArchitectureArm.cpp

@@ -9,10 +9,15 @@
 #include "Plugins/Architecture/Arm/ArchitectureArm.h"
 #include "Plugins/Process/Utility/ARMDefines.h"
 #include "Plugins/Process/Utility/InstructionUtils.h"
+#include "Utility/ARM_DWARF_Registers.h"
 #include "lldb/Core/PluginManager.h"
+#include "lldb/Symbol/UnwindPlan.h"
+#include "lldb/Target/Process.h"
 #include "lldb/Target/RegisterContext.h"
 #include "lldb/Target/Thread.h"
 #include "lldb/Utility/ArchSpec.h"
+#include "lldb/Utility/LLDBLog.h"
+#include "lldb/Utility/Log.h"
 
 using namespace lldb_private;
 using namespace lldb;
@@ -150,3 +155,118 @@ addr_t ArchitectureArm::GetOpcodeLoadAddress(addr_t opcode_addr,
   }
   return opcode_addr & ~(1ull);
 }
+
+// The ARM M-Profile Armv7-M Architecture Reference Manual
+// "Exception return behavior" describes how the processor
+// saves registers to the stack, decrements the stack pointer,
+// puts a special value in $lr, and then calls a registered
+// exception handler routine.
+//
+// Detect that special value in $lr, and if present, add
+// unwind rules for the registers that were saved above this
+// stack frame's CFA.  Overwrite any register locations that
+// the current_unwindplan has for these registers; they are
+// not correct when we're invoked this way.
+UnwindPlanSP ArchitectureArm::GetArchitectureUnwindPlan(
+    Thread &thread, addr_t callers_return_address, addr_t cfa,
+    std::shared_ptr<const UnwindPlan> current_unwindplan) {
+
+  ProcessSP process_sp = thread.GetProcess();
+  if (!process_sp)
+    return {};
+
+  const ArchSpec arch = process_sp->GetTarget().GetArchitecture();
+  if (!arch.GetTriple().isArmMClass() || arch.GetAddressByteSize() != 4)
+    return {};
+
+  if (callers_return_address != 0xFFFFFFF1 &&
+      callers_return_address != 0xFFFFFFF9 &&
+      callers_return_address != 0xFFFFFFFD &&
+      callers_return_address != 0xFFFFFFE1 &&
+      callers_return_address != 0xFFFFFFE9 &&
+      callers_return_address != 0xFFFFFFED)
+    return {};
+
+  const RegisterKind plan_regkind = current_unwindplan->GetRegisterKind();
+  UnwindPlanSP new_plan = std::make_shared<UnwindPlan>(plan_regkind);
+  new_plan->SetSourceName("Arm Cortex-M exception return UnwindPlan");
+  new_plan->SetSourcedFromCompiler(eLazyBoolNo);
+  new_plan->SetUnwindPlanValidAtAllInstructions(eLazyBoolYes);
+  new_plan->SetUnwindPlanForSignalTrap(eLazyBoolYes);
+
+  // bit 4 will be 1 if only the general purpose registers were saved.
+  // bit 4 will be 0 if the GPRs + floating point registers were saved.
+  const bool fp_regs_saved = (callers_return_address & 0x10) == 0;
+
+  int stored_regs_size = 0x20;
+  if (fp_regs_saved)
+    stored_regs_size = 0x68;
+
+  uint32_t gpr_regs[] = {dwarf_r0,  dwarf_r1, dwarf_r2, dwarf_r3,
+                         dwarf_r12, dwarf_lr, dwarf_pc, dwarf_cpsr};
+  const int gpr_reg_count = sizeof(gpr_regs) / sizeof(uint32_t);
+  uint32_t fpr_regs[] = {dwarf_s0,  dwarf_s1,  dwarf_s2,  dwarf_s3,
+                         dwarf_s4,  dwarf_s5,  dwarf_s6,  dwarf_s7,
+                         dwarf_s8,  dwarf_s9,  dwarf_s10, dwarf_s11,
+                         dwarf_s12, dwarf_s13, dwarf_s14, dwarf_s15};
+  const int fpr_reg_count = sizeof(fpr_regs) / sizeof(uint32_t);
+
+  RegisterContextSP reg_ctx_sp = thread.GetRegisterContext();
+  std::vector<uint32_t> saved_regs;
+  for (int i = 0; i < gpr_reg_count; i++) {
+    uint32_t regno = gpr_regs[i];
+    reg_ctx_sp->ConvertBetweenRegisterKinds(eRegisterKindDWARF, gpr_regs[i],
+                                            plan_regkind, regno);
+    saved_regs.push_back(regno);
+  }
+  if (fp_regs_saved) {
+    for (int i = 0; i < fpr_reg_count; i++) {
+      uint32_t regno = fpr_regs[i];
+      reg_ctx_sp->ConvertBetweenRegisterKinds(eRegisterKindDWARF, fpr_regs[i],
+                                              plan_regkind, regno);
+      saved_regs.push_back(regno);
+    }
+  }
+
+  // PSR bit 9 indicates that the stack pointer was unaligned (to
+  // an 8-byte alignment) when the exception happened, and we must
+  // account for that when restoring the excepted stack pointer value.
+  Status error;
+  uint32_t callers_xPSR =
+      process_sp->ReadUnsignedIntegerFromMemory(cfa + 0x28, 4, 0, error);
+  const bool align_stack = callers_xPSR & (1 << 9U);
+  uint32_t callers_sp = cfa + stored_regs_size;
+  if (align_stack)
+    callers_sp |= 4;
+
+  Log *log = GetLog(LLDBLog::Unwind);
+  LLDB_LOGF(log,
+            "ArchitectureArm::GetArchitectureUnwindPlan found caller return "
+            "addr of 0x%" PRIx64 ", for frame with CFA 0x%" PRIx64
+            ", fp_regs_saved %d, stored_regs_size 0x%x, align stack %d",
+            callers_return_address, cfa, fp_regs_saved, stored_regs_size,
+            align_stack);
+
+  uint32_t sp_regnum = dwarf_sp;
+  reg_ctx_sp->ConvertBetweenRegisterKinds(eRegisterKindDWARF, dwarf_sp,
+                                          plan_regkind, sp_regnum);
+
+  const int row_count = current_unwindplan->GetRowCount();
+  for (int i = 0; i < row_count; i++) {
+    UnwindPlan::Row row = *current_unwindplan->GetRowAtIndex(i);
+    uint32_t offset = 0;
+    const size_t saved_reg_count = saved_regs.size();
+    for (size_t j = 0; j < saved_reg_count; j++) {
+      // The locations could be set with
+      // SetRegisterLocationToIsConstant(regno, cfa+offset)
+      // expressing it in terms of CFA addr+offset - this UnwindPlan
+      // is only used once, with this specific CFA.  I'm not sure
+      // which will be clearer for someone reading the unwind log.
+      row.SetRegisterLocationToAtCFAPlusOffset(saved_regs[j], offset, true);
+      offset += 4;
+    }
+    row.SetRegisterLocationToIsCFAPlusOffset(sp_regnum, callers_sp - cfa, true);
+    new_plan->AppendRow(row);
+  }
+  return new_plan;
+}

lldb/source/Plugins/Architecture/Arm/ArchitectureArm.h

@@ -10,6 +10,7 @@
 #define LLDB_SOURCE_PLUGINS_ARCHITECTURE_ARM_ARCHITECTUREARM_H
 
 #include "lldb/Core/Architecture.h"
+#include "lldb/Target/Thread.h"
 
 namespace lldb_private {
 
@@ -29,6 +30,11 @@ class ArchitectureArm : public Architecture {
   lldb::addr_t GetOpcodeLoadAddress(lldb::addr_t load_addr,
                                     AddressClass addr_class) const override;
 
+  lldb::UnwindPlanSP GetArchitectureUnwindPlan(
+      lldb_private::Thread &thread, lldb::addr_t callers_return_address,
+      lldb::addr_t cfa,
+      std::shared_ptr<const UnwindPlan> current_unwindplan) override;
+
 private:
   static std::unique_ptr<Architecture> Create(const ArchSpec &arch);
   ArchitectureArm() = default;

lldb/source/Plugins/ObjectFile/JSON/ObjectFileJSON.cpp

@@ -12,6 +12,7 @@
 #include "lldb/Core/PluginManager.h"
 #include "lldb/Core/Section.h"
 #include "lldb/Symbol/Symbol.h"
+#include "lldb/Target/Target.h"
 #include "lldb/Utility/LLDBLog.h"
 #include "lldb/Utility/Log.h"
 #include "llvm/ADT/DenseSet.h"
@@ -233,6 +234,41 @@ void ObjectFileJSON::CreateSections(SectionList &unified_section_list) {
   }
 }
 
+bool ObjectFileJSON::SetLoadAddress(Target &target, lldb::addr_t value,
+                                    bool value_is_offset) {
+  Log *log(GetLog(LLDBLog::DynamicLoader));
+  if (!m_sections_up)
+    return true;
+
+  const bool warn_multiple = true;
+
+  addr_t slide = value;
+  if (!value_is_offset) {
+    addr_t lowest_addr = LLDB_INVALID_ADDRESS;
+    for (const SectionSP &section_sp : *m_sections_up) {
+      addr_t section_load_addr = section_sp->GetFileAddress();
+      lowest_addr = std::min(lowest_addr, section_load_addr);
+    }
+    if (lowest_addr == LLDB_INVALID_ADDRESS)
+      return false;
+    slide = value - lowest_addr;
+  }
+
+  // Apply slide to each section's file address.
+  for (const SectionSP &section_sp : *m_sections_up) {
+    addr_t section_load_addr = section_sp->GetFileAddress();
+    if (section_load_addr != LLDB_INVALID_ADDRESS) {
+      LLDB_LOGF(
+          log,
+          "ObjectFileJSON::SetLoadAddress section %s to load addr 0x%" PRIx64,
+          section_sp->GetName().AsCString(), section_load_addr + slide);
+      target.SetSectionLoadAddress(section_sp, section_load_addr + slide,
+                                   warn_multiple);
+    }
+  }
+  return true;
+}
+
 bool ObjectFileJSON::MagicBytesMatch(DataBufferSP data_sp,
                                      lldb::addr_t data_offset,
                                      lldb::addr_t data_length) {

lldb/source/Plugins/ObjectFile/JSON/ObjectFileJSON.h

@@ -86,6 +86,9 @@ class ObjectFileJSON : public ObjectFile {
 
   Strata CalculateStrata() override { return eStrataUser; }
 
+  bool SetLoadAddress(Target &target, lldb::addr_t value,
+                      bool value_is_offset) override;
+
   static bool MagicBytesMatch(lldb::DataBufferSP data_sp, lldb::addr_t offset,
                               lldb::addr_t length);
 

lldb/source/Plugins/Process/mach-core/ProcessMachCore.cpp

@@ -799,6 +799,23 @@ Status ProcessMachCore::DoGetMemoryRegionInfo(addr_t load_addr,
       region_info.SetMapped(MemoryRegionInfo::eNo);
     }
     return Status();
+  } else {
+    // The corefile has no LC_SEGMENT at this virtual address,
+    // but see if there is a binary whose Section has been
+    // loaded at that address in the current Target.
+    Address addr;
+    if (GetTarget().ResolveLoadAddress(load_addr, addr)) {
+      SectionSP section_sp(addr.GetSection());
+      if (section_sp) {
+        region_info.GetRange().SetRangeBase(
+            section_sp->GetLoadBaseAddress(&GetTarget()));
+        region_info.GetRange().SetByteSize(section_sp->GetByteSize());
+        if (region_info.GetRange().Contains(load_addr)) {
+          region_info.SetLLDBPermissions(section_sp->GetPermissions());
+          return Status();
+        }
+      }
+    }
   }
 
   region_info.GetRange().SetRangeBase(load_addr);

lldb/source/Target/RegisterContextUnwind.cpp

@@ -293,6 +293,9 @@ void RegisterContextUnwind::InitializeZerothFrame() {
     return;
   }
 
+  // Give the Architecture a chance to replace the UnwindPlan.
+  AdoptArchitectureUnwindPlan();
+
   UnwindLogMsg("initialized frame current pc is 0x%" PRIx64 " cfa is 0x%" PRIx64
                " afa is 0x%" PRIx64 " using %s UnwindPlan",
                (uint64_t)m_current_pc.GetLoadAddress(exe_ctx.GetTargetPtr()),
@@ -482,6 +485,9 @@ void RegisterContextUnwind::InitializeNonZerothFrame() {
         }
       }
 
+      // Give the Architecture a chance to replace the UnwindPlan.
+      AdoptArchitectureUnwindPlan();
+
       UnwindLogMsg("initialized frame cfa is 0x%" PRIx64 " afa is 0x%" PRIx64,
                    (uint64_t)m_cfa, (uint64_t)m_afa);
       return;
@@ -686,6 +692,9 @@ void RegisterContextUnwind::InitializeNonZerothFrame() {
     }
   }
 
+  // Give the Architecture a chance to replace the UnwindPlan.
+  AdoptArchitectureUnwindPlan();
+
   UnwindLogMsg("initialized frame current pc is 0x%" PRIx64
                " cfa is 0x%" PRIx64 " afa is 0x%" PRIx64,
                (uint64_t)m_current_pc.GetLoadAddress(exe_ctx.GetTargetPtr()),
@@ -1717,6 +1726,78 @@ RegisterContextUnwind::SavedLocationForRegister(
   return UnwindLLDB::RegisterSearchResult::eRegisterNotFound;
 }
 
+UnwindPlanSP RegisterContextUnwind::AdoptArchitectureUnwindPlan() {
+  if (!m_full_unwind_plan_sp)
+    return {};
+  ProcessSP process_sp = m_thread.GetProcess();
+  if (!process_sp)
+    return {};
+
+  UnwindPlanSP arch_override_plan_sp;
+
+  RegisterNumber ra_regnum(m_thread, eRegisterKindGeneric,
+                           LLDB_REGNUM_GENERIC_RA);
+  uint32_t ra_regnum_lldb = ra_regnum.GetAsKind(eRegisterKindLLDB);
+  // The only Architecture UnwindPlan today requires the value of
+  // the return address register.
+  if (ra_regnum_lldb == LLDB_INVALID_REGNUM)
+    return {};
+
+  UnwindLLDB::ConcreteRegisterLocation regloc = {};
+  bool got_concrete_location = false;
+  if (SavedLocationForRegister(ra_regnum_lldb, regloc) ==
+      UnwindLLDB::RegisterSearchResult::eRegisterFound) {
+    got_concrete_location = true;
+  } else {
+    RegisterNumber pc_regnum(m_thread, eRegisterKindGeneric,
+                             LLDB_REGNUM_GENERIC_PC);
+    uint32_t pc_regnum_lldb = pc_regnum.GetAsKind(eRegisterKindLLDB);
+    if (SavedLocationForRegister(pc_regnum_lldb, regloc) ==
+        UnwindLLDB::RegisterSearchResult::eRegisterFound)
+      got_concrete_location = true;
+  }
+
+  if (got_concrete_location) {
+    const RegisterInfo *reg_info = GetRegisterInfoAtIndex(ra_regnum_lldb);
+    if (reg_info) {
+      RegisterValue reg_value;
+      if (ReadRegisterValueFromRegisterLocation(regloc, reg_info, reg_value)) {
+        addr_t ra;
+        if (process_sp->GetTarget().GetArchitecture().GetAddressByteSize() == 4)
+          ra = reg_value.GetAsUInt32();
+        else
+          ra = reg_value.GetAsUInt64();
+        if (Architecture *arch =
+                process_sp->GetTarget().GetArchitecturePlugin())
+          arch_override_plan_sp = arch->GetArchitectureUnwindPlan(
+              m_thread, ra, m_cfa, m_full_unwind_plan_sp);
+      }
+    }
+  }
+  if (arch_override_plan_sp) {
+    m_full_unwind_plan_sp = arch_override_plan_sp;
+    PropagateTrapHandlerFlagFromUnwindPlan(m_full_unwind_plan_sp);
+    m_registers.clear();
+    Log *log = GetLog(LLDBLog::Unwind);
+    if (log) {
+      UnwindLogMsg(
+          "Replacing Full Unwindplan with Architecture UnwindPlan, '%s'",
+          m_full_unwind_plan_sp->GetSourceName().AsCString());
+      const UnwindPlan::Row *active_row =
+          m_full_unwind_plan_sp->GetRowForFunctionOffset(m_current_offset);
+      if (active_row) {
+        StreamString active_row_strm;
+        active_row->Dump(active_row_strm, m_full_unwind_plan_sp.get(),
+                         &m_thread,
+                         m_start_pc.GetLoadAddress(&process_sp->GetTarget()));
+        UnwindLogMsg("%s", active_row_strm.GetData());
+      }
+    }
+  }
+
+  return {};
+}
+
 // TryFallbackUnwindPlan() -- this method is a little tricky.
 //
 // When this is called, the frame above -- the caller frame, the "previous"

lldb/test/API/functionalities/unwind/cortex-m-exception/Makefile

@@ -0,0 +1 @@
+include Makefile.rules