Home | History | Annotate | Download | only in Serialization
      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/SourceLocation.h"
     19 #include "clang/Serialization/ASTBitCodes.h"
     20 #include "clang/Serialization/ContinuousRangeMap.h"
     21 #include "clang/Serialization/ModuleFileExtension.h"
     22 #include "llvm/ADT/SetVector.h"
     23 #include "llvm/Bitcode/BitstreamReader.h"
     24 #include "llvm/Support/Endian.h"
     25 #include <memory>
     26 #include <string>
     27 
     28 namespace llvm {
     29 template <typename Info> class OnDiskChainedHashTable;
     30 template <typename Info> class OnDiskIterableChainedHashTable;
     31 }
     32 
     33 namespace clang {
     34 
     35 class FileEntry;
     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:
     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 
     79   static InputFile getNotFound() {
     80     InputFile File;
     81     File.Val.setInt(NotFound);
     82     return File;
     83   }
     84 
     85   const FileEntry *getFile() const { return Val.getPointer(); }
     86   bool isOverridden() const { return Val.getInt() == Overridden; }
     87   bool isOutOfDate() const { return Val.getInt() == OutOfDate; }
     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 
    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 The number of C++ base specifier sets in this AST file.
    403   unsigned LocalNumCXXBaseSpecifiers;
    404 
    405   /// \brief Offset of each C++ base specifier set within the bitstream,
    406   /// indexed by the C++ base specifier set ID (-1).
    407   const uint32_t *CXXBaseSpecifiersOffsets;
    408 
    409   /// \brief The number of C++ ctor initializer lists in this AST file.
    410   unsigned LocalNumCXXCtorInitializers;
    411 
    412   /// \brief Offset of each C++ ctor initializer list within the bitstream,
    413   /// indexed by the C++ ctor initializer list ID minus 1.
    414   const uint32_t *CXXCtorInitializersOffsets;
    415 
    416   /// \brief Array of file-level DeclIDs sorted by file.
    417   const serialization::DeclID *FileSortedDecls;
    418   unsigned NumFileSortedDecls;
    419 
    420   /// \brief Array of category list location information within this
    421   /// module file, sorted by the definition ID.
    422   const serialization::ObjCCategoriesInfo *ObjCCategoriesMap;
    423 
    424   /// \brief The number of redeclaration info entries in ObjCCategoriesMap.
    425   unsigned LocalNumObjCCategoriesInMap;
    426 
    427   /// \brief The Objective-C category lists for categories known to this
    428   /// module.
    429   SmallVector<uint64_t, 1> ObjCCategories;
    430 
    431   // === Types ===
    432 
    433   /// \brief The number of types in this AST file.
    434   unsigned LocalNumTypes;
    435 
    436   /// \brief Offset of each type within the bitstream, indexed by the
    437   /// type ID, or the representation of a Type*.
    438   const uint32_t *TypeOffsets;
    439 
    440   /// \brief Base type ID for types local to this module as represented in
    441   /// the global type ID space.
    442   serialization::TypeID BaseTypeIndex;
    443 
    444   /// \brief Remapping table for type IDs in this module.
    445   ContinuousRangeMap<uint32_t, int, 2> TypeRemap;
    446 
    447   // === Miscellaneous ===
    448 
    449   /// \brief Diagnostic IDs and their mappings that the user changed.
    450   SmallVector<uint64_t, 8> PragmaDiagMappings;
    451 
    452   /// \brief List of modules which depend on this module
    453   llvm::SetVector<ModuleFile *> ImportedBy;
    454 
    455   /// \brief List of modules which this module depends on
    456   llvm::SetVector<ModuleFile *> Imports;
    457 
    458   /// \brief Determine whether this module was directly imported at
    459   /// any point during translation.
    460   bool isDirectlyImported() const { return DirectlyImported; }
    461 
    462   /// \brief Is this a module file for a module (rather than a PCH or similar).
    463   bool isModule() const {
    464     return Kind == MK_ImplicitModule || Kind == MK_ExplicitModule;
    465   }
    466 
    467   /// \brief Dump debugging output for this module.
    468   void dump();
    469 };
    470 
    471 } // end namespace serialization
    472 
    473 } // end namespace clang
    474 
    475 #endif
    476