LoweringOptions.h

Go to the documentation of this file.

//===- LoweringOptions.h - CIRCT Lowering Options ---------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// Options for controlling the lowering process and verilog exporting.
//
//===----------------------------------------------------------------------===//
 
#ifndef CIRCT_SUPPORT_LOWERINGOPTIONS_H
#define CIRCT_SUPPORT_LOWERINGOPTIONS_H
 
#include "mlir/IR/BuiltinAttributes.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/ADT/Twine.h"
 
namespace mlir {
class ModuleOp;
}
 
namespace circt {
 
/// Options which control the emission from CIRCT to Verilog.
struct LoweringOptions {
  /// Error callback type used to indicate errors parsing the options string.
  using ErrorHandlerT = llvm::function_ref<void(llvm::Twine)>;
 
  /// Create a LoweringOptions with the default values.
  LoweringOptions() = default;
 
  /// Create a LoweringOptions and read in options from a string,
  /// overriding only the set options in the string.
  LoweringOptions(llvm::StringRef options, ErrorHandlerT errorHandler);
 
  /// Create a LoweringOptions with values loaded from an MLIR ModuleOp. This
  /// loads a string attribute with the key `circt.loweringOptions`. If there is
  /// an error parsing the attribute this will print an error using the
  /// ModuleOp.
  LoweringOptions(mlir::ModuleOp module);
 
  /// Return the value of the `circt.loweringOptions` in the specified module
  /// if present, or a null attribute if not.
  static mlir::StringAttr getAttributeFrom(mlir::ModuleOp module);
 
  /// Read in options from a string, overriding only the set options in the
  /// string.
  void parse(llvm::StringRef options, ErrorHandlerT callback);
 
  /// Returns a string representation of the options.
  std::string toString() const;
 
  /// Write the verilog emitter options to a module's attributes.
  void setAsAttribute(mlir::ModuleOp module);
 
  /// Load any emitter options from the module. If there is an error validating
  /// the attribute, this will print an error using the ModuleOp.
  void parseFromAttribute(mlir::ModuleOp module);
 
  /// If true, emits `sv.alwayscomb` as Verilog `always @(*)` statements.
  /// Otherwise, print them as `always_comb`.
  bool noAlwaysComb = false;
 
  /// If true, expressions are allowed in the sensitivity list of `always`
  /// statements, otherwise they are forced to be simple wires. Some EDA
  /// tools rely on these being simple wires.
  bool allowExprInEventControl = false;
 
  /// If true, eliminate packed arrays for tools that don't support them (e.g.
  /// Yosys).
  bool disallowPackedArrays = false;
 
  /// If true, eliminate packed struct assignments in favor of a wire +
  /// assignments to the individual fields.
  bool disallowPackedStructAssignments = false;
 
  /// If true, do not emit SystemVerilog locally scoped "automatic" or logic
  /// declarations - emit top level wire and reg's instead.
  bool disallowLocalVariables = false;
 
  /// If true, verification statements like `assert`, `assume`, and `cover` will
  /// always be emitted with a label. If the statement has no label in the IR, a
  /// generic one will be created. Some EDA tools require verification
  /// statements to be labeled.
  bool enforceVerifLabels = false;
 
  /// This is the maximum number of terms in an expression before that
  /// expression spills a wire.
  enum { DEFAULT_TERM_LIMIT = 256 };
  unsigned maximumNumberOfTermsPerExpression = DEFAULT_TERM_LIMIT;
 
  /// This is the target width of lines in an emitted Verilog source file in
  /// columns.  Zero indicates no wrapping.  Must be < 2^14.
  enum { DEFAULT_LINE_LENGTH = 90, MAX_LINE_LENGTH = (1 << 14) - 1 };
  unsigned emittedLineLength = DEFAULT_LINE_LENGTH;
 
  /// Return std::nullopt if not wrapping, else the target emission line length.
  std::optional<unsigned> getEmittedLineLength() const {
    if (emittedLineLength == 0)
      return std::nullopt;
    // This should be rejected in parsing, but in case set directly, saturate.
    return std::min<unsigned>(MAX_LINE_LENGTH, emittedLineLength);
  }
 
  /// Add an explicit bitcast for avoiding bitwidth mismatch LINT errors.
  bool explicitBitcast = false;
 
  /// If true, replicated ops are emitted to a header file.
  bool emitReplicatedOpsToHeader = false;
 
  /// This option controls emitted location information style.
  enum LocationInfoStyle {
    Plain,                 // Default.
    WrapInAtSquareBracket, // Wrap location info in @[..].
    None,                  // No location info comment.
  } locationInfoStyle = Plain;
 
  /// If true, every port is declared separately
  /// (each includes direction and type (e.g., `input [3:0]`)).
  /// When false (default), ports share declarations when possible.
  bool disallowPortDeclSharing = false;
 
