LLVM  13.0.0git
MCSymbolizer.h
Go to the documentation of this file.
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/ADT/ArrayRef.h"
20 #include <algorithm>
21 #include <cstdint>
22 #include <memory>
23 
24 namespace llvm {
25 
26 class MCContext;
27 class MCInst;
28 class raw_ostream;
29 
30 /// Symbolize and annotate disassembled instructions.
31 ///
32 /// For now this mimics the old symbolization logic (from both ARM and x86), that
33 /// relied on user-provided (C API) callbacks to do the actual symbol lookup in
34 /// the object file. This was moved to MCExternalSymbolizer.
35 /// A better API would not rely on actually calling the two methods here from
36 /// inside each disassembler, but would use the instr info to determine what
37 /// operands are actually symbolizable, and in what way. I don't think this
38 /// information exists right now.
39 class MCSymbolizer {
40 protected:
42  std::unique_ptr<MCRelocationInfo> RelInfo;
43 
44 public:
45  /// Construct an MCSymbolizer, taking ownership of \p RelInfo.
46  MCSymbolizer(MCContext &Ctx, std::unique_ptr<MCRelocationInfo> RelInfo)
47  : Ctx(Ctx), RelInfo(std::move(RelInfo)) {
48  }
49 
50  MCSymbolizer(const MCSymbolizer &) = delete;
51  MCSymbolizer &operator=(const MCSymbolizer &) = delete;
52  virtual ~MCSymbolizer();
53 
54  /// Try to add a symbolic operand instead of \p Value to the MCInst.
55  ///
56  /// Instead of having a difficult to read immediate, a symbolic operand would
57  /// represent this immediate in a more understandable way, for instance as a
58  /// symbol or an offset from a symbol. Relocations can also be used to enrich
59  /// the symbolic expression.
60  /// \param Inst - The MCInst where to insert the symbolic operand.
61  /// \param cStream - Stream to print comments and annotations on.
62  /// \param Value - Operand value, pc-adjusted by the caller if necessary.
63  /// \param Address - Load address of the instruction.
64  /// \param IsBranch - Is the instruction a branch?
65  /// \param Offset - Byte offset of the operand inside the inst.
66  /// \param InstSize - Size of the instruction in bytes.
67  /// \return Whether a symbolic operand was added.
68  virtual bool tryAddingSymbolicOperand(MCInst &Inst, raw_ostream &cStream,
69  int64_t Value, uint64_t Address,
70  bool IsBranch, uint64_t Offset,
71  uint64_t InstSize) = 0;
72 
73  /// Try to add a comment on the PC-relative load.
74  /// For instance, in Mach-O, this is used to add annotations to instructions
75  /// that use C string literals, as found in __cstring.
76  virtual void tryAddingPcLoadReferenceComment(raw_ostream &cStream,
77  int64_t Value,
78  uint64_t Address) = 0;
79 
80  /// Get the MCSymbolizer's list of addresses that were referenced by
81  /// symbolizable operands but not resolved to a symbol. The caller (some
82  /// code that is disassembling a section or other chunk of code) would
83  /// typically create a synthetic label at each address and add them to its
84  /// list of symbols in the section, before creating a new MCSymbolizer with
85  /// the enhanced symbol list and retrying disassembling the section.
86  /// The returned array is unordered and may have duplicates.
87  /// The returned ArrayRef stops being valid on any call to or destruction of
88  /// the MCSymbolizer object.
89  virtual ArrayRef<uint64_t> getReferencedAddresses() const { return {}; }
90 };
91 
92 } // end namespace llvm
93 
94 #endif // LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H
llvm
Definition: AllocatorList.h:23
llvm::MCSymbolizer::Ctx
MCContext & Ctx
Definition: MCSymbolizer.h:41
llvm::MCContext
Context object for machine code objects.
Definition: MCContext.h:71
llvm::MCSymbolizer::getReferencedAddresses
virtual ArrayRef< uint64_t > getReferencedAddresses() const
Get the MCSymbolizer's list of addresses that were referenced by symbolizable operands but not resolv...
Definition: MCSymbolizer.h:89
Offset
uint64_t Offset
Definition: ELFObjHandler.cpp:81
llvm::MCInst
Instances of this class represent a single low-level machine instruction.
Definition: MCInst.h:183
llvm::MCSymbolizer
Symbolize and annotate disassembled instructions.
Definition: MCSymbolizer.h:39
llvm::MCSymbolizer::MCSymbolizer
MCSymbolizer(MCContext &Ctx, std::unique_ptr< MCRelocationInfo > RelInfo)
Construct an MCSymbolizer, taking ownership of RelInfo.
Definition: MCSymbolizer.h:46
llvm::raw_ostream
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:50
llvm::MCSymbolizer::~MCSymbolizer
virtual ~MCSymbolizer()
ArrayRef.h
llvm::move
OutputIt move(R &&Range, OutputIt Out)
Provide wrappers to std::move which take ranges instead of having to pass begin/end explicitly.
Definition: STLExtras.h:1540
llvm::ArrayRef< uint64_t >
llvm::MCSymbolizer::RelInfo
std::unique_ptr< MCRelocationInfo > RelInfo
Definition: MCSymbolizer.h:42
std
Definition: BitVector.h:838
MCRelocationInfo.h
llvm::MCSymbolizer::operator=
MCSymbolizer & operator=(const MCSymbolizer &)=delete
llvm::MCSymbolizer::tryAddingSymbolicOperand
virtual bool tryAddingSymbolicOperand(MCInst &Inst, raw_ostream &cStream, int64_t Value, uint64_t Address, bool IsBranch, uint64_t Offset, uint64_t InstSize)=0
Try to add a symbolic operand instead of Value to the MCInst.
llvm::Value
LLVM Value Representation.
Definition: Value.h:75
llvm::MCSymbolizer::tryAddingPcLoadReferenceComment
virtual void tryAddingPcLoadReferenceComment(raw_ostream &cStream, int64_t Value, uint64_t Address)=0
Try to add a comment on the PC-relative load.