defaults.yml

# Core configuration options and defaults for hammer-vlsi.
# The values specified in this file are the defaults.
# e.g. foo: "bar" in this file means that the default setting for foo is "bar".

vlsi.core:
  # Path(s) to out-of-tree hammer technology libraries.
  technology_path: ["${vlsi.builtins.hammer_vlsi_path}/technology"]
  technology_path_meta: subst

  # Technology to use. hammer-vlsi will read this and load the appropriate technology libraries.
  technology: "saed32"

  # Technology node dimension (nm) to use.
  # Some tools change what they do as this changes.
  # TODO: move this to vlsi.technology (or technology.core) ucb-bar/hammer#317
  node: 32

  # Path(s) to synthesis tools.
  # Add the built-in path to synthesis tools.
  synthesis_tool_path: ["${vlsi.builtins.hammer_vlsi_path}/synthesis"]
  synthesis_tool_path_meta: subst

  # Path(s) to place and route tools.
  # Add the built-in path to place and route tools.
  par_tool_path: ["${vlsi.builtins.hammer_vlsi_path}/par"]
  par_tool_path_meta: subst

  # Path(s) to drc tools.
  # Add the built-in path to drc tools.
  drc_tool_path: ["${vlsi.builtins.hammer_vlsi_path}/drc"]
  drc_tool_path_meta: subst

  # Path(s) to lvs tools.
  # Add the built-in path to lvs tools.
  lvs_tool_path: ["${vlsi.builtins.hammer_vlsi_path}/lvs"]
  lvs_tool_path_meta: subst

  # Path(s) to sram generator tools.
  # Add the built-in path to sram generator tools.
  sram_generator_tool_path: ["${vlsi.builtins.hammer_vlsi_path}/sram_generator"]
  sram_generator_tool_path_meta: subst

  # Synthesis tool to use.
  # Currently we can choose from a selection of built-in tools which hammer-vlsi supports.
  synthesis_tool: "nop"

  # Place and route tool to use.
  par_tool: "nop"

  # DRC tool to use.
  drc_tool: "nop"

  # LVS tool to use.
  lvs_tool: "nop"

  # SRAM Generator tool to use.
  sram_generator_tool: "nop"

  # Maximum threads to use in a CAD tool invocation.
  max_threads: 1

# TODO ucb-bar/hammer#317 move these to technology.core (discussion to be had)
vlsi.technology:
  # Placement site for macros. (Optional[str])
  # Typically specified in standard cell LEFs.
  # See http://www.ispd.cc/contests/18/lefdefref.pdf
  # Required for some CAD tools to function properly.
  placement_site: null

  # Top cut/via layer for blockage under bumps. (Optional[str])
  # Only used if using vlsi.inputs.bumps
  # TODO: remove this after stackup supports vias ucb-bar/hammer#354
  bump_block_cut_layer: null

  # Extra semiconductor IP libraries/stdcell libs/hard macros. (List[ExtraLibrary])
  # Used for non-technology-vendor-provided custom IP blocks.
  # ExtraLibrary is a struct with two fields:
  # - prefix (Optional[PathPrefix]) - struct that holds a prefix and path.
  #   - path (str) - Path for the prefix below.
  #     For example, if the path is /foo/bar/pll, then a reference of pll/test.txt (assuming 'pll' is the prefix) will
  #     resolve to /foo/bar/pll/test.txt.
  #   - prefix (str) - prefix used for referencing in the library.
  #     For example, if "lef file" in HammerLibrary references "pll/layout/pll.lef", then the path would be "pll".
  # - library (hammer_tech.HammerLibrary) - IP library to add.
  # Extra libraries are added at the end of the library list, in the event that order matters.
  extra_libraries: []

  # Extra information about macro sizes.
  # type: List[MacroSize]
  # MacroSize is a struct with the following fields:
  # - library (str): IP library of the macro. Leave blank if unknown
  # - name (str): Name of the macro block
  # - width (float): Width of the macro in um
  # - height (float): Height of the macro in um
  extra_macro_sizes: []

  # Path where tarballs have been extracted.
  # type: Optional[str]
  # Note: this setting can be specified per-technology using
  # technology.<tag>.extracted_tarballs_dir as well.
  # The technology-specific setting takes precedence if it exists.
  # For example, if the technology plugin defines a tarball foobar.tar.gz,
  # and this is set to /opt/test, then /opt/test/foobar.tar.gz/ should contain
  # the extracted contents of foobar.tar.gz.
  # If this is not specified, then the tarballs will be extracted to obj/<tech_dir>/extracted/.
  extracted_tarballs_dir: null

