include/llvm/MC/MCDisassembler/MCSymbolizer.h

   1 //===- llvm/MC/MCSymbolizer.h - MCSymbolizer class --------------*- 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 // This file contains the declaration of the MCSymbolizer class, which is used
  10 // to symbolize instructions decoded from an object, that is, transform their
  11 // immediate operands to MCExprs.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H
  16 #define LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H
  17
  18 #include "llvm/MC/MCDisassembler/MCRelocationInfo.h"
  19 #include <algorithm>
  20 #include <cstdint>
  21 #include <memory>
  22
  23 namespace llvm {
  24
  25 class MCContext;
  26 class MCInst;
  27 class raw_ostream;
  28
  29 /// Symbolize and annotate disassembled instructions.
  30 ///
  31 /// For now this mimics the old symbolization logic (from both ARM and x86), that
  32 /// relied on user-provided (C API) callbacks to do the actual symbol lookup in
  33 /// the object file. This was moved to MCExternalSymbolizer.
  34 /// A better API would not rely on actually calling the two methods here from
  35 /// inside each disassembler, but would use the instr info to determine what
  36 /// operands are actually symbolizable, and in what way. I don't think this
  37 /// information exists right now.
  38 class MCSymbolizer {
  39 protected:
  40   MCContext &Ctx;
  41   std::unique_ptr<MCRelocationInfo> RelInfo;
  42
  43 public:
  44   /// Construct an MCSymbolizer, taking ownership of \p RelInfo.
  45   MCSymbolizer(MCContext &Ctx, std::unique_ptr<MCRelocationInfo> RelInfo)
  46     : Ctx(Ctx), RelInfo(std::move(RelInfo)) {
  47   }
  48
  49   MCSymbolizer(const MCSymbolizer &) = delete;
  50   MCSymbolizer &operator=(const MCSymbolizer &) = delete;
  51   virtual ~MCSymbolizer();
  52
  53   /// Try to add a symbolic operand instead of \p Value to the MCInst.
  54   ///
  55   /// Instead of having a difficult to read immediate, a symbolic operand would
  56   /// represent this immediate in a more understandable way, for instance as a
  57   /// symbol or an offset from a symbol. Relocations can also be used to enrich
  58   /// the symbolic expression.
  59   /// \param Inst      - The MCInst where to insert the symbolic operand.
  60   /// \param cStream   - Stream to print comments and annotations on.
  61   /// \param Value     - Operand value, pc-adjusted by the caller if necessary.
  62   /// \param Address   - Load address of the instruction.
  63   /// \param IsBranch  - Is the instruction a branch?
  64   /// \param Offset    - Byte offset of the operand inside the inst.
  65   /// \param InstSize  - Size of the instruction in bytes.
  66   /// \return Whether a symbolic operand was added.
  67   virtual bool tryAddingSymbolicOperand(MCInst &Inst, raw_ostream &cStream,
  68                                         int64_t Value, uint64_t Address,
  69                                         bool IsBranch, uint64_t Offset,
  70                                         uint64_t InstSize) = 0;
  71
  72   /// Try to add a comment on the PC-relative load.
  73   /// For instance, in Mach-O, this is used to add annotations to instructions
  74   /// that use C string literals, as found in __cstring.
  75   virtual void tryAddingPcLoadReferenceComment(raw_ostream &cStream,
  76                                                int64_t Value,
  77                                                uint64_t Address) = 0;
  78 };
  79
  80 } // end namespace llvm
  81
  82 #endif // LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H