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