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
24namespace llvm {
25
26class MCContext;
27class MCInst;
28class 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.
39class MCSymbolizer {
40protected:
41 MCContext &Ctx;
42 std::unique_ptr<MCRelocationInfo> RelInfo;
43
44public:
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 tryAddingPcLoadReferenceComment(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

source code of llvm/include/llvm/MC/MCDisassembler/MCSymbolizer.h