CIRCT  20.0.0git
FIRParser.h
Go to the documentation of this file.
1 //===- FIRParser.h - .fir to FIRRTL dialect parser --------------*- C++ -*-===//
2 //
3 //
4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5 // See https://llvm.org/LICENSE.txt for license information.
6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // Defines the interface to the .fir file parser.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef CIRCT_DIALECT_FIRRTL_FIRPARSER_H
15 #define CIRCT_DIALECT_FIRRTL_FIRPARSER_H
16 
18 #include "circt/Support/LLVM.h"
19 #include <optional>
20 #include <string>
21 #include <vector>
22 
23 namespace llvm {
24 class SourceMgr;
25 } // namespace llvm
26 
27 namespace mlir {
28 class LocationAttr;
29 class TimingScope;
30 } // namespace mlir
31 
32 namespace circt {
33 namespace firrtl {
34 
36  /// Specify how @info locators should be handled.
37  enum class InfoLocHandling {
38  /// If this is set to true, the @info locators are ignored, and the
39  /// locations are set to the location in the .fir file.
40  IgnoreInfo,
41  /// Prefer @info locators, fallback to .fir locations.
42  PreferInfo,
43  /// Attach both @info locators (when present) and .fir locations.
44  FusedInfo
45  };
46 
48 
49  /// The number of annotation files that were specified on the command line.
50  /// This, along with numOMIRFiles provides structure to the buffers in the
51  /// source manager.
53  bool scalarizePublicModules = false;
55  bool scalarizeExtModules = false;
56  std::vector<std::string> enableLayers;
57  std::vector<std::string> disableLayers;
58  std::optional<LayerSpecialization> defaultLayerSpecialization;
59 };
60 
62  mlir::MLIRContext *context,
63  mlir::TimingScope &ts,
64  FIRParserOptions options = {});
65 
66 // Decode a source locator string `spelling`, returning a pair indicating that
67 // the `spelling` was correct and an optional location attribute. The
68 // `skipParsing` option can be used to short-circuit parsing and just do
69 // validation of the `spelling`. This require both an Identifier and a
70 // FileLineColLoc to use for caching purposes and context as the cache may be
71 // updated with a new identifier.
72 //
73 // This utility exists because source locators can exist outside of normal
74 // "parsing". E.g., these can show up in annotations or in Object Model 2.0
75 // JSON.
76 //
77 // TODO: This API is super wacky and should be streamlined to hide the
78 // caching.
79 std::pair<bool, std::optional<mlir::LocationAttr>>
80 maybeStringToLocation(llvm::StringRef spelling, bool skipParsing,
81  mlir::StringAttr &locatorFilenameCache,
82  FileLineColLoc &fileLineColLocCache,
83  MLIRContext *context);
84 
86 
87 /// The FIRRTL specification version.
88 struct FIRVersion {
89  constexpr FIRVersion(uint16_t major, uint16_t minor, uint16_t patch)
90  : major{major}, minor{minor}, patch{patch} {}
91 
92  explicit constexpr operator uint64_t() const {
93  return uint64_t(major) << 32 | uint64_t(minor) << 16 | uint64_t(patch);
94  }
95 
96  constexpr bool operator<(FIRVersion rhs) const {
97  return uint64_t(*this) < uint64_t(rhs);
98  }
99 
100  constexpr bool operator>(FIRVersion rhs) const {
101  return uint64_t(*this) > uint64_t(rhs);
102  }
103 
104  constexpr bool operator<=(FIRVersion rhs) const {
105  return uint64_t(*this) <= uint64_t(rhs);
106  }
107 
108  constexpr bool operator>=(FIRVersion rhs) const {
109  return uint64_t(*this) >= uint64_t(rhs);
110  }
111 
112  uint16_t major;
113  uint16_t minor;
114  uint16_t patch;
115 };
116 
117 /// The current minimum version of FIRRTL that the parser supports.
118 constexpr FIRVersion minimumFIRVersion(2, 0, 0);
119 
120 /// The next version of FIRRTL that is not yet released.
121 ///
122 /// Features use this version if they have been landed on the main branch of
123 /// `chipsalliance/firrtl-spec`, but have not been part of a release yet. Once a
124 /// new version of the spec is released, all uses of `nextFIRVersion` in the
125 /// parser are replaced with the concrete version `{x, y, z}`, and this
126 /// declaration here is bumped to the next probable version number.
127 constexpr FIRVersion nextFIRVersion(4, 1, 0);
128 
129 /// A marker for parser features that are currently missing from the spec.
130 ///
131 /// Features use this version if they have _not_ been added to the documentation
132 /// in the `chipsalliance/firrtl-spec` repository. This allows us to distinguish
133 /// features that are released in the next version of the spec and features that
134 /// are still missing from the spec.
136 
137 /// The version of FIRRTL that the exporter produces. This is always the next
138 /// version, since it contains any new developments.
140 
141 template <typename T>
142 T &operator<<(T &os, FIRVersion version) {
143  return os << version.major << "." << version.minor << "." << version.patch;
144 }
145 
146 } // namespace firrtl
147 } // namespace circt
148 
149 #endif // CIRCT_DIALECT_FIRRTL_FIRPARSER_H
void registerFromFIRFileTranslation()
Definition: FIRParser.cpp:5926
std::pair< bool, std::optional< mlir::LocationAttr > > maybeStringToLocation(llvm::StringRef spelling, bool skipParsing, mlir::StringAttr &locatorFilenameCache, FileLineColLoc &fileLineColLocCache, MLIRContext *context)
mlir::OwningOpRef< mlir::ModuleOp > importFIRFile(llvm::SourceMgr &sourceMgr, mlir::MLIRContext *context, mlir::TimingScope &ts, FIRParserOptions options={})
constexpr FIRVersion exportFIRVersion
The version of FIRRTL that the exporter produces.
Definition: FIRParser.h:139
llvm::raw_ostream & operator<<(llvm::raw_ostream &os, const InstanceInfo::LatticeValue &value)
constexpr FIRVersion missingSpecFIRVersion
A marker for parser features that are currently missing from the spec.
Definition: FIRParser.h:135
constexpr FIRVersion minimumFIRVersion(2, 0, 0)
The current minimum version of FIRRTL that the parser supports.
constexpr FIRVersion nextFIRVersion(4, 1, 0)
The next version of FIRRTL that is not yet released.
The InstanceGraph op interface, see InstanceGraphInterface.td for more details.
Definition: DebugAnalysis.h:21
unsigned numAnnotationFiles
The number of annotation files that were specified on the command line.
Definition: FIRParser.h:52
InfoLocHandling infoLocatorHandling
Definition: FIRParser.h:47
std::optional< LayerSpecialization > defaultLayerSpecialization
Definition: FIRParser.h:58
InfoLocHandling
Specify how @info locators should be handled.
Definition: FIRParser.h:37
@ PreferInfo
Prefer @info locators, fallback to .fir locations.
@ FusedInfo
Attach both @info locators (when present) and .fir locations.
@ IgnoreInfo
If this is set to true, the @info locators are ignored, and the locations are set to the location in ...
std::vector< std::string > enableLayers
Definition: FIRParser.h:56
std::vector< std::string > disableLayers
Definition: FIRParser.h:57
The FIRRTL specification version.
Definition: FIRParser.h:88
constexpr bool operator<(FIRVersion rhs) const
Definition: FIRParser.h:96
constexpr bool operator>(FIRVersion rhs) const
Definition: FIRParser.h:100
constexpr bool operator>=(FIRVersion rhs) const
Definition: FIRParser.h:108
constexpr FIRVersion(uint16_t major, uint16_t minor, uint16_t patch)
Definition: FIRParser.h:89
constexpr bool operator<=(FIRVersion rhs) const
Definition: FIRParser.h:104