1 //===--- DWARFExpression.h - DWARF Expression handling ----------*- 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_DEBUGINFO_DWARF_DWARFEXPRESSION_H
10 #define LLVM_DEBUGINFO_DWARF_DWARFEXPRESSION_H
11 
12 #include "llvm/ADT/Optional.h"
13 #include "llvm/ADT/StringRef.h"
14 #include "llvm/ADT/iterator.h"
15 #include "llvm/BinaryFormat/Dwarf.h"
16 #include "llvm/Support/DataExtractor.h"
17 
18 namespace llvm {
19 class DWARFUnit;
20 struct DIDumpOptions;
21 class MCRegisterInfo;
22 class raw_ostream;
23 
24 class DWARFExpression {
25 public:
26   class iterator;
27 
28   /// This class represents an Operation in the Expression. Each operation can
29   /// have up to 2 oprerands.
30   ///
31   /// An Operation can be in Error state (check with isError()). This
32   /// means that it couldn't be decoded successfully and if it is the
33   /// case, all others fields contain undefined values.
34   class Operation {
35   public:
36     /// Size and signedness of expression operations' operands.
37     enum Encoding : uint8_t {
38       Size1 = 0,
39       Size2 = 1,
40       Size4 = 2,
41       Size8 = 3,
42       SizeLEB = 4,
43       SizeAddr = 5,
44       SizeRefAddr = 6,
45       SizeBlock = 7, ///< Preceding operand contains block size
46       BaseTypeRef = 8,
47       WasmLocationArg = 30,
48       SignBit = 0x80,
49       SignedSize1 = SignBit | Size1,
50       SignedSize2 = SignBit | Size2,
51       SignedSize4 = SignBit | Size4,
52       SignedSize8 = SignBit | Size8,
53       SignedSizeLEB = SignBit | SizeLEB,
54       SizeNA = 0xFF ///< Unused operands get this encoding.
55     };
56 
57     enum DwarfVersion : uint8_t {
58       DwarfNA, ///< Serves as a marker for unused entries
59       Dwarf2 = 2,
60       Dwarf3,
61       Dwarf4,
62       Dwarf5
63     };
64 
65     /// Description of the encoding of one expression Op.
66     struct Description {
67       DwarfVersion Version; ///< Dwarf version where the Op was introduced.
68       Encoding Op[2];       ///< Encoding for Op operands, or SizeNA.
69 
70       Description(DwarfVersion Version = DwarfNA, Encoding Op1 = SizeNA,
71                   Encoding Op2 = SizeNA)
72           : Version(Version) {
73         Op[0] = Op1;
74         Op[1] = Op2;
75       }
76     };
77 
78   private:
79     friend class DWARFExpression::iterator;
80     uint8_t Opcode; ///< The Op Opcode, DW_OP_<something>.
81     Description Desc;
82     bool Error = false;
83     uint64_t EndOffset;
84     uint64_t Operands[2];
85     uint64_t OperandEndOffsets[2];
86 
87   public:
88     const Description &getDescription() const { return Desc; }
89     uint8_t getCode() const { return Opcode; }
90     uint64_t getRawOperand(unsigned Idx) const { return Operands[Idx]; }
91     uint64_t getOperandEndOffset(unsigned Idx) const {
92       return OperandEndOffsets[Idx];
93     }
94     uint64_t getEndOffset() const { return EndOffset; }
95     bool isError() const { return Error; }
96     bool print(raw_ostream &OS, DIDumpOptions DumpOpts,
97                const DWARFExpression *Expr, const MCRegisterInfo *RegInfo,
98                DWARFUnit *U, bool isEH) const;
99 
100     /// Verify \p Op. Does not affect the return of \a isError().
101     static bool verify(const Operation &Op, DWARFUnit *U);
102 
103   private:
104     bool extract(DataExtractor Data, uint8_t AddressSize, uint64_t Offset,
105                  Optional<dwarf::DwarfFormat> Format);
106   };
107 
108   /// An iterator to go through the expression operations.
109   class iterator
110       : public iterator_facade_base<iterator, std::forward_iterator_tag,
111                                     const Operation> {
112     friend class DWARFExpression;
113     const DWARFExpression *Expr;
114     uint64_t Offset;
115     Operation Op;
116     iterator(const DWARFExpression *Expr, uint64_t Offset)
117         : Expr(Expr), Offset(Offset) {
118       Op.Error =
119           Offset >= Expr->Data.getData().size() ||
120           !Op.extract(Expr->Data, Expr->AddressSize, Offset, Expr->Format);
121     }
122 
123   public:
124     iterator &operator++() {
125       Offset = Op.isError() ? Expr->Data.getData().size() : Op.EndOffset;
126       Op.Error =
127           Offset >= Expr->Data.getData().size() ||
128           !Op.extract(Expr->Data, Expr->AddressSize, Offset, Expr->Format);
129       return *this;
130     }
131 
132     const Operation &operator*() const { return Op; }
133 
134     iterator skipBytes(uint64_t Add) const {
135       return iterator(Expr, Op.EndOffset + Add);
136     }
137 
138     // Comparison operators are provided out of line.
139     friend bool operator==(const iterator &, const iterator &);
140   };
141 
142   DWARFExpression(DataExtractor Data, uint8_t AddressSize,
143                   Optional<dwarf::DwarfFormat> Format = None)
144       : Data(Data), AddressSize(AddressSize), Format(Format) {
145     assert(AddressSize == 8 || AddressSize == 4 || AddressSize == 2);
146   }
147 
148   iterator begin() const { return iterator(this, 0); }
149   iterator end() const { return iterator(this, Data.getData().size()); }
150 
151   void print(raw_ostream &OS, DIDumpOptions DumpOpts,
152              const MCRegisterInfo *RegInfo, DWARFUnit *U,
153              bool IsEH = false) const;
154 
155   /// Print the expression in a format intended to be compact and useful to a
156   /// user, but not perfectly unambiguous, or capable of representing every
157   /// valid DWARF expression. Returns true if the expression was sucessfully
158   /// printed.
159   bool printCompact(raw_ostream &OS, const MCRegisterInfo &RegInfo);
160 
161   bool verify(DWARFUnit *U);
162 
163   bool operator==(const DWARFExpression &RHS) const;
164 
165   StringRef getData() const { return Data.getData(); }
166 
167 private:
168   DataExtractor Data;
169   uint8_t AddressSize;
170   Optional<dwarf::DwarfFormat> Format;
171 };
172 
173 inline bool operator==(const DWARFExpression::iterator &LHS,
174                        const DWARFExpression::iterator &RHS) {
175   return LHS.Expr == RHS.Expr && LHS.Offset == RHS.Offset;
176 }
177 }
178 #endif
179