//===-- RegisterContextUnwind.h ---------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLDB_TARGET_REGISTERCONTEXTUNWIND_H

#define LLDB_TARGET_REGISTERCONTEXTUNWIND_H

#include <vector>

#include "lldb/Symbol/SymbolContext.h"

#include "lldb/Symbol/UnwindPlan.h"

#include "lldb/Target/RegisterContext.h"

#include "lldb/Target/RegisterNumber.h"

#include "lldb/Target/UnwindLLDB.h"

#include "lldb/lldb-private.h"

namespace lldb_private {

class UnwindLLDB;

class RegisterContextUnwind : public lldb_private::RegisterContext {

public:

  typedef std::shared_ptr<RegisterContextUnwind> SharedPtr;

  RegisterContextUnwind(lldb_private::Thread &thread,

                        const SharedPtr &next_frame,

                        lldb_private::SymbolContext &sym_ctx,

                        uint32_t frame_number,

                        lldb_private::UnwindLLDB &unwind_lldb);

  ~RegisterContextUnwind() override = default;

  void InvalidateAllRegisters() override;

  size_t GetRegisterCount() override;

  const lldb_private::RegisterInfo *GetRegisterInfoAtIndex(size_t reg) override;

  size_t GetRegisterSetCount() override;

  const lldb_private::RegisterSet *GetRegisterSet(size_t reg_set) override;

  bool ReadRegister(const lldb_private::RegisterInfo *reg_info,

                    lldb_private::RegisterValue &value) override;

  bool WriteRegister(const lldb_private::RegisterInfo *reg_info,

                     const lldb_private::RegisterValue &value) override;

  bool ReadAllRegisterValues(lldb::WritableDataBufferSP &data_sp) override;

  bool WriteAllRegisterValues(const lldb::DataBufferSP &data_sp) override;

  uint32_t ConvertRegisterKindToRegisterNumber(lldb::RegisterKind kind,

                                               uint32_t num) override;

  bool IsValid() const;

  bool IsTrapHandlerFrame() const;

  bool GetCFA(lldb::addr_t &cfa);

  bool GetStartPC(lldb::addr_t &start_pc);

  bool ReadPC(lldb::addr_t &start_pc);

  // Indicates whether this frame *behaves* like frame zero -- the currently

  // executing frame -- or not.  This can be true in the middle of the stack

  // above asynchronous trap handlers (sigtramp) for instance.

  bool BehavesLikeZerothFrame() const override;

private:

  enum FrameType {

    eNormalFrame,

    eTrapHandlerFrame,

    eDebuggerFrame, // a debugger inferior function call frame; we get caller's

                    // registers from debugger

    eSkipFrame,     // The unwind resulted in a bogus frame but may get back on

                    // track so we don't want to give up yet

    eNotAValidFrame // this frame is invalid for some reason - most likely it is

                    // past the top (end) of the stack

  };

  // UnwindLLDB needs to pass around references to RegisterLocations

  friend class UnwindLLDB;

  // Returns true if we have an unwind loop -- the same stack frame unwinding

  // multiple times.

  bool CheckIfLoopingStack();

  // Indicates whether this frame is frame zero -- the currently

  // executing frame -- or not.

  bool IsFrameZero() const;

  void InitializeZerothFrame();

  void InitializeNonZerothFrame();

  SharedPtr GetNextFrame() const;

  SharedPtr GetPrevFrame() const;

  // A SkipFrame occurs when the unwind out of frame 0 didn't go right -- we've

  // got one bogus frame at frame #1.

  // There is a good chance we'll get back on track if we follow the frame

  // pointer chain (or whatever is appropriate

  // on this ABI) so we allow one invalid frame to be in the stack.  Ideally

  // we'll mark this frame specially at some

  // point and indicate to the user that the unwinder had a hiccup.  Often when

  // this happens we will miss a frame of

  // the program's actual stack in the unwind and we want to flag that for the

  // user somehow.

  bool IsSkipFrame() const;

  /// Determines if a SymbolContext is a trap handler or not

  ///

  /// Given a SymbolContext, determines if this is a trap handler function

  /// aka asynchronous signal handler.

  ///

  /// \return

  ///     Returns true if the SymbolContext is a trap handler.

  bool IsTrapHandlerSymbol(lldb_private::Process *process,

                           const lldb_private::SymbolContext &m_sym_ctx) const;

  /// Check if the given unwind plan indicates a signal trap handler, and

  /// update frame type and symbol context if so.

  void PropagateTrapHandlerFlagFromUnwindPlan(lldb::UnwindPlanSP unwind_plan);

  // Provide a location for where THIS function saved the CALLER's register

  // value

  // Or a frame "below" this one saved it, i.e. a function called by this one,

  // preserved a register that this

  // function didn't modify/use.

  //

  // The RegisterLocation type may be set to eRegisterNotAvailable -- this will

  // happen for a volatile register

  // being queried mid-stack.  Instead of floating frame 0's contents of that

  // register up the stack (which may

  // or may not be the value of that reg when the function was executing), we

  // won't return any value.

  //