cadence:
  # Path to the folder with defaults.yml for common Cadence settings.
  common_path: "${vlsi.builtins.hammer_vlsi_path}/common/cadence"
  common_path_meta: subst

# General VLSI inputs.
# These will vary per run of hammer-vlsi.
vlsi.inputs:
  # Supply voltages and names
  # Supply Struct:
  #   name (str) - The name of your supply's net
  #   pin (Optional[str]) - The cell pin that this net should drive, no pins are connected when omitted
  #   tie (Optional[str]) - Another supply this supply is tied to. Nets with this set will  not end up in your final layout.
  #   weight (Optional[int]) - The weight of this supply when building power straps (larger number = more straps).
  #     Not used for grounds. Mandatory, but defaults to 1 if omitted.
  # power (List(Supply)): A list of of all power net(s) in the design
  # ground (List(Supply)): A list of all ground net(s) in the design
  # VDD (str): The default voltage of the primary power net
  # GND (str): The default voltage of the primary ground net
  supplies:
    power: [{name: "VDD", pin: "VDD"}]
    ground: [{name: "VSS", pin: "VSS"}]
    VDD: "0.85 V"
    GND: "0 V"


  hierarchical:
    # Hierarchical par mode. (str)
    # Valid options:
    # flat - Perform a flat place and route run.
    # leaf - Leaf module in a hierarchical run - same as flat except that an extra write_ilm step is added.
    # hierarchical - Module which has sub-modules which are also hierarchical.
    # top - Top module in a hierarchical run - runs an extra assemble_design step.
    mode: flat

    # Top RTL module in the hierarchical flow. (str)
    # Not to be confused with synthesis.inputs.top_module which specifies the synthesis module for this run.
    # (e.g. synthesis.inputs.top_module is used for a sub-synthesis run)
    top_module: "null"

    # Used by HammerDriver to generate configurations for hierarchical place-and-route.
    # type: (str)
    # Valid options:
    # none - Do nothing. (default)
    # manual - Read from hierarchical_manual_* below.
    # from_placement - Generate from "hierarchical" entries in vlsi.inputs.placement_constraints.
    config_source: none

    # Manual hierarchical definitions used only if hierarchical_definition_source is set to manual mode.
    # Should be a list along the lines of [{"module1": "module1_sub1", "module1_sub2", "module2": "module2_sub"}].
    manual_modules: []

    # Manual hierarchical placement constraints used only if hierarchical_definition_source is set to manual mode.
    # Should be a list along the lines of [{"module1": <list of PlacementConstraint structs>}].
    manual_placement_constraints: []

    # Manual hierarchical constraints. Overrides generic constraints on a per module basis.
    # Should be a list along the lines of [{"module1": <list of other hammer constraints>}].
    # For example [{"mod1": [vlsi.inputs.default_output_load: 2], "mod2": [vlsi.inputs.clocks:<clock constraints>] }].
    constraints: []

  # ILMs for hierarchical mode.
  # ILM struct (ILMStruct) members:
  # dir (str) - directory to the ILMs (...ILMDir)
  # data_dir (str) - data directory to the ILMs (...ILMDir/mmmc/...)
  # module (str) - module name for the ILM
  # lef (str) - path to the LEF file
  # gds (str) - path to the GDS file
  # netlist (str) - path to the netlist file
  ilms: []

  # Muli-mode multi-corner setups, overrides supplies
  # MMMC struct members:
  # name (str) - name of the corner.
  # type (str) - One of the following:
  # - "setup" (corner used for setup timing)
  # - "hold" (corner used for hold timing)
  # - "extra" (misc. corner potentially used for power analysis
  # voltage (str) - voltage of the corner should match tech json
  # temp (str) - temperature of the corner should match tech json
  mmmc_corners: []

  # Clock ports of the top-level module.
  # type: List[ClockPort]
  # TODO: support multiply_by in generated clocks
  # Clock struct members:
  # name (str) - Name of the clock port.
  # period (TimeValue) - Clock port period. e.g. "1 ns", "5ns". Default units: ns
  # path (str) - Optional. If specified, this is the RTL path to the clock. Otherwise, the path is the same as the name.
  # uncertainty (TimeValue) - Optional. Clock uncertainty. e.g. "1 ns", "5ns". Default units: ns
  # generated (bool) - Optional. If specified this clock is generated from another clock, must specify source_path and divisor
  # source_path (str) - Required if generated. The path of the clock that this clock is generated from.
  # divisor (int) - Required if generated. The amount this generated clock is slowed from the source clock e.g. 2 => this clock will be two times slower than the source clock.
  #   We are constrained to integers by SDC.
  clocks: []

  # Default output pin load capacitance.
  # Default: 1pF
  default_output_load: 1

  # List of output load constraints.
  # Each item in the list should be a struct with the following members:
  # name (str) - Name of the output load (e.g. io_out)
  # load (float) - Output load capacitance in pF.
  output_loads: []

  # List of delay constraints.
  # These either constrain inputs to arrive after a certain delay relative
  # to the clock or constrain outputs to arrive a certain delay before
  # the clock edge.
  # Each item in the list should be a struct with the following members:
  # name (str) - Name of the I/O being delayed.
  # clock (str) - Name of the clock that this delay is based on.
  # direction (str) - Gives the direction of the I/O. Should be one of:
  # - "input"
  # - "output"
  # delay (TimeValue) - Delay applied to the I/O.
  delays: []

  # List of custom sdc constraints to use. (List[str])
  # These are appended after all other generated constraints (clock, pin, delay, load, etc.).
  custom_sdc_constraints: []

  # List of placement constraints for floorplanning.
  # Each item is a struct member:
  # path (str) - Path to the given instance
  # type (str) - One of the following:
  # - "dummy" (does nothing with this constraint)
  # - "placement" (creates a placement constraint for an instance)
  # - "toplevel" (top-level chip dimensions; may only occur once, for the top-level module)
  # - "hardmacro" (places this hard macro at a particular spot)
  # - "hierarchical" (marks this instance as part of hierarchical place and route)
  # - "obstruction" (creates a blockage at a particular spot; see obs_types)
  # TODO(edwardw): add rotation
  # x (float) - x coordinate in um
  # y (float) - y coordinate in um
  # width (float) - width in um
  # height (float) - height in um
  # margins (Optional[Margins]) - margins for the top-level module (i.e. only only for a toplevel constraint). Contains the following keys:
  # - "left" - margin from the left side of the core PNR area to the edge of the chip
  # - "right" - margin from the right side of the core PNR area to the edge of the chip
  # - "top" - margin from the top side of the core PNR area to the edge of the chip
  # - "bottom" - margin from the bottom side of the core PNR area to the edge of the chip
  # top_layer (str) - Optional: Specifies the highest layer used by this hardmacro
  #   If specified will be used to keep other wires away from this hardmacro
  # layers (List[str]) - Optional: only used for obstruction type. 
  #   If specified, a list of strings that enumerates layer(s) blocked by the obstruction otherwise all layers are blocked
  # obs_types (List[str]) - Required for obstruction type. A list of one or more of the following:
  # - "place" - This obstruction type stops the placement of standard cells inside it
  # - "route" - This obstruction type stops all routing inside it
  # - "power" - This obstruction type stops only power routing/straps inside it
  placement_constraints: []

  # Don't use list mode. (str)
  # Specifies where to get the list of cells to not use.
  # These cells can be specified in a number of ways:
  # - "MY_CELL" (cell MY_CELL in any library)
  # - "*/MY_CELL" (cell MY_CELL in any library)
  # - "*CELL" (any cell that ends with CELL in any library)
  # - "*_CELL_*" (any cell that matches the wildcard *_CELL_* in any library)
  # - "CELL_*_IVX" (any cell that matches the wildcard CELL_*_IVX in any library)
  # - "MY_LIB/*" (any cell under the library MY_LIB)
  # - "MY_LIB/CELL*" (any cell that matches the wildcard CELL* under the library MY_LIB)
  # Valid options:
  # auto - Use the technology plugin's value for the don't use list
  # manual - Use the list from the variable below, overriding the technology plugin
  # append - Append the manual list to the technology plugin's list
  dont_use_mode: auto
  # Optional: List of cells to mark as don't use
  # type: List[str]
  dont_use_list: []

  # Power specification mode. (str)
  # Specifies how to obtain a power specificaiton. Power specifications often setup
  # how many power nets you have, what their names and voltages are, as well as
  # how many domains you have and what their relation is.
  # Valid options:
  # auto - Hammer will generate a power specification based on other settings,
  #        including vlsi.inputs.supplies.
  # manual - Use the value given in power_spec_contents with type given in power_spec_type
  # empty - Do not use any power specification
  power_spec_mode: empty
  # Optional: Power specification type. (str)
  # Specifies what kind/version/type of power specification to use
  # Valid options:
  # cpf - Use the common power format commonly used in Cadence tools
  # upf - Use the universal power format, IEEE 1801-2015
  power_spec_type: null
  # Optional: Contents of a power specification in the above type (str)
  power_spec_contents: null

  # SRAM Parameters
  sram_parameters: []

  # Bumps settings mode. (str)
  # Specifies how to setup the bumps for your design.
  # Currently only support rectangular, evenly-spaced grids
  # Bumps are numbered starting with 1,1 in the lower left
  # Unassigned bumps will be removed, bumps with no_connect set will be present but unconnected
  # Valid options:
  # manual - Use the bumps struct to create and assign bumps
  # empty - Do not add any bumps
  bumps_mode: empty
  # Bumps settings struct only required if above key is set to manual
  # BumpsDefinition struct members
  bumps:
    # x (int) - number of bumps in the x dimension
    x: 0
    # y (int) - number of bumps in the y dimension
    y: 0
    # pitch (float) - pitch of bumps in microns
    pitch: 0.0
    # cell (str) - Name of the default bump cell
    cell: ""
    # assignments - List of BumpAssignment structs. You must specify one of name or no_connect.
    # If both are specified the bump will be left unconnected
    #  - name (Optional[str]) - The name of the net being assigned to a bump
    #  - no_connect (Optional[bool]) - If True the bump will be present but unconnected
    #  - x (Decimal) - The X coordinate of the bump assigned to this net
    #  - y (Decimal) - The Y coordinate of the bump assigned to this net
    #  - custom_cell (Optional[str]) - Cell name (MACRO name) of a custom bump cell in place of the default for this bump. You must also specify the LEF and GDS for this bump in extra_libraries.
    assignments: []

  # Pin placement mode. (str)
  # Specifies how to arrange pins for your design.
  # Valid options:
  # none - This mode lets the CAD tool do whatever it wants (providing no constraints).
  #   Typically this is sane but unpredictable.
  # generated - Use the assignments list below
  # auto - (not implemented yet) looks at the hierarchy and guess where pins should go
  pin_mode: none
  pin:
    # List of PinAssignment Structs.
    #   You must specify pins and one of either preplaced or layers and side.
    # - pins (str) - The name(s) of pins that will be assigned. All current backends support
    #   * as wildcards in the pin names. So "*" for all pins or "io_tl_a*" for all pins that
    #   start with "io_tl_a".
    # - side (Optional[str]) - The side of the chip/block these pins will be placed along.
    #   One of "left", "right", "top", "bottom"
    # - layers (Optional[List[str]]) - The metal layers that these pins will be placed on.
    # - preplaced (Optional[bool]) - If true, these pins are preplaced by some internal block or macro.
    #   This is telling the tool that these pins are on an internal block and I want them
    #   "placed" where they are currently on the internal block. This can be used for IP
    #   that directly connects to bumps, or signals that will be connected by abutment,
    #   and much more.
    assignments: []

