contrib/llvm-project/lldb/include/lldb/Core/Disassembler.h

   1 //===-- Disassembler.h ------------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef liblldb_Disassembler_h_
  10 #define liblldb_Disassembler_h_
  11
  12 #include "lldb/Core/Address.h"
  13 #include "lldb/Core/EmulateInstruction.h"
  14 #include "lldb/Core/FormatEntity.h"
  15 #include "lldb/Core/Opcode.h"
  16 #include "lldb/Core/PluginInterface.h"
  17 #include "lldb/Interpreter/OptionValue.h"
  18 #include "lldb/Symbol/LineEntry.h"
  19 #include "lldb/Target/ExecutionContext.h"
  20 #include "lldb/Utility/ArchSpec.h"
  21 #include "lldb/Utility/ConstString.h"
  22 #include "lldb/Utility/FileSpec.h"
  23 #include "lldb/lldb-defines.h"
  24 #include "lldb/lldb-forward.h"
  25 #include "lldb/lldb-private-enumerations.h"
  26 #include "lldb/lldb-types.h"
  27
  28 #include "llvm/ADT/StringRef.h"
  29
  30 #include <functional>
  31 #include <map>
  32 #include <memory>
  33 #include <set>
  34 #include <string>
  35 #include <vector>
  36
  37 #include <stddef.h>
  38 #include <stdint.h>
  39 #include <stdio.h>
  40
  41 namespace llvm {
  42 template <typename T> class SmallVectorImpl;
  43 }
  44
  45 namespace lldb_private {
  46 class AddressRange;
  47 class DataExtractor;
  48 class Debugger;
  49 class Disassembler;
  50 class Module;
  51 class Stream;
  52 class SymbolContext;
  53 class SymbolContextList;
  54 class Target;
  55 struct RegisterInfo;
  56
  57 class Instruction {
  58 public:
  59   Instruction(const Address &address,
  60               AddressClass addr_class = AddressClass::eInvalid);
  61
  62   virtual ~Instruction();
  63
  64   const Address &GetAddress() const { return m_address; }
  65
  66   const char *GetMnemonic(const ExecutionContext *exe_ctx) {
  67     CalculateMnemonicOperandsAndCommentIfNeeded(exe_ctx);
  68     return m_opcode_name.c_str();
  69   }
  70
  71   const char *GetOperands(const ExecutionContext *exe_ctx) {
  72     CalculateMnemonicOperandsAndCommentIfNeeded(exe_ctx);
  73     return m_mnemonics.c_str();
  74   }
  75
  76   const char *GetComment(const ExecutionContext *exe_ctx) {
  77     CalculateMnemonicOperandsAndCommentIfNeeded(exe_ctx);
  78     return m_comment.c_str();
  79   }
  80
  81   virtual void
  82   CalculateMnemonicOperandsAndComment(const ExecutionContext *exe_ctx) = 0;
  83
  84   AddressClass GetAddressClass();
  85
  86   void SetAddress(const Address &addr) {
  87     // Invalidate the address class to lazily discover it if we need to.
  88     m_address_class = AddressClass::eInvalid;
  89     m_address = addr;
  90   }
  91
  92   /// Dump the text representation of this Instruction to a Stream
  93   ///
  94   /// Print the (optional) address, (optional) bytes, opcode,
  95   /// operands, and instruction comments to a stream.
  96   ///
  97   /// \param[in] s
  98   ///     The Stream to add the text to.
  99   ///
 100   /// \param[in] show_address
 101   ///     Whether the address (using disassembly_addr_format_spec formatting)
 102   ///     should be printed.
 103   ///
 104   /// \param[in] show_bytes
 105   ///     Whether the bytes of the assembly instruction should be printed.
 106   ///
 107   /// \param[in] max_opcode_byte_size
 108   ///     The size (in bytes) of the largest instruction in the list that
 109   ///     we are printing (for text justification/alignment purposes)
 110   ///     Only needed if show_bytes is true.
 111   ///
 112   /// \param[in] exe_ctx
 113   ///     The current execution context, if available.  May be used in
 114   ///     the assembling of the operands+comments for this instruction.
 115   ///     Pass NULL if not applicable.
 116   ///
 117   /// \param[in] sym_ctx
 118   ///     The SymbolContext for this instruction.
 119   ///     Pass NULL if not available/computed.
 120   ///     Only needed if show_address is true.
 121   ///
 122   /// \param[in] prev_sym_ctx
 123   ///     The SymbolContext for the previous instruction.  Depending on
 124   ///     the disassembly address format specification, a change in
 125   ///     Symbol / Function may mean that a line is printed with the new
 126   ///     symbol/function name.
 127   ///     Pass NULL if unavailable, or if this is the first instruction of
 128   ///     the InstructionList.
 129   ///     Only needed if show_address is true.
 130   ///
 131   /// \param[in] disassembly_addr_format
 132   ///     The format specification for how addresses are printed.
 133   ///     Only needed if show_address is true.
 134   ///
 135   /// \param[in] max_address_text_size
 136   ///     The length of the longest address string at the start of the
 137   ///     disassembly line that will be printed (the
 138   ///     Debugger::FormatDisassemblerAddress() string)
 139   ///     so this method can properly align the instruction opcodes.
 140   ///     May be 0 to indicate no indentation/alignment of the opcodes.
 141   virtual void Dump(Stream *s, uint32_t max_opcode_byte_size, bool show_address,
 142                     bool show_bytes, const ExecutionContext *exe_ctx,
 143                     const SymbolContext *sym_ctx,
 144                     const SymbolContext *prev_sym_ctx,
 145                     const FormatEntity::Entry *disassembly_addr_format,
 146                     size_t max_address_text_size);
 147
 148   virtual bool DoesBranch() = 0;
 149
 150   virtual bool HasDelaySlot();
 151
 152   bool CanSetBreakpoint ();
 153
 154   virtual size_t Decode(const Disassembler &disassembler,
 155                         const DataExtractor &data,
 156                         lldb::offset_t data_offset) = 0;
 157
 158   virtual void SetDescription(llvm::StringRef) {
 159   } // May be overridden in sub-classes that have descriptions.
 160
 161   lldb::OptionValueSP ReadArray(FILE *in_file, Stream *out_stream,
 162                                 OptionValue::Type data_type);
 163
 164   lldb::OptionValueSP ReadDictionary(FILE *in_file, Stream *out_stream);
 165
 166   bool DumpEmulation(const ArchSpec &arch);
 167
 168   virtual bool TestEmulation(Stream *stream, const char *test_file_name);
 169
 170   bool Emulate(const ArchSpec &arch, uint32_t evaluate_options, void *baton,
 171                EmulateInstruction::ReadMemoryCallback read_mem_callback,
 172                EmulateInstruction::WriteMemoryCallback write_mem_calback,
 173                EmulateInstruction::ReadRegisterCallback read_reg_callback,
 174                EmulateInstruction::WriteRegisterCallback write_reg_callback);
 175
 176   const Opcode &GetOpcode() const { return m_opcode; }
 177
 178   uint32_t GetData(DataExtractor &data);
 179
 180   struct Operand {
 181     enum class Type {
 182       Invalid = 0,
 183       Register,
 184       Immediate,
 185       Dereference,
 186       Sum,
 187       Product
 188     } m_type = Type::Invalid;
 189     std::vector<Operand> m_children;
 190     lldb::addr_t m_immediate = 0;
 191     ConstString m_register;
 192     bool m_negative = false;
 193     bool m_clobbered = false;
 194
 195     bool IsValid() { return m_type != Type::Invalid; }
 196
 197     static Operand BuildRegister(ConstString &r);
 198     static Operand BuildImmediate(lldb::addr_t imm, bool neg);
 199     static Operand BuildImmediate(int64_t imm);
 200     static Operand BuildDereference(const Operand &ref);
 201     static Operand BuildSum(const Operand &lhs, const Operand &rhs);
 202     static Operand BuildProduct(const Operand &lhs, const Operand &rhs);
 203   };
 204
 205   virtual bool ParseOperands(llvm::SmallVectorImpl<Operand> &operands) {
 206     return false;
 207   }
 208
 209   virtual bool IsCall() { return false; }
 210
 211 protected:
 212   Address m_address; // The section offset address of this instruction
 213                      // We include an address class in the Instruction class to
 214                      // allow the instruction specify the
 215                      // AddressClass::eCodeAlternateISA (currently used for
 216                      // thumb), and also to specify data (AddressClass::eData).
 217                      // The usual value will be AddressClass::eCode, but often
 218                      // when disassembling memory, you might run into data.
 219                      // This can help us to disassemble appropriately.
 220 private:
 221   AddressClass m_address_class; // Use GetAddressClass () accessor function!
 222
 223 protected:
 224   Opcode m_opcode; // The opcode for this instruction
 225   std::string m_opcode_name;
 226   std::string m_mnemonics;
 227   std::string m_comment;
 228   bool m_calculated_strings;
 229
 230   void
 231   CalculateMnemonicOperandsAndCommentIfNeeded(const ExecutionContext *exe_ctx) {
 232     if (!m_calculated_strings) {
 233       m_calculated_strings = true;
 234       CalculateMnemonicOperandsAndComment(exe_ctx);
 235     }
 236   }
 237 };
 238
 239 namespace OperandMatchers {
 240 std::function<bool(const Instruction::Operand &)>
 241 MatchBinaryOp(std::function<bool(const Instruction::Operand &)> base,
 242               std::function<bool(const Instruction::Operand &)> left,
 243               std::function<bool(const Instruction::Operand &)> right);
 244
 245 std::function<bool(const Instruction::Operand &)>
 246 MatchUnaryOp(std::function<bool(const Instruction::Operand &)> base,
 247              std::function<bool(const Instruction::Operand &)> child);
 248
 249 std::function<bool(const Instruction::Operand &)>
 250 MatchRegOp(const RegisterInfo &info);
 251
 252 std::function<bool(const Instruction::Operand &)> FetchRegOp(ConstString &reg);
 253
 254 std::function<bool(const Instruction::Operand &)> MatchImmOp(int64_t imm);
 255
 256 std::function<bool(const Instruction::Operand &)> FetchImmOp(int64_t &imm);
 257
 258 std::function<bool(const Instruction::Operand &)>
 259 MatchOpType(Instruction::Operand::Type type);
 260 }
 261
 262 class InstructionList {
 263 public:
 264   InstructionList();
 265   ~InstructionList();
 266
 267   size_t GetSize() const;
 268
 269   uint32_t GetMaxOpcocdeByteSize() const;
 270
 271   lldb::InstructionSP GetInstructionAtIndex(size_t idx) const;
 272
 273   //------------------------------------------------------------------
 274   /// Get the index of the next branch instruction.
 275   ///
 276   /// Given a list of instructions, find the next branch instruction
 277   /// in the list by returning an index.
 278   ///
 279   /// @param[in] start
 280   ///     The instruction index of the first instruction to check.
 281   ///
 282   /// @param[in] target
 283   ///     A LLDB target object that is used to resolve addresses.
 284   ///
 285   /// @param[in] ignore_calls
 286   ///     It true, then fine the first branch instruction that isn't
 287   ///     a function call (a branch that calls and returns to the next
 288   ///     instruction). If false, find the instruction index of any
 289   ///     branch in the list.
 290   ///
 291   /// @return
 292   ///     The instruction index of the first branch that is at or past
 293   ///     \a start. Returns UINT32_MAX if no matching branches are
 294   ///     found.
 295   //------------------------------------------------------------------
 296   uint32_t GetIndexOfNextBranchInstruction(uint32_t start,
 297                                            Target &target,
 298                                            bool ignore_calls) const;
 299
 300   uint32_t GetIndexOfInstructionAtLoadAddress(lldb::addr_t load_addr,
 301                                               Target &target);
 302
 303   uint32_t GetIndexOfInstructionAtAddress(const Address &addr);
 304
 305   void Clear();
 306
 307   void Append(lldb::InstructionSP &inst_sp);
 308
 309   void Dump(Stream *s, bool show_address, bool show_bytes,
 310             const ExecutionContext *exe_ctx);
 311
 312 private:
 313   typedef std::vector<lldb::InstructionSP> collection;
 314   typedef collection::iterator iterator;
 315   typedef collection::const_iterator const_iterator;
 316
 317   collection m_instructions;
 318 };
 319
 320 class PseudoInstruction : public Instruction {
 321 public:
 322   PseudoInstruction();
 323
 324   ~PseudoInstruction() override;
 325
 326   bool DoesBranch() override;
 327
 328   bool HasDelaySlot() override;
 329
 330   void CalculateMnemonicOperandsAndComment(
 331       const ExecutionContext *exe_ctx) override {
 332     // TODO: fill this in and put opcode name into Instruction::m_opcode_name,
 333     // mnemonic into Instruction::m_mnemonics, and any comment into
 334     // Instruction::m_comment
 335   }
 336
 337   size_t Decode(const Disassembler &disassembler, const DataExtractor &data,
 338                 lldb::offset_t data_offset) override;
 339
 340   void SetOpcode(size_t opcode_size, void *opcode_data);
 341
 342   void SetDescription(llvm::StringRef description) override;
 343
 344 protected:
 345   std::string m_description;
 346
 347   DISALLOW_COPY_AND_ASSIGN(PseudoInstruction);
 348 };
 349
 350 class Disassembler : public std::enable_shared_from_this<Disassembler>,
 351                      public PluginInterface {
 352 public:
 353   enum {
 354     eOptionNone = 0u,
 355     eOptionShowBytes = (1u << 0),
 356     eOptionRawOuput = (1u << 1),
 357     eOptionMarkPCSourceLine = (1u << 2), // Mark the source line that contains
 358                                          // the current PC (mixed mode only)
 359     eOptionMarkPCAddress =
 360         (1u << 3) // Mark the disassembly line the contains the PC
 361   };
 362
 363   enum HexImmediateStyle {
 364     eHexStyleC,
 365     eHexStyleAsm,
 366   };
 367
 368   // FindPlugin should be lax about the flavor string (it is too annoying to
 369   // have various internal uses of the disassembler fail because the global
 370   // flavor string gets set wrong. Instead, if you get a flavor string you
 371   // don't understand, use the default.  Folks who care to check can use the
 372   // FlavorValidForArchSpec method on the disassembler they got back.
 373   static lldb::DisassemblerSP
 374   FindPlugin(const ArchSpec &arch, const char *flavor, const char *plugin_name);
 375
 376   // This version will use the value in the Target settings if flavor is NULL;
 377   static lldb::DisassemblerSP
 378   FindPluginForTarget(const lldb::TargetSP target_sp, const ArchSpec &arch,
 379                       const char *flavor, const char *plugin_name);
 380
 381   static lldb::DisassemblerSP
 382   DisassembleRange(const ArchSpec &arch, const char *plugin_name,
 383                    const char *flavor, const ExecutionContext &exe_ctx,
 384                    const AddressRange &disasm_range, bool prefer_file_cache);
 385
 386   static lldb::DisassemblerSP
 387   DisassembleBytes(const ArchSpec &arch, const char *plugin_name,
 388                    const char *flavor, const Address &start, const void *bytes,
 389                    size_t length, uint32_t max_num_instructions,
 390                    bool data_from_file);
 391
 392   static bool Disassemble(Debugger &debugger, const ArchSpec &arch,
 393                           const char *plugin_name, const char *flavor,
 394                           const ExecutionContext &exe_ctx,
 395                           const AddressRange &range, uint32_t num_instructions,
 396                           bool mixed_source_and_assembly,
 397                           uint32_t num_mixed_context_lines, uint32_t options,
 398                           Stream &strm);
 399
 400   static bool Disassemble(Debugger &debugger, const ArchSpec &arch,
 401                           const char *plugin_name, const char *flavor,
 402                           const ExecutionContext &exe_ctx, const Address &start,
 403                           uint32_t num_instructions,
 404                           bool mixed_source_and_assembly,
 405                           uint32_t num_mixed_context_lines, uint32_t options,
 406                           Stream &strm);
 407
 408   static size_t
 409   Disassemble(Debugger &debugger, const ArchSpec &arch, const char *plugin_name,
 410               const char *flavor, const ExecutionContext &exe_ctx,
 411               SymbolContextList &sc_list, uint32_t num_instructions,
 412               bool mixed_source_and_assembly, uint32_t num_mixed_context_lines,
 413               uint32_t options, Stream &strm);
 414
 415   static bool
 416   Disassemble(Debugger &debugger, const ArchSpec &arch, const char *plugin_name,
 417               const char *flavor, const ExecutionContext &exe_ctx,
 418               ConstString name, Module *module,
 419               uint32_t num_instructions, bool mixed_source_and_assembly,
 420               uint32_t num_mixed_context_lines, uint32_t options, Stream &strm);
 421
 422   static bool
 423   Disassemble(Debugger &debugger, const ArchSpec &arch, const char *plugin_name,
 424               const char *flavor, const ExecutionContext &exe_ctx,
 425               uint32_t num_instructions, bool mixed_source_and_assembly,
 426               uint32_t num_mixed_context_lines, uint32_t options, Stream &strm);
 427
 428   // Constructors and Destructors
 429   Disassembler(const ArchSpec &arch, const char *flavor);
 430   ~Disassembler() override;
 431
 432   typedef const char *(*SummaryCallback)(const Instruction &inst,
 433                                          ExecutionContext *exe_context,
 434                                          void *user_data);
 435
 436   static bool PrintInstructions(Disassembler *disasm_ptr, Debugger &debugger,
 437                                 const ArchSpec &arch,
 438                                 const ExecutionContext &exe_ctx,
 439                                 uint32_t num_instructions,
 440                                 bool mixed_source_and_assembly,
 441                                 uint32_t num_mixed_context_lines,
 442                                 uint32_t options, Stream &strm);
 443
 444   size_t ParseInstructions(const ExecutionContext *exe_ctx,
 445                            const AddressRange &range, Stream *error_strm_ptr,
 446                            bool prefer_file_cache);
 447
 448   size_t ParseInstructions(const ExecutionContext *exe_ctx,
 449                            const Address &range, uint32_t num_instructions,
 450                            bool prefer_file_cache);
 451
 452   virtual size_t DecodeInstructions(const Address &base_addr,
 453                                     const DataExtractor &data,
 454                                     lldb::offset_t data_offset,
 455                                     size_t num_instructions, bool append,
 456                                     bool data_from_file) = 0;
 457
 458   InstructionList &GetInstructionList();
 459
 460   const InstructionList &GetInstructionList() const;
 461
 462   const ArchSpec &GetArchitecture() const { return m_arch; }
 463
 464   const char *GetFlavor() const { return m_flavor.c_str(); }
 465
 466   virtual bool FlavorValidForArchSpec(const lldb_private::ArchSpec &arch,
 467                                       const char *flavor) = 0;
 468
 469 protected:
 470   // SourceLine and SourceLinesToDisplay structures are only used in the mixed
 471   // source and assembly display methods internal to this class.
 472
 473   struct SourceLine {
 474     FileSpec file;
 475     uint32_t line;
 476     uint32_t column;
 477
 478     SourceLine() : file(), line(LLDB_INVALID_LINE_NUMBER), column(0) {}
 479
 480     bool operator==(const SourceLine &rhs) const {
 481       return file == rhs.file && line == rhs.line && rhs.column == column;
 482     }
 483
 484     bool operator!=(const SourceLine &rhs) const {
 485       return file != rhs.file || line != rhs.line || column != rhs.column;
 486     }
 487
 488     bool IsValid() const { return line != LLDB_INVALID_LINE_NUMBER; }
 489   };
 490
 491   struct SourceLinesToDisplay {
 492     std::vector<SourceLine> lines;
 493
 494     // index of the "current" source line, if we want to highlight that when
 495     // displaying the source lines.  (as opposed to the surrounding source
 496     // lines provided to give context)
 497     size_t current_source_line;
 498
 499     // Whether to print a blank line at the end of the source lines.
 500     bool print_source_context_end_eol;
 501
 502     SourceLinesToDisplay()
 503         : lines(), current_source_line(-1), print_source_context_end_eol(true) {
 504     }
 505   };
 506
 507   // Get the function's declaration line number, hopefully a line number
 508   // earlier than the opening curly brace at the start of the function body.
 509   static SourceLine GetFunctionDeclLineEntry(const SymbolContext &sc);
 510
 511   // Add the provided SourceLine to the map of filenames-to-source-lines-seen.
 512   static void AddLineToSourceLineTables(
 513       SourceLine &line,
 514       std::map<FileSpec, std::set<uint32_t>> &source_lines_seen);
 515
 516   // Given a source line, determine if we should print it when we're doing
 517   // mixed source & assembly output. We're currently using the
 518   // target.process.thread.step-avoid-regexp setting (which is used for
 519   // stepping over inlined STL functions by default) to determine what source
 520   // lines to avoid showing.
 521   //
 522   // Returns true if this source line should be elided (if the source line
 523   // should not be displayed).
 524   static bool
 525   ElideMixedSourceAndDisassemblyLine(const ExecutionContext &exe_ctx,
 526                                      const SymbolContext &sc, SourceLine &line);
 527
 528   static bool
 529   ElideMixedSourceAndDisassemblyLine(const ExecutionContext &exe_ctx,
 530                                      const SymbolContext &sc, LineEntry &line) {
 531     SourceLine sl;
 532     sl.file = line.file;
 533     sl.line = line.line;
 534     sl.column = line.column;
 535     return ElideMixedSourceAndDisassemblyLine(exe_ctx, sc, sl);
 536   };
 537
 538   // Classes that inherit from Disassembler can see and modify these
 539   ArchSpec m_arch;
 540   InstructionList m_instruction_list;
 541   lldb::addr_t m_base_addr;
 542   std::string m_flavor;
 543
 544 private:
 545   // For Disassembler only
 546   DISALLOW_COPY_AND_ASSIGN(Disassembler);
 547 };
 548
 549 } // namespace lldb_private
 550
 551 #endif // liblldb_Disassembler_h_