1 //===- ModuleFile.h - Module file description -------------------*- 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 defines the Module class, which describes a module that has
10 //  been loaded from an AST file.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_CLANG_SERIALIZATION_MODULEFILE_H
15 #define LLVM_CLANG_SERIALIZATION_MODULEFILE_H
16 
17 #include "clang/Basic/Module.h"
18 #include "clang/Basic/SourceLocation.h"
19 #include "clang/Serialization/ASTBitCodes.h"
20 #include "clang/Serialization/ContinuousRangeMap.h"
21 #include "clang/Serialization/ModuleFileExtension.h"
22 #include "llvm/ADT/DenseMap.h"
23 #include "llvm/ADT/PointerIntPair.h"
24 #include "llvm/ADT/SetVector.h"
25 #include "llvm/ADT/SmallVector.h"
26 #include "llvm/ADT/StringRef.h"
27 #include "llvm/Bitstream/BitstreamReader.h"
28 #include "llvm/Support/Endian.h"
29 #include <cassert>
30 #include <cstdint>
31 #include <memory>
32 #include <string>
33 #include <vector>
34 
35 namespace clang {
36 
37 class FileEntry;
38 
39 namespace serialization {
40 
41 /// Specifies the kind of module that has been loaded.
42 enum ModuleKind {
43   /// File is an implicitly-loaded module.
44   MK_ImplicitModule,
45 
46   /// File is an explicitly-loaded module.
47   MK_ExplicitModule,
48 
49   /// File is a PCH file treated as such.
50   MK_PCH,
51 
52   /// File is a PCH file treated as the preamble.
53   MK_Preamble,
54 
55   /// File is a PCH file treated as the actual main file.
56   MK_MainFile,
57 
58   /// File is from a prebuilt module path.
59   MK_PrebuiltModule
60 };
61 
62 /// The input file that has been loaded from this AST file, along with
63 /// bools indicating whether this was an overridden buffer or if it was
64 /// out-of-date or not-found.
65 class InputFile {
66   enum {
67     Overridden = 1,
68     OutOfDate = 2,
69     NotFound = 3
70   };
71   llvm::PointerIntPair<const FileEntry *, 2, unsigned> Val;
72 
73 public:
74   InputFile() = default;
75 
76   InputFile(const FileEntry *File,
77             bool isOverridden = false, bool isOutOfDate = false) {
78     assert(!(isOverridden && isOutOfDate) &&
79            "an overridden cannot be out-of-date");
80     unsigned intVal = 0;
81     if (isOverridden)
82       intVal = Overridden;
83     else if (isOutOfDate)
84       intVal = OutOfDate;
85     Val.setPointerAndInt(File, intVal);
86   }
87 
88   static InputFile getNotFound() {
89     InputFile File;
90     File.Val.setInt(NotFound);
91     return File;
92   }
93 
94   const FileEntry *getFile() const { return Val.getPointer(); }
95   bool isOverridden() const { return Val.getInt() == Overridden; }
96   bool isOutOfDate() const { return Val.getInt() == OutOfDate; }
97   bool isNotFound() const { return Val.getInt() == NotFound; }
98 };
99 
100 /// Information about a module that has been loaded by the ASTReader.
101 ///
102 /// Each instance of the Module class corresponds to a single AST file, which
103 /// may be a precompiled header, precompiled preamble, a module, or an AST file
104 /// of some sort loaded as the main file, all of which are specific formulations
105 /// of the general notion of a "module". A module may depend on any number of
106 /// other modules.
107 class ModuleFile {
108 public:
109   ModuleFile(ModuleKind Kind, unsigned Generation)
110       : Kind(Kind), Generation(Generation) {}
111   ~ModuleFile();
112 
113   // === General information ===
114 
115   /// The index of this module in the list of modules.
116   unsigned Index = 0;
117 
118   /// The type of this module.
119   ModuleKind Kind;
120 
121   /// The file name of the module file.
122   std::string FileName;
123 
124   /// The name of the module.
125   std::string ModuleName;
126 
127   /// The base directory of the module.
128   std::string BaseDirectory;
129 
130   std::string getTimestampFilename() const {
131     return FileName + ".timestamp";
132   }
133 
134   /// The original source file name that was used to build the
135   /// primary AST file, which may have been modified for
136   /// relocatable-pch support.
137   std::string OriginalSourceFileName;
138 
139   /// The actual original source file name that was used to
140   /// build this AST file.
141   std::string ActualOriginalSourceFileName;
142 
143   /// The file ID for the original source file that was used to
144   /// build this AST file.
145   FileID OriginalSourceFileID;
146 
147   /// The directory that the PCH was originally created in. Used to
148   /// allow resolving headers even after headers+PCH was moved to a new path.
149   std::string OriginalDir;
150 
151   std::string ModuleMapPath;
152 
153   /// Whether this precompiled header is a relocatable PCH file.
154   bool RelocatablePCH = false;
155 
156   /// Whether timestamps are included in this module file.
157   bool HasTimestamps = false;
158 
159   /// Whether the PCH has a corresponding object file.
160   bool PCHHasObjectFile = false;
161 
162   /// Whether the top-level module has been read from the AST file.
163   bool DidReadTopLevelSubmodule = false;
164 
165   /// The file entry for the module file.
166   const FileEntry *File = nullptr;
167 
168   /// The signature of the module file, which may be used instead of the size
169   /// and modification time to identify this particular file.
170   ASTFileSignature Signature;
171 
172   /// Whether this module has been directly imported by the
173   /// user.
174   bool DirectlyImported = false;
175 
176   /// The generation of which this module file is a part.
177   unsigned Generation;
178 
179   /// The memory buffer that stores the data associated with
180   /// this AST file, owned by the InMemoryModuleCache.
181   llvm::MemoryBuffer *Buffer;
182 
183   /// The size of this file, in bits.
184   uint64_t SizeInBits = 0;
185 
186   /// The global bit offset (or base) of this module
187   uint64_t GlobalBitOffset = 0;
188 
189   /// The serialized bitstream data for this file.
190   StringRef Data;
191 
192   /// The main bitstream cursor for the main block.
193   llvm::BitstreamCursor Stream;
194 
195   /// The source location where the module was explicitly or implicitly
196   /// imported in the local translation unit.
197   ///
198   /// If module A depends on and imports module B, both modules will have the
199   /// same DirectImportLoc, but different ImportLoc (B's ImportLoc will be a
200   /// source location inside module A).
201   ///
202   /// WARNING: This is largely useless. It doesn't tell you when a module was
203   /// made visible, just when the first submodule of that module was imported.
204   SourceLocation DirectImportLoc;
205 
206   /// The source location where this module was first imported.
207   SourceLocation ImportLoc;
208 
209   /// The first source location in this module.
210   SourceLocation FirstLoc;
211 
212   /// The list of extension readers that are attached to this module
213   /// file.
214   std::vector<std::unique_ptr<ModuleFileExtensionReader>> ExtensionReaders;
215 
216   /// The module offset map data for this file. If non-empty, the various
217   /// ContinuousRangeMaps described below have not yet been populated.
218   StringRef ModuleOffsetMap;
219 
220   // === Input Files ===
221 
222   /// The cursor to the start of the input-files block.
223   llvm::BitstreamCursor InputFilesCursor;
224 
225   /// Offsets for all of the input file entries in the AST file.
226   const llvm::support::unaligned_uint64_t *InputFileOffsets = nullptr;
227 
228   /// The input files that have been loaded from this AST file.
229   std::vector<InputFile> InputFilesLoaded;
230 
231   // All user input files reside at the index range [0, NumUserInputFiles), and
232   // system input files reside at [NumUserInputFiles, InputFilesLoaded.size()).
233   unsigned NumUserInputFiles = 0;
234 
235   /// If non-zero, specifies the time when we last validated input
236   /// files.  Zero means we never validated them.
237   ///
238   /// The time is specified in seconds since the start of the Epoch.
239   uint64_t InputFilesValidationTimestamp = 0;
240 
241   // === Source Locations ===
242 
243   /// Cursor used to read source location entries.
244   llvm::BitstreamCursor SLocEntryCursor;
245 
246   /// The number of source location entries in this AST file.
247   unsigned LocalNumSLocEntries = 0;
248 
249   /// The base ID in the source manager's view of this module.
250   int SLocEntryBaseID = 0;
251 
252   /// The base offset in the source manager's view of this module.
253   unsigned SLocEntryBaseOffset = 0;
254 
255   /// Offsets for all of the source location entries in the
256   /// AST file.
257   const uint32_t *SLocEntryOffsets = nullptr;
258 
259   /// SLocEntries that we're going to preload.
260   SmallVector<uint64_t, 4> PreloadSLocEntries;
261 
262   /// Remapping table for source locations in this module.
263   ContinuousRangeMap<uint32_t, int, 2> SLocRemap;
264 
265   // === Identifiers ===
266 
267   /// The number of identifiers in this AST file.
268   unsigned LocalNumIdentifiers = 0;
269 
270   /// Offsets into the identifier table data.
271   ///
272   /// This array is indexed by the identifier ID (-1), and provides
273   /// the offset into IdentifierTableData where the string data is
274   /// stored.
275   const uint32_t *IdentifierOffsets = nullptr;
276 
277   /// Base identifier ID for identifiers local to this module.
278   serialization::IdentID BaseIdentifierID = 0;
279 
280   /// Remapping table for identifier IDs in this module.
281   ContinuousRangeMap<uint32_t, int, 2> IdentifierRemap;
282 
283   /// Actual data for the on-disk hash table of identifiers.
284   ///
285   /// This pointer points into a memory buffer, where the on-disk hash
286   /// table for identifiers actually lives.
287   const char *IdentifierTableData = nullptr;
288 
289   /// A pointer to an on-disk hash table of opaque type
290   /// IdentifierHashTable.
291   void *IdentifierLookupTable = nullptr;
292 
293   /// Offsets of identifiers that we're going to preload within
294   /// IdentifierTableData.
295   std::vector<unsigned> PreloadIdentifierOffsets;
296 
297   // === Macros ===
298 
299   /// The cursor to the start of the preprocessor block, which stores
300   /// all of the macro definitions.
301   llvm::BitstreamCursor MacroCursor;
302 
303   /// The number of macros in this AST file.
304   unsigned LocalNumMacros = 0;
305 
306   /// Offsets of macros in the preprocessor block.
307   ///
308   /// This array is indexed by the macro ID (-1), and provides
309   /// the offset into the preprocessor block where macro definitions are
310   /// stored.
311   const uint32_t *MacroOffsets = nullptr;
312 
313   /// Base macro ID for macros local to this module.
314   serialization::MacroID BaseMacroID = 0;
315 
316   /// Remapping table for macro IDs in this module.
317   ContinuousRangeMap<uint32_t, int, 2> MacroRemap;
318 
319   /// The offset of the start of the set of defined macros.
320   uint64_t MacroStartOffset = 0;
321 
322   // === Detailed PreprocessingRecord ===
323 
324   /// The cursor to the start of the (optional) detailed preprocessing
325   /// record block.
326   llvm::BitstreamCursor PreprocessorDetailCursor;
327 
328   /// The offset of the start of the preprocessor detail cursor.
329   uint64_t PreprocessorDetailStartOffset = 0;
330 
331   /// Base preprocessed entity ID for preprocessed entities local to
332   /// this module.
333   serialization::PreprocessedEntityID BasePreprocessedEntityID = 0;
334 
335   /// Remapping table for preprocessed entity IDs in this module.
336   ContinuousRangeMap<uint32_t, int, 2> PreprocessedEntityRemap;
337 
338   const PPEntityOffset *PreprocessedEntityOffsets = nullptr;
339   unsigned NumPreprocessedEntities = 0;
340 
341   /// Base ID for preprocessed skipped ranges local to this module.
342   unsigned BasePreprocessedSkippedRangeID = 0;
343 
344   const PPSkippedRange *PreprocessedSkippedRangeOffsets = nullptr;
345   unsigned NumPreprocessedSkippedRanges = 0;
346 
347   // === Header search information ===
348 
349   /// The number of local HeaderFileInfo structures.
350   unsigned LocalNumHeaderFileInfos = 0;
351 
352   /// Actual data for the on-disk hash table of header file
353   /// information.
354   ///
355   /// This pointer points into a memory buffer, where the on-disk hash
356   /// table for header file information actually lives.
357   const char *HeaderFileInfoTableData = nullptr;
358 
359   /// The on-disk hash table that contains information about each of
360   /// the header files.
361   void *HeaderFileInfoTable = nullptr;
362 
363   // === Submodule information ===
364 
365   /// The number of submodules in this module.
366   unsigned LocalNumSubmodules = 0;
367 
368   /// Base submodule ID for submodules local to this module.
369   serialization::SubmoduleID BaseSubmoduleID = 0;
370 
371   /// Remapping table for submodule IDs in this module.
372   ContinuousRangeMap<uint32_t, int, 2> SubmoduleRemap;
373 
374   // === Selectors ===
375 
376   /// The number of selectors new to this file.
377   ///
378   /// This is the number of entries in SelectorOffsets.
379   unsigned LocalNumSelectors = 0;
380 
381   /// Offsets into the selector lookup table's data array
382   /// where each selector resides.
383   const uint32_t *SelectorOffsets = nullptr;
384 
385   /// Base selector ID for selectors local to this module.
386   serialization::SelectorID BaseSelectorID = 0;
387 
388   /// Remapping table for selector IDs in this module.
389   ContinuousRangeMap<uint32_t, int, 2> SelectorRemap;
390 
391   /// A pointer to the character data that comprises the selector table
392   ///
393   /// The SelectorOffsets table refers into this memory.
394   const unsigned char *SelectorLookupTableData = nullptr;
395 
396   /// A pointer to an on-disk hash table of opaque type
397   /// ASTSelectorLookupTable.
398   ///
399   /// This hash table provides the IDs of all selectors, and the associated
400   /// instance and factory methods.
401   void *SelectorLookupTable = nullptr;
402 
403   // === Declarations ===
404 
405   /// DeclsCursor - This is a cursor to the start of the DECLS_BLOCK block. It
406   /// has read all the abbreviations at the start of the block and is ready to
407   /// jump around with these in context.
408   llvm::BitstreamCursor DeclsCursor;
409 
410   /// The number of declarations in this AST file.
411   unsigned LocalNumDecls = 0;
412 
413   /// Offset of each declaration within the bitstream, indexed
414   /// by the declaration ID (-1).
415   const DeclOffset *DeclOffsets = nullptr;
416 
417   /// Base declaration ID for declarations local to this module.
418   serialization::DeclID BaseDeclID = 0;
419 
420   /// Remapping table for declaration IDs in this module.
421   ContinuousRangeMap<uint32_t, int, 2> DeclRemap;
422 
423   /// Mapping from the module files that this module file depends on
424   /// to the base declaration ID for that module as it is understood within this
425   /// module.
426   ///
427   /// This is effectively a reverse global-to-local mapping for declaration
428   /// IDs, so that we can interpret a true global ID (for this translation unit)
429   /// as a local ID (for this module file).
430   llvm::DenseMap<ModuleFile *, serialization::DeclID> GlobalToLocalDeclIDs;
431 
432   /// Array of file-level DeclIDs sorted by file.
433   const serialization::DeclID *FileSortedDecls = nullptr;
434   unsigned NumFileSortedDecls = 0;
435 
436   /// Array of category list location information within this
437   /// module file, sorted by the definition ID.
438   const serialization::ObjCCategoriesInfo *ObjCCategoriesMap = nullptr;
439 
440   /// The number of redeclaration info entries in ObjCCategoriesMap.
441   unsigned LocalNumObjCCategoriesInMap = 0;
442 
443   /// The Objective-C category lists for categories known to this
444   /// module.
445   SmallVector<uint64_t, 1> ObjCCategories;
446 
447   // === Types ===
448 
449   /// The number of types in this AST file.
450   unsigned LocalNumTypes = 0;
451 
452   /// Offset of each type within the bitstream, indexed by the
453   /// type ID, or the representation of a Type*.
454   const uint32_t *TypeOffsets = nullptr;
455 
456   /// Base type ID for types local to this module as represented in
457   /// the global type ID space.
458   serialization::TypeID BaseTypeIndex = 0;
459 
460   /// Remapping table for type IDs in this module.
461   ContinuousRangeMap<uint32_t, int, 2> TypeRemap;
462 
463   // === Miscellaneous ===
464 
465   /// Diagnostic IDs and their mappings that the user changed.
466   SmallVector<uint64_t, 8> PragmaDiagMappings;
467 
468   /// List of modules which depend on this module
469   llvm::SetVector<ModuleFile *> ImportedBy;
470 
471   /// List of modules which this module depends on
472   llvm::SetVector<ModuleFile *> Imports;
473 
474   /// Determine whether this module was directly imported at
475   /// any point during translation.
476   bool isDirectlyImported() const { return DirectlyImported; }
477 
478   /// Is this a module file for a module (rather than a PCH or similar).
479   bool isModule() const {
480     return Kind == MK_ImplicitModule || Kind == MK_ExplicitModule ||
481            Kind == MK_PrebuiltModule;
482   }
483 
484   /// Dump debugging output for this module.
485   void dump();
486 };
487 
488 } // namespace serialization
489 
490 } // namespace clang
491 
492 #endif // LLVM_CLANG_SERIALIZATION_MODULEFILE_H
493