vlsi.submit:
  # The submit command to use. "none", "local", or null will run on the current host. See hammer_submit_command.py for other options.
  command: "local"
  # type: List[Dict[str, Dict[str, Any]]]
  # The list substitutes settings in order of appearance, and the first Dict key is the command.
  # The second dict key is the name of that command's setting, followed by whatever type it takes.
  settings: []

# Specific inputs for the synthesis tool.
# These inputs are the generic inputs; specific tools ("CAD junk") may require
# additional inputs.
# They will vary per run of hammer-vlsi.
synthesis.inputs:
  # Input files.
  # Typically a list of Verilog/VHDL files, depending on the synthesis tool.
  input_files: []

  # Top RTL module.
  # Set to null to not specify from the JSON.
  top_module: null

# Syntheis tool settings
synthesis:
  # Clock gating mode.
  # type: str
  # This tells the tool how to handle clock gating.
  # Valid options:
  # auto - Turn on automatic clock gating inference in CAD tools.
  # empty - Do not do any clock gating.
  clock_gating_mode: auto

# inherit settings from vlsi.submit but allow us to override them
synthesis.submit:
  command: "${vlsi.submit.command}"
  command_meta: lazysubst
  settings: "vlsi.submit.settings"
  settings_meta: lazycrossref

# Specific inputs for the place and route tool.
# These inputs are the generic inputs; specific tools ("CAD junk") may require
# additional inputs.
# They will vary per run of hammer-vlsi.
par.inputs:
  # Input post-synthesis netlist files.
  # Typically a list of Verilog/VHDL files, depending on the tool.
  # For place and route, these should typically be post-synthesis netlists.
  input_files: []

  # Top RTL module.
  top_module: null

  # Optional: SDC input file from post-synthesis.
  # Leave as null to not use.
  post_synth_sdc: null

  # GDS output map mode.
  # type: str
  # The GDS map file shows how/what layers should be put in the GDSII file.
  # Valid options:
  # auto - Use the technology plugin's value for the map file.
  # empty - Don't use a map file at all and let the cad tool do what it wants.
  #         This often results in a complete but arbitrary assignment.
  # manual - Read the map file from the variable below, overriding the technology plugin.
  gds_map_mode: auto
  # Optional: GDS map file path. Used only if gds_map_mode above is set to manual.
  # type: Optional[str]
  gds_map_file: null

  # If true, tell the place and route tool to merge any library/macro GDSes into
  # the final GDS.
  # type: bool
  gds_merge: false