  // If a non-volatile register (a "preserved" register) is requested mid-stack

  // and no frames "below" the requested

  // stack have saved the register anywhere, it is safe to assume that frame 0's

  // register values are still the same

  // as the requesting frame's.

  lldb_private::UnwindLLDB::RegisterSearchResult

  SavedLocationForRegister(uint32_t lldb_regnum,

                           lldb_private::UnwindLLDB::RegisterLocation &regloc);

  bool ReadRegisterValueFromRegisterLocation(

      lldb_private::UnwindLLDB::RegisterLocation regloc,

      const lldb_private::RegisterInfo *reg_info,

      lldb_private::RegisterValue &value);

  bool WriteRegisterValueToRegisterLocation(

      lldb_private::UnwindLLDB::RegisterLocation regloc,

      const lldb_private::RegisterInfo *reg_info,

      const lldb_private::RegisterValue &value);

  /// If the unwind has to the caller frame has failed, try something else

  ///

  /// If lldb is using an assembly language based UnwindPlan for a frame and

  /// the unwind to the caller frame fails, try falling back to a generic

  /// UnwindPlan (architecture default unwindplan) to see if that might work

  /// better.  This is mostly helping to work around problems where the

  /// assembly language inspection fails on hand-written assembly code.

  ///

  /// \return

  ///     Returns true if a fallback unwindplan was found & was installed.

  bool TryFallbackUnwindPlan();

  /// Switch to the fallback unwind plan unconditionally without any safety

  /// checks that it is providing better results than the normal unwind plan.

  ///

  /// The only time it is valid to call this method is if the full unwindplan is

  /// found to be fundamentally incorrect/impossible.

  ///

  /// Returns true if it was able to install the fallback unwind plan.

  bool ForceSwitchToFallbackUnwindPlan();

  // Get the contents of a general purpose (address-size) register for this

  // frame

  // (usually retrieved from the next frame)

  bool ReadGPRValue(lldb::RegisterKind register_kind, uint32_t regnum,

                    lldb::addr_t &value);

  bool ReadGPRValue(const RegisterNumber &reg_num, lldb::addr_t &value);

  // Get the Frame Address register for a given frame.

  bool ReadFrameAddress(lldb::RegisterKind register_kind,

                          UnwindPlan::Row::FAValue &fa, lldb::addr_t &address);

  lldb::UnwindPlanSP GetFastUnwindPlanForFrame();

  lldb::UnwindPlanSP GetFullUnwindPlanForFrame();

  void UnwindLogMsg(const char *fmt, ...) __attribute__((format(printf, 2, 3)));

  void UnwindLogMsgVerbose(const char *fmt, ...)

      __attribute__((format(printf, 2, 3)));

  bool IsUnwindPlanValidForCurrentPC(lldb::UnwindPlanSP unwind_plan_sp);

  lldb::addr_t GetReturnAddressHint(int32_t plan_offset);

  lldb_private::Thread &m_thread;

  ///

  // The following tell us how to retrieve the CALLER's register values (ie the

  // "previous" frame, aka the frame above)

  // i.e. where THIS frame saved them

  ///

  lldb::UnwindPlanSP m_fast_unwind_plan_sp; // may be NULL

  lldb::UnwindPlanSP m_full_unwind_plan_sp;

  lldb::UnwindPlanSP m_fallback_unwind_plan_sp; // may be NULL

  bool m_all_registers_available; // Can we retrieve all regs or just

                                  // nonvolatile regs?

  int m_frame_type;               // enum FrameType

  lldb::addr_t m_cfa;

  lldb::addr_t m_afa;

  lldb_private::Address m_start_pc;

  lldb_private::Address m_current_pc;

  int m_current_offset; // how far into the function we've executed; -1 if

                        // unknown

                        // 0 if no instructions have been executed yet.

  // 0 if no instructions have been executed yet.

  // On architectures where the return address on the stack points

  // to the instruction after the CALL, this value will have 1

  // subtracted from it.  Else a function that ends in a CALL will

  // have an offset pointing into the next function's address range.

  // m_current_pc has the actual address of the "current" pc.

  int m_current_offset_backed_up_one; // how far into the function we've

                                      // executed; -1 if unknown

  bool m_behaves_like_zeroth_frame; // this frame behaves like frame zero

  lldb_private::SymbolContext &m_sym_ctx;

  bool m_sym_ctx_valid; // if ResolveSymbolContextForAddress fails, don't try to

                        // use m_sym_ctx

  uint32_t m_frame_number; // What stack frame this RegisterContext is

  std::map<uint32_t, lldb_private::UnwindLLDB::RegisterLocation>

      m_registers; // where to find reg values for this frame

  lldb_private::UnwindLLDB &m_parent_unwind; // The UnwindLLDB that is creating

                                             // this RegisterContextUnwind

  RegisterContextUnwind(const RegisterContextUnwind &) = delete;

  const RegisterContextUnwind &

  operator=(const RegisterContextUnwind &) = delete;

};

} // namespace lldb_private

#endif // LLDB_TARGET_REGISTERCONTEXTUNWIND_H