MC/MCDisassembler/MCSymbolizer.h

0001 //===- llvm/MC/MCSymbolizer.h - MCSymbolizer class --------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // This file contains the declaration of the MCSymbolizer class, which is used
0010 // to symbolize instructions decoded from an object, that is, transform their
0011 // immediate operands to MCExprs.
0012 //
0013 //===----------------------------------------------------------------------===//
0014
0015 #ifndef LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H
0016 #define LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H
0017
0018 #include "llvm/ADT/ArrayRef.h"
0019 #include "llvm/MC/MCDisassembler/MCRelocationInfo.h"
0020 #include <cstdint>
0021 #include <memory>
0022 #include <utility>
0023
0024 namespace llvm {
0025
0026 class MCContext;
0027 class MCInst;
0028 class raw_ostream;
0029
0030 /// Symbolize and annotate disassembled instructions.
0031 ///
0032 /// For now this mimics the old symbolization logic (from both ARM and x86), that
0033 /// relied on user-provided (C API) callbacks to do the actual symbol lookup in
0034 /// the object file. This was moved to MCExternalSymbolizer.
0035 /// A better API would not rely on actually calling the two methods here from
0036 /// inside each disassembler, but would use the instr info to determine what
0037 /// operands are actually symbolizable, and in what way. I don't think this
0038 /// information exists right now.
0039 class MCSymbolizer {
0040 protected:
0041   MCContext &Ctx;
0042   std::unique_ptr<MCRelocationInfo> RelInfo;
0043
0044 public:
0045   /// Construct an MCSymbolizer, taking ownership of \p RelInfo.
0046   MCSymbolizer(MCContext &Ctx, std::unique_ptr<MCRelocationInfo> RelInfo)
0047     : Ctx(Ctx), RelInfo(std::move(RelInfo)) {
0048   }
0049
0050   MCSymbolizer(const MCSymbolizer &) = delete;
0051   MCSymbolizer &operator=(const MCSymbolizer &) = delete;
0052   virtual ~MCSymbolizer();
0053
0054   /// Try to add a symbolic operand instead of \p Value to the MCInst.
0055   ///
0056   /// Instead of having a difficult to read immediate, a symbolic operand would
0057   /// represent this immediate in a more understandable way, for instance as a
0058   /// symbol or an offset from a symbol. Relocations can also be used to enrich
0059   /// the symbolic expression.
0060   /// \param Inst      - The MCInst where to insert the symbolic operand.
0061   /// \param cStream   - Stream to print comments and annotations on.
0062   /// \param Value     - Operand value, pc-adjusted by the caller if necessary.
0063   /// \param Address   - Load address of the instruction.
0064   /// \param IsBranch  - Is the instruction a branch?
0065   /// \param Offset    - Byte offset of the operand inside the inst.
0066   /// \param OpSize    - Size of the operand in bytes.
0067   /// \param InstSize  - Size of the instruction in bytes.
0068   /// \return Whether a symbolic operand was added.
0069   virtual bool tryAddingSymbolicOperand(MCInst &Inst, raw_ostream &cStream,
0070                                         int64_t Value, uint64_t Address,
0071                                         bool IsBranch, uint64_t Offset,
0072                                         uint64_t OpSize, uint64_t InstSize) = 0;
0073
0074   /// Try to add a comment on the PC-relative load.
0075   /// For instance, in Mach-O, this is used to add annotations to instructions
0076   /// that use C string literals, as found in __cstring.
0077   virtual void tryAddingPcLoadReferenceComment(raw_ostream &cStream,
0078                                                int64_t Value,
0079                                                uint64_t Address) = 0;
0080
0081   /// Get the MCSymbolizer's list of addresses that were referenced by
0082   /// symbolizable operands but not resolved to a symbol. The caller (some
0083   /// code that is disassembling a section or other chunk of code) would
0084   /// typically create a synthetic label at each address and add them to its
0085   /// list of symbols in the section, before creating a new MCSymbolizer with
0086   /// the enhanced symbol list and retrying disassembling the section.
0087   /// The returned array is unordered and may have duplicates.
0088   /// The returned ArrayRef stops being valid on any call to or destruction of
0089   /// the MCSymbolizer object.
0090   virtual ArrayRef<uint64_t> getReferencedAddresses() const { return {}; }
0091 };
0092
0093 } // end namespace llvm
0094
0095 #endif // LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H