# Place-and-route settings
par:
  # Submission command settings
  # inherit settings from vlsi.submit but allow us to override them
  submit:
    command: "${vlsi.submit.command}"
    command_meta: lazysubst
    settings: "vlsi.submit.settings"
    settings_meta: lazycrossref

  # Power straps configuration.
  # Valid options are:
  # - empty - Specify no power straps
  # - manual - Specify the contents of a manual TCL script to use, specified in power_straps_script_contents.
  # - generate - Generate power straps from Hammer IR.
  power_straps_mode: empty
  power_straps_script_contents: null

  # Spacing around blocks and hardmacros in microns
  # Used by power straps and floorplanning
  blockage_spacing: 0.0

  # If power_straps_mode is 'generate', which method to use.
  # Currently, the valid options are:
  # - by_tracks - Specify the power strap plan per layer in terms of tracks
  generate_power_straps_method: "by_tracks"

  # Default settings for power strap generation modes
  # Keys are the valid values of the 'generate_power_straps_method' key above
  generate_power_straps_options:
    by_tracks:
      # Spacing from end of strap to a block or blockage
      # Overrideable by appending _<layer name>
      blockage_spacing: "par.blockage_spacing"
      blockage_spacing_meta: lazycrossref

      # Number of routing tracks to be consumed by an individual strap
      # Overrideable by appending _<layer name>
      track_width: 5

      # The first track to contain a power stripe
      # Overrideable by appending _<layer name>
      # TODO(johnwright): include an auto-center option
      track_start: 0

      # Number of routing tracks between sets of straps (0 is recommended)
      # Overrideable by appending _<layer name>
      track_spacing: 0

      # Ratio of total routing tracks to dedicate to power straps, which is used to calculate set pitch
      # Overrideable by appending _<layer name>
      power_utilization: 0.1

      # Layers to put power pins on
      pin_layers: []

      # List of layers on which to place power straps (std cell rail layer is implied - do not include it)
      strap_layers: []

