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" |
19 | #include "llvm/MC/MCDisassembler/MCRelocationInfo.h" |
20 | #include <cstdint> |
21 | #include <memory> |
22 | #include <utility> |
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: |
41 | MCContext &Ctx; |
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 OpSize - Size of the operand in bytes. |
67 | /// \param InstSize - Size of the instruction in bytes. |
68 | /// \return Whether a symbolic operand was added. |
69 | virtual bool tryAddingSymbolicOperand(MCInst &Inst, raw_ostream &cStream, |
70 | int64_t Value, uint64_t Address, |
71 | bool IsBranch, uint64_t Offset, |
72 | uint64_t OpSize, uint64_t InstSize) = 0; |
73 | |
74 | /// Try to add a comment on the PC-relative load. |
75 | /// For instance, in Mach-O, this is used to add annotations to instructions |
76 | /// that use C string literals, as found in __cstring. |
77 | virtual void (raw_ostream &cStream, |
78 | int64_t Value, |
79 | uint64_t Address) = 0; |
80 | |
81 | /// Get the MCSymbolizer's list of addresses that were referenced by |
82 | /// symbolizable operands but not resolved to a symbol. The caller (some |
83 | /// code that is disassembling a section or other chunk of code) would |
84 | /// typically create a synthetic label at each address and add them to its |
85 | /// list of symbols in the section, before creating a new MCSymbolizer with |
86 | /// the enhanced symbol list and retrying disassembling the section. |
87 | /// The returned array is unordered and may have duplicates. |
88 | /// The returned ArrayRef stops being valid on any call to or destruction of |
89 | /// the MCSymbolizer object. |
90 | virtual ArrayRef<uint64_t> getReferencedAddresses() const { return {}; } |
91 | }; |
92 | |
93 | } // end namespace llvm |
94 | |
95 | #endif // LLVM_MC_MCDISASSEMBLER_MCSYMBOLIZER_H |
96 | |