1 //===--- Descriptor.h - Types for the constexpr VM --------------*- 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 // Defines descriptors which characterise allocations.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_AST_INTERP_DESCRIPTOR_H
14 #define LLVM_CLANG_AST_INTERP_DESCRIPTOR_H
15 
16 #include "clang/AST/Decl.h"
17 #include "clang/AST/Expr.h"
18 
19 namespace clang {
20 namespace interp {
21 class Block;
22 class Record;
23 struct Descriptor;
24 enum PrimType : unsigned;
25 
26 using DeclTy = llvm::PointerUnion<const Decl *, const Expr *>;
27 
28 /// Invoked whenever a block is created. The constructor method fills in the
29 /// inline descriptors of all fields and array elements. It also initializes
30 /// all the fields which contain non-trivial types.
31 using BlockCtorFn = void (*)(Block *Storage, char *FieldPtr, bool IsConst,
32                              bool IsMutable, bool IsActive,
33                              const Descriptor *FieldDesc);
34 
35 /// Invoked when a block is destroyed. Invokes the destructors of all
36 /// non-trivial nested fields of arrays and records.
37 using BlockDtorFn = void (*)(Block *Storage, char *FieldPtr,
38                              const Descriptor *FieldDesc);
39 
40 /// Invoked when a block with pointers referencing it goes out of scope. Such
41 /// blocks are persisted: the move function copies all inline descriptors and
42 /// non-trivial fields, as existing pointers might need to reference those
43 /// descriptors. Data is not copied since it cannot be legally read.
44 using BlockMoveFn = void (*)(Block *Storage, const char *SrcFieldPtr,
45                              char *DstFieldPtr, const Descriptor *FieldDesc);
46 
47 /// Inline descriptor embedded in structures and arrays.
48 ///
49 /// Such descriptors precede all composite array elements and structure fields.
50 /// If the base of a pointer is not zero, the base points to the end of this
51 /// structure. The offset field is used to traverse the pointer chain up
52 /// to the root structure which allocated the object.
53 struct InlineDescriptor {
54   /// Offset inside the structure/array.
55   unsigned Offset;
56 
57   /// Flag indicating if the storage is constant or not.
58   /// Relevant for primitive fields.
59   unsigned IsConst : 1;
60   /// For primitive fields, it indicates if the field was initialized.
61   /// Primitive fields in static storage are always initialized.
62   /// Arrays are always initialized, even though their elements might not be.
63   /// Base classes are initialized after the constructor is invoked.
64   unsigned IsInitialized : 1;
65   /// Flag indicating if the field is an embedded base class.
66   unsigned IsBase : 1;
67   /// Flag indicating if the field is the active member of a union.
68   unsigned IsActive : 1;
69   /// Flag indicating if the field is mutable (if in a record).
70   unsigned IsFieldMutable : 1;
71 
72   Descriptor *Desc;
73 };
74 
75 /// Describes a memory block created by an allocation site.
76 struct Descriptor final {
77 private:
78   /// Original declaration, used to emit the error message.
79   const DeclTy Source;
80   /// Size of an element, in host bytes.
81   const unsigned ElemSize;
82   /// Size of the storage, in host bytes.
83   const unsigned Size;
84   // Size of the metadata.
85   const unsigned MDSize;
86   /// Size of the allocation (storage + metadata), in host bytes.
87   const unsigned AllocSize;
88 
89   /// Value to denote arrays of unknown size.
90   static constexpr unsigned UnknownSizeMark = (unsigned)-1;
91 
92 public:
93   /// Token to denote structures of unknown size.
94   struct UnknownSize {};
95 
96   using MetadataSize = std::optional<unsigned>;
97   static constexpr MetadataSize InlineDescMD = sizeof(InlineDescriptor);
98 
99   /// Pointer to the record, if block contains records.
100   Record *const ElemRecord = nullptr;
101   /// Descriptor of the array element.
102   Descriptor *const ElemDesc = nullptr;
103   /// Flag indicating if the block is mutable.
104   const bool IsConst = false;
105   /// Flag indicating if a field is mutable.
106   const bool IsMutable = false;
107   /// Flag indicating if the block is a temporary.
108   const bool IsTemporary = false;
109   /// Flag indicating if the block is an array.
110   const bool IsArray = false;
111 
112   /// Storage management methods.
113   const BlockCtorFn CtorFn = nullptr;
114   const BlockDtorFn DtorFn = nullptr;
115   const BlockMoveFn MoveFn = nullptr;
116 
117   /// Allocates a descriptor for a primitive.
118   Descriptor(const DeclTy &D, PrimType Type, MetadataSize MD, bool IsConst,
119              bool IsTemporary, bool IsMutable);
120 
121   /// Allocates a descriptor for an array of primitives.
122   Descriptor(const DeclTy &D, PrimType Type, MetadataSize MD, size_t NumElems,
123              bool IsConst, bool IsTemporary, bool IsMutable);
124 
125   /// Allocates a descriptor for an array of primitives of unknown size.
126   Descriptor(const DeclTy &D, PrimType Type, bool IsTemporary, UnknownSize);
127 
128   /// Allocates a descriptor for an array of composites.
129   Descriptor(const DeclTy &D, Descriptor *Elem, MetadataSize MD,
130              unsigned NumElems, bool IsConst, bool IsTemporary, bool IsMutable);
131 
132   /// Allocates a descriptor for an array of composites of unknown size.
133   Descriptor(const DeclTy &D, Descriptor *Elem, bool IsTemporary, UnknownSize);
134 
135   /// Allocates a descriptor for a record.
136   Descriptor(const DeclTy &D, Record *R, MetadataSize MD, bool IsConst,
137              bool IsTemporary, bool IsMutable);
138 
139   QualType getType() const;
140   SourceLocation getLocation() const;
141 
142   const Decl *asDecl() const { return Source.dyn_cast<const Decl *>(); }
143   const Expr *asExpr() const { return Source.dyn_cast<const Expr *>(); }
144 
145   const ValueDecl *asValueDecl() const {
146     return dyn_cast_if_present<ValueDecl>(asDecl());
147   }
148 
149   const FieldDecl *asFieldDecl() const {
150     return dyn_cast_if_present<FieldDecl>(asDecl());
151   }
152 
153   const RecordDecl *asRecordDecl() const {
154     return dyn_cast_if_present<RecordDecl>(asDecl());
155   }
156 
157   /// Returns the size of the object without metadata.
158   unsigned getSize() const {
159     assert(!isUnknownSizeArray() && "Array of unknown size");
160     return Size;
161   }
162 
163   /// Returns the allocated size, including metadata.
164   unsigned getAllocSize() const { return AllocSize; }
165   /// returns the size of an element when the structure is viewed as an array.
166   unsigned getElemSize()  const { return ElemSize; }
167   /// Returns the size of the metadata.
168   unsigned getMetadataSize() const { return MDSize; }
169 
170   /// Returns the number of elements stored in the block.
171   unsigned getNumElems() const {
172     return Size == UnknownSizeMark ? 0 : (getSize() / getElemSize());
173   }
174 
175   /// Checks if the descriptor is of an array of primitives.
176   bool isPrimitiveArray() const { return IsArray && !ElemDesc; }
177   /// Checks if the descriptor is of an array of composites.
178   bool isCompositeArray() const { return IsArray && ElemDesc; }
179   /// Checks if the descriptor is of an array of zero size.
180   bool isZeroSizeArray() const { return Size == 0; }
181   /// Checks if the descriptor is of an array of unknown size.
182   bool isUnknownSizeArray() const { return Size == UnknownSizeMark; }
183 
184   /// Checks if the descriptor is of a primitive.
185   bool isPrimitive() const { return !IsArray && !ElemRecord; }
186 
187   /// Checks if the descriptor is of an array.
188   bool isArray() const { return IsArray; }
189 };
190 
191 /// Bitfield tracking the initialisation status of elements of primitive arrays.
192 /// A pointer to this is embedded at the end of all primitive arrays.
193 /// If the map was not yet created and nothing was initialized, the pointer to
194 /// this structure is 0. If the object was fully initialized, the pointer is -1.
195 struct InitMap final {
196 private:
197   /// Type packing bits.
198   using T = uint64_t;
199   /// Bits stored in a single field.
200   static constexpr uint64_t PER_FIELD = sizeof(T) * CHAR_BIT;
201 
202   /// Initializes the map with no fields set.
203   InitMap(unsigned N);
204 
205   /// Returns a pointer to storage.
206   T *data();
207   const T *data() const;
208 
209 public:
210   /// Initializes an element. Returns true when object if fully initialized.
211   bool initialize(unsigned I);
212 
213   /// Checks if an element was initialized.
214   bool isInitialized(unsigned I) const;
215 
216   /// Allocates a map holding N elements.
217   static InitMap *allocate(unsigned N);
218 
219 private:
220   /// Number of fields initialized.
221   unsigned UninitFields;
222 };
223 
224 } // namespace interp
225 } // namespace clang
226 
227 #endif
228