mentor:
    # Path to the folder with defaults.yml for common Mentor settings.
    common_path: "${vlsi.builtins.hammer_vlsi_path}/common/mentor"
    common_path_meta: subst

# DRC settings
drc.inputs:
  # Top RTL module.
  top_module: null

  # Input layout file
  # Typically a GDSII file from the place and route tool
  layout_file: null

  # Valid modes are auto, manual, prepend, and append
  additional_drc_text_mode: "auto"
  # Custom DRC command text to add after the boilerplate commands at the top of the run file
  additional_drc_text: ""

# inherit settings from vlsi.submit but allow us to override them
drc.submit:
  command: "${vlsi.submit.command}"
  command_meta: lazysubst
  settings: "vlsi.submit.settings"
  settings_meta: lazycrossref

# LVS settings
lvs.inputs:
  # Top RTL module.
  top_module: null

  # Input layout file
  # Typically a GDSII file from the place and route tool
  layout_file: null

  # Input list of schematic files
  schematic_files: []

  # Input list of ILMStructs
  ilms: []

  # Valid modes are auto, manual, prepend, and append
  additional_lvs_text_mode: "auto"
  # Custom LVS command text to add after the boilerplate commands at the top of the run file
  additional_lvs_text: ""

lvs.submit:
  command: "${vlsi.submit.command}"
  command_meta: lazysubst
  settings: "vlsi.submit.settings"
  settings_meta: lazycrossref

# inherit settings from vlsi.submit but allow us to override them
sram_generator.submit:
  command: "${vlsi.submit.command}"
  command_meta: lazysubst
  settings: "vlsi.submit.settings"
  settings_meta: lazycrossref

technology.core:
    # Key name for the technology stackup
    # This should exist in the stackups list in the tech json
    # type: str
    stackup: null
    # Key name for the technology's special cells
    # This should exist in the special_cells list in the tech json
    # type: str
    special_cells: null
    # This should specify the TOPMOST metal layer the standard cells use for power rails
    # Note that this is not usually stackup specific; it is based on the std cell library
    # type: str
    std_cell_rail_layer: null
    # This is used to provide a reference master for generating standard cell rails
    # Can be a wildcard/glob
    # type: str
    tap_cell_rail_reference: null