LLVM 20.0.0git
MCDisassembler.h
Go to the documentation of this file.
1//===- llvm/MC/MCDisassembler.h - Disassembler interface --------*- 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#ifndef LLVM_MC_MCDISASSEMBLER_MCDISASSEMBLER_H
10#define LLVM_MC_MCDISASSEMBLER_MCDISASSEMBLER_H
11
12#include "llvm/ADT/StringRef.h"
15#include "llvm/Support/Error.h"
16#include <cstdint>
17#include <memory>
18#include <vector>
19
20namespace llvm {
21
23 std::optional<XCOFF::StorageMappingClass> StorageMappingClass;
24 std::optional<uint32_t> Index;
25 bool IsLabel = false;
26 bool operator<(const XCOFFSymbolInfoTy &SymInfo) const;
27};
28
32 // XCOFF uses XCOFFSymInfo. Other targets use Type.
34 uint8_t Type;
35 // Used by ELF to describe a mapping symbol that is usually not displayed.
37
38private:
39 bool IsXCOFF;
40 bool HasType;
41
42public:
43 SymbolInfoTy(std::optional<XCOFF::StorageMappingClass> Smc, uint64_t Addr,
44 StringRef Name, std::optional<uint32_t> Idx, bool Label)
45 : Addr(Addr), Name(Name), XCOFFSymInfo{Smc, Idx, Label}, Type(0),
46 IsMappingSymbol(false), IsXCOFF(true), HasType(false) {}
48 bool IsMappingSymbol = false, bool IsXCOFF = false)
50 IsXCOFF(IsXCOFF), HasType(true) {}
51 bool isXCOFF() const { return IsXCOFF; }
52
53private:
54 friend bool operator<(const SymbolInfoTy &P1, const SymbolInfoTy &P2) {
55 assert((P1.IsXCOFF == P2.IsXCOFF && P1.HasType == P2.HasType) &&
56 "The value of IsXCOFF and HasType in P1 and P2 should be the same "
57 "respectively.");
58
59 if (P1.IsXCOFF && P1.HasType)
60 return std::tie(P1.Addr, P1.Type, P1.Name) <
61 std::tie(P2.Addr, P2.Type, P2.Name);
62
63 if (P1.IsXCOFF)
64 return std::tie(P1.Addr, P1.XCOFFSymInfo, P1.Name) <
65 std::tie(P2.Addr, P2.XCOFFSymInfo, P2.Name);
66
67 // With the same address, place mapping symbols first.
68 bool MS1 = !P1.IsMappingSymbol, MS2 = !P2.IsMappingSymbol;
69 return std::tie(P1.Addr, MS1, P1.Name, P1.Type) <
70 std::tie(P2.Addr, MS2, P2.Name, P2.Type);
71 }
72};
73
74using SectionSymbolsTy = std::vector<SymbolInfoTy>;
75
76template <typename T> class ArrayRef;
77class MCContext;
78class MCInst;
79class MCSubtargetInfo;
80class raw_ostream;
81
82/// Superclass for all disassemblers. Consumes a memory region and provides an
83/// array of assembly instructions.
85public:
86 /// Ternary decode status. Most backends will just use Fail and
87 /// Success, however some have a concept of an instruction with
88 /// understandable semantics but which is architecturally
89 /// incorrect. An example of this is ARM UNPREDICTABLE instructions
90 /// which are disassemblable but cause undefined behaviour.
91 ///
92 /// Because it makes sense to disassemble these instructions, there
93 /// is a "soft fail" failure mode that indicates the MCInst& is
94 /// valid but architecturally incorrect.
95 ///
96 /// The enum numbers are deliberately chosen such that reduction
97 /// from Success->SoftFail ->Fail can be done with a simple
98 /// bitwise-AND:
99 ///
100 /// LEFT & TOP = | Success Unpredictable Fail
101 /// --------------+-----------------------------------
102 /// Success | Success Unpredictable Fail
103 /// Unpredictable | Unpredictable Unpredictable Fail
104 /// Fail | Fail Fail Fail
105 ///
106 /// An easy way of encoding this is as 0b11, 0b01, 0b00 for
107 /// Success, SoftFail, Fail respectively.
109 Fail = 0,
111 Success = 3
112 };
113
115 : Ctx(Ctx), STI(STI) {}
116
118
119 /// Returns the disassembly of a single instruction.
120 ///
121 /// \param Instr - An MCInst to populate with the contents of the
122 /// instruction.
123 /// \param Size - A value to populate with the size of the instruction, or
124 /// the number of bytes consumed while attempting to decode
125 /// an invalid instruction.
126 /// \param Address - The address, in the memory space of region, of the first
127 /// byte of the instruction.
128 /// \param Bytes - A reference to the actual bytes of the instruction.
129 /// \param CStream - The stream to print comments and annotations on.
130 /// \return - MCDisassembler::Success if the instruction is valid,
131 /// MCDisassembler::SoftFail if the instruction was
132 /// disassemblable but invalid,
133 /// MCDisassembler::Fail if the instruction was invalid.
136 raw_ostream &CStream) const = 0;
137
138 /// Used to perform separate target specific disassembly for a particular
139 /// symbol. May parse any prelude that precedes instructions after the
140 /// start of a symbol, or the entire symbol.
141 /// This is used for example by WebAssembly to decode preludes.
142 ///
143 /// Base implementation returns false. So all targets by default decline to
144 /// treat symbols separately.
145 ///
146 /// \param Symbol - The symbol.
147 /// \param Size - The number of bytes consumed.
148 /// \param Address - The address, in the memory space of region, of the first
149 /// byte of the symbol.
150 /// \param Bytes - A reference to the actual bytes at the symbol location.
151 /// \return - True if this symbol triggered some target specific
152 /// disassembly for this symbol. Size must be set with the
153 /// number of bytes consumed.
154 /// - Error if this symbol triggered some target specific
155 /// disassembly for this symbol, but an error was found with
156 /// it. Size must be set with the number of bytes consumed.
157 /// - False if the target doesn't want to handle the symbol
158 /// separately. The value of Size is ignored in this case,
159 /// and Err must not be set.
161 ArrayRef<uint8_t> Bytes,
162 uint64_t Address) const;
163 // TODO:
164 // Implement similar hooks that can be used at other points during
165 // disassembly. Something along the following lines:
166 // - onBeforeInstructionDecode()
167 // - onAfterInstructionDecode()
168 // - onSymbolEnd()
169 // It should help move much of the target specific code from llvm-objdump to
170 // respective target disassemblers.
171
172 /// Suggest a distance to skip in a buffer of data to find the next
173 /// place to look for the start of an instruction. For example, if
174 /// all instructions have a fixed alignment, this might advance to
175 /// the next multiple of that alignment.
176 ///
177 /// If not overridden, the default is 1.
178 ///
179 /// \param Address - The address, in the memory space of region, of the
180 /// starting point (typically the first byte of something
181 /// that did not decode as a valid instruction at all).
182 /// \param Bytes - A reference to the actual bytes at Address. May be
183 /// needed in order to determine the width of an
184 /// unrecognized instruction (e.g. in Thumb this is a simple
185 /// consistent criterion that doesn't require knowing the
186 /// specific instruction). The caller can pass as much data
187 /// as they have available, and the function is required to
188 /// make a reasonable default choice if not enough data is
189 /// available to make a better one.
190 /// \return - A number of bytes to skip. Must always be greater than
191 /// zero. May be greater than the size of Bytes.
193 uint64_t Address) const;
194
195private:
196 MCContext &Ctx;
197
198protected:
199 // Subtarget information, for instruction decoding predicates if required.
201 std::unique_ptr<MCSymbolizer> Symbolizer;
202
203public:
204 // Helpers around MCSymbolizer
206 bool IsBranch, uint64_t Offset, uint64_t OpSize,
207 uint64_t InstSize) const;
208
210
211 /// Set \p Symzer as the current symbolizer.
212 /// This takes ownership of \p Symzer, and deletes the previously set one.
213 void setSymbolizer(std::unique_ptr<MCSymbolizer> Symzer);
214
215 MCContext& getContext() const { return Ctx; }
216
217 const MCSubtargetInfo& getSubtargetInfo() const { return STI; }
218
219 /// ELF-specific, set the ABI version from the object header.
220 virtual void setABIVersion(unsigned Version) {}
221
222 // Marked mutable because we cache it inside the disassembler, rather than
223 // having to pass it around as an argument through all the autogenerated code.
224 mutable raw_ostream *CommentStream = nullptr;
225};
226
227} // end namespace llvm
228
229#endif // LLVM_MC_MCDISASSEMBLER_MCDISASSEMBLER_H
basic Basic Alias true
Returns the sub type a function will return at a given Idx Should correspond to the result type of an ExtractValue instruction executed with just that one unsigned Idx
uint64_t Size
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition: ArrayRef.h:41
Tagged union holding either a T or a Error.
Definition: Error.h:481
Context object for machine code objects.
Definition: MCContext.h:83
Superclass for all disassemblers.
MCDisassembler(const MCSubtargetInfo &STI, MCContext &Ctx)
virtual void setABIVersion(unsigned Version)
ELF-specific, set the ABI version from the object header.
MCContext & getContext() const
virtual Expected< bool > onSymbolStart(SymbolInfoTy &Symbol, uint64_t &Size, ArrayRef< uint8_t > Bytes, uint64_t Address) const
Used to perform separate target specific disassembly for a particular symbol.
bool tryAddingSymbolicOperand(MCInst &Inst, int64_t Value, uint64_t Address, bool IsBranch, uint64_t Offset, uint64_t OpSize, uint64_t InstSize) const
const MCSubtargetInfo & getSubtargetInfo() const
std::unique_ptr< MCSymbolizer > Symbolizer
const MCSubtargetInfo & STI
raw_ostream * CommentStream
void setSymbolizer(std::unique_ptr< MCSymbolizer > Symzer)
Set Symzer as the current symbolizer.
void tryAddingPcLoadReferenceComment(int64_t Value, uint64_t Address) const
virtual uint64_t suggestBytesToSkip(ArrayRef< uint8_t > Bytes, uint64_t Address) const
Suggest a distance to skip in a buffer of data to find the next place to look for the start of an ins...
DecodeStatus
Ternary decode status.
virtual DecodeStatus getInstruction(MCInst &Instr, uint64_t &Size, ArrayRef< uint8_t > Bytes, uint64_t Address, raw_ostream &CStream) const =0
Returns the disassembly of a single instruction.
virtual ~MCDisassembler()
Instances of this class represent a single low-level machine instruction.
Definition: MCInst.h:184
Generic base class for all target subtargets.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
The instances of the Type class are immutable: once they are created, they are never changed.
Definition: Type.h:45
LLVM Value Representation.
Definition: Value.h:74
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
@ Offset
Definition: DWP.cpp:480
std::vector< SymbolInfoTy > SectionSymbolsTy
SymInfo contains information about symbol: it's address and section index which is -1LL for absolute ...
SymbolInfoTy(std::optional< XCOFF::StorageMappingClass > Smc, uint64_t Addr, StringRef Name, std::optional< uint32_t > Idx, bool Label)
SymbolInfoTy(uint64_t Addr, StringRef Name, uint8_t Type, bool IsMappingSymbol=false, bool IsXCOFF=false)
XCOFFSymbolInfoTy XCOFFSymInfo
friend bool operator<(const SymbolInfoTy &P1, const SymbolInfoTy &P2)
bool isXCOFF() const
bool operator<(const XCOFFSymbolInfoTy &SymInfo) const
The function is for symbol sorting when symbols have the same address.
std::optional< uint32_t > Index
std::optional< XCOFF::StorageMappingClass > StorageMappingClass