  /// Print debug info.
  bool printDebugInfo = false;
 
  /// If true, every mux expression is spilled to a wire.
  bool disallowMuxInlining = false;
 
  /// If true, expand `comb.replicate` into an explicit concatenation instead
  /// of emitting the `{N{...}}` replication operator (unsupported in some
  /// tools).
  bool disallowReplicate = false;
 
  /// This controls extra wire spilling performed in PrepareForEmission to
  /// improve readablitiy and debuggability.
  enum WireSpillingHeuristic : unsigned {
    SpillLargeTermsWithNamehints = 1, // Spill wires for expressions with
                                      // namehints if the term size is greater
                                      // than `wireSpillingNamehintTermLimit`.
  };
 
  unsigned wireSpillingHeuristicSet = 0;
 
  bool isWireSpillingHeuristicEnabled(WireSpillingHeuristic heurisic) const {
    return static_cast<bool>(wireSpillingHeuristicSet & heurisic);
  }
 
  enum { DEFAULT_NAMEHINT_TERM_LIMIT = 3 };
  unsigned wireSpillingNamehintTermLimit = DEFAULT_NAMEHINT_TERM_LIMIT;
 
  /// If true, every expression passed to an instance port is driven by a wire.
  /// Some lint tools dislike expressions being inlined into input ports so this
  /// option avoids such warnings.
  bool disallowExpressionInliningInPorts = false;
 
  /// If true, every expression used as an array index is driven by a wire, and
  /// the wire is marked as `(* keep = "true" *)`. Certain versions of Vivado
  /// produce incorrect synthesis results for certain arithmetic ops inlined
  /// into the array index.
  bool mitigateVivadoArrayIndexConstPropBug = false;
 
  /// Controls the port declaration syntax for module ports.
  ///
  /// - emitVarLogic: Emits `var logic` in the port lists rather than nothing,
  /// i.e., default plain (non-handle) ports to a variable (`input var logic
  /// ...`, `output var logic ...`).
  /// - emitWire: Emits 'wire' in port lists rather than nothing. Used in cases
  /// where `default_nettype` is not set to wire.
  /// - emitNone: Omits both `var logic` and `wire` in port lists; relies
  /// on standard SystemVerilog implicit net-kind port declaration.
  enum class EmitPortType {
    emitVarLogic,
    emitWire,
    emitNone,
  } emitPortType = EmitPortType::emitNone;
 
  /// If true, emit a comment wherever an instance wasn't printed, because
  /// it's emitted elsewhere as a bind.
  bool emitBindComments = false;
 
  /// If true, do not emit a version comment at the top of each verilog file.
  bool omitVersionComment = false;
 
  /// If true, then unique names that collide with keywords case insensitively.
  /// This is used to avoid stricter lint warnings which, e.g., treat "REG" as a
  /// Verilog keyword.
  bool caseInsensitiveKeywords = false;
 
  /// If true, then update the the mlir to include output verilog locations.
  bool emitVerilogLocations = false;
 
  /// If true, add a dummy wire to empty modules to prevent tools from regarding
  /// the module as blackbox.
  bool fixUpEmptyModules = false;
 
  // If true, wrap concurrent assertions with explicit clocking events into
  // procedural form, by hoisting the clock event into an enclosing always
  // block. The same transformation is applied to `assume property` and `cover
  // property`.
  bool disallowClockedAssertions = false;
 
  // If true, always emit assignments (both continuous and blocking) separately
  // rather than inlining them in net and variable declarations
  bool disallowDeclAssignments = false;
 
  /// If true, always emit begin/end blocks around if/else/always bodies, even
  /// when there is only a single statement.
  bool alwaysEmitBeginEnd = false;
 
  /// Controls the declaration syntax emitted for `sv.var`.
  ///
  /// - VarLogic: Always emits the `var` keyword. Integer vectors print as `var
  /// logic [3:0] x`; types that supply their own data type (structs, unions,
  /// enums, typedefs) print as `var my_struct x`.
  /// - Logic: Omits the `var` keyword, Integer vectors print as `logic [3:0]
  /// x`; types that supply their own data type print with no prefix (`my_struct
  /// x`).
  /// - Reg: Omits the `var` keyword, Integer vectors print as `reg [3:0] x`;
  /// types that supply their own data type print with no prefix (`my_struct
  /// x`).
  ///
  /// All there styles are equivalent in meaning and differ only in spelling.
  enum class VarOpDeclStyle {
    VarLogic,
    Logic,
    Reg,
  } varOpDeclStyle = VarOpDeclStyle::VarLogic;
};
} // namespace circt
 
#endif // CIRCT_SUPPORT_LOWERINGOPTIONS_H