spef.py

# vim: set shiftwidth=2 softtabstop=2 ts=2 expandtab:
#
#    Copyright 2022 Google LLC
#
#    Licensed under the Apache License, Version 2.0 (the "License");
#    you may not use this file except in compliance with the License.
#    You may obtain a copy of the License at
#
#        https://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.

import re
import collections
from enum import Enum

from spice_util import NumericalValue, SIUnitPrefix
import circuit

# NOTE(growly): This script encodes my understanding of the SPEF format, which
# alone doesn't completely encode the assumptions made by the tools that read/
# write it. For example, when generated by OpenRCX in OpenROAD, it _seems_
# like names are mapped to the original values they had in the post-mapping
# Verilog netlist. *Seems*. So this script also encodes my guesses about those
# rules too.

class SPEFUnknownDirection(Exception):
  pass


class SPEFUnrecognisedCapLine(Exception):
  pass


class SPEFUnrecognisedSignalRef(Exception):
  pass


class SPEFNoTopDesignName(Exception):
  pass


class SPEFNodeNameError(Exception):
  pass


class SPEFDuplicatePort(Exception):
  pass


class SPEFBadAssumption(Exception):
  pass


class SPEFUnknownUnit(Exception):
  pass


class SPEFNet():

  def __init__(self):
    self.name = None
    # These are connections into/out of the net.
    self.connections = set()

  def __repr__(self):
    out = '{} connections: {}'.format(self.name, len(self.connections))
    return out


class SPEFPort():

  def __init__(self, name, node, direction):
    self.name = name
    self.node = node
    self.direction = direction

  def __repr__(self):
    return '"{}" [{}] {}'.format(self.name, self.node, self.direction)


class SPEFNodeReference():
  """Represents a node name in SPEF type."""

  def __init__(self, src=None, root=None, suffix=None, bus_index=None):
    self.original_name = src
    self.root = root
    self.suffix = suffix
    self.bus_index = bus_index
    self.cell_type = None
    self.internal_to_nets = set()
    self.connection_to_nets = set()

  def __repr__(self):
    out = '"{}": {} {} {}'.format(
        self.original_name,
        self.root,
        self.suffix,
        self.bus_index)
    if self.internal_to_nets:
      out += ' internal to {}'.format(self.internal_to_nets)
    return out

  def IsInternalOnly(self):
    return len(self.connection_to_nets) == 0

  def IsBusReference(self):
    return self.bus_index is not None and self.suffix is None


class SPEFReader():
  COMMENT_RE = re.compile(r'\/\/.*$')

  class Section(Enum):
    HEADER = 1
    NAME_MAP = 2
    PORTS = 3
    PARASITICS_HEADER = 4
    PARASITICS_CONN = 5
    PARASITICS_CAP = 6
    PARASITICS_RES = 7
    PARASITICS_END = 8

  HEADER_PARAM_TO_ATTR_MAP = {
      '*SPEF': 'spef_type',
      '*DESIGN': 'design_name',
      '*DATE': 'date',
      '*VENDOR': 'vendor',
      '*PROGRAM': 'program',
      '*VERSION': 'version',
      '*DESIGN_FLOW': 'design_flow',
      '*DIVIDER': 'divider',
      '*DELIMITER': 'delimiter',
      '*BUS_DELIMITER': 'bus_delimiter',
      '*T_UNIT': 'time_unit',
      '*C_UNIT': 'capacitance_unit',
      '*R_UNIT': 'resistance_unit',
      '*L_UNIT': 'inductance_unit'
  }

  SECTION_TRANSITION_MAP = {
      '*NAME_MAP': (Section.NAME_MAP, True),
      '*PORTS': (Section.PORTS, True),
      '*D_NET': (Section.PARASITICS_HEADER, False),
      '*CONN': (Section.PARASITICS_CONN, True),
      '*CAP': (Section.PARASITICS_CAP, True),
      '*RES': (Section.PARASITICS_RES, True),
      '*END': (Section.PARASITICS_END, False)
  }

  TIME_UNIT_MAP = {
      'NS': SIUnitPrefix.NANO,
  }

  CAPACITANCE_UNIT_MAP = {
      'PF': SIUnitPrefix.PICO,
  }

  RESISTANCE_UNIT_MAP = {
      'OHM': None,
  }

  INDUCTANCE_UNIT_MAP = {
      'HENRY': None,
  }

  # NOTE(growly): SPEFs are produced for a top-level design. Everything within
  # seems somewhat flattened.

  def __init__(self, implicit_ground_net):
    self.ports = {}
    self.signals = {}
    self.name_map = {}
    self.net_descriptions = {}
    self.nodes = {}
    self.capacitors = collections.defaultdict(dict)
    self.resistors = collections.defaultdict(dict)
    self.current_net = None
    self.current_section = SPEFReader.Section.HEADER

    self.pre_section_hooks = {
        SPEFReader.Section.NAME_MAP: self.NormaliseUnits
    }

    self.spef_type = None
    self.design_name = None
    self.date = None
    self.vendor = None
    self.program = None
    self.version = None
    self.design_flow = None
    self.version = None
    self.divider = None
    self.delimiter = None
    self.bus_delimiter = None
    self.bus_delimiter_re = None
    self.time_unit = None
    self.capacitance_unit = None
    self.resistance_unit = None
    self.inductance_unit = None
    self.ground = SPEFNodeReference(src=implicit_ground_net)
    # TODO(growly): This should be provided by the user.

  def AddCapacitor(self, left, right, value):
    left, right = sorted([left, right], key=lambda x: x.original_name if x else '')
    self.capacitors[left][right] = value

  def AddResistor(self, left, right, value):
    left, right = sorted([left, right], key=lambda x: x.original_name if x else '')
    self.resistors[left][right] = value

  def __repr__(self):
    out = ''
    for key, value in self.__dict__.items():
      if not value:
        continue
      if isinstance(value, dict):
        out += '{}: dict with {} entries\n'.format(key, len(value))
      elif value is not None:
        out += '{}: {}\n'.format(key, value)

    for net, net_info in self.net_descriptions.items():
      out += '\t{}: {}\n'.format(net, net_info)
    return out

  def ReadSPEF(self, filename):
    with open(filename) as f:
      for line in f:
        SPEFReader.COMMENT_RE.sub('', line)
        self.ReadLine(line)
    return self.ToModule()

  def ReadLine(self, line):
    # The state machine that determines what kind of line we're reading changes
    # state depending on the first keyword of the current line.
    tokens = line.split()
    if not tokens:
      return
    keyword = tokens[0]
    if keyword in self.SECTION_TRANSITION_MAP:
      new_state, skip_line = self.SECTION_TRANSITION_MAP[keyword]
      if new_state in self.pre_section_hooks:
        hook = self.pre_section_hooks[new_state]
        hook()
      self.current_section = new_state
      if skip_line:
        return

    if self.current_section == SPEFReader.Section.HEADER:
      self.ReadHeader(tokens)
    elif self.current_section == SPEFReader.Section.NAME_MAP:
      self.ReadNameMap(tokens)
    elif self.current_section == SPEFReader.Section.PORTS:
      self.ReadPorts(tokens)
    elif self.current_section == SPEFReader.Section.PARASITICS_HEADER:
      self.ReadParasiticsHeader(tokens)
    elif self.current_section == SPEFReader.Section.PARASITICS_CONN:
      self.ReadConn(tokens)
    elif self.current_section == SPEFReader.Section.PARASITICS_CAP:
      self.ReadCap(tokens)
    elif self.current_section == SPEFReader.Section.PARASITICS_RES:
      self.ReadRes(tokens)
    elif self.current_section == SPEFReader.Section.PARASITICS_END:
      self.current_net = None
    return

  def NormaliseUnits(self):
    def NormalisedUnit(spef_description, mapping):
      multiplier, unit = spef_description.split()
      if unit not in mapping:
        raise SPEFUnknownUnit(self.time_unit)
      prefix = mapping[unit]
      return (float(multiplier), prefix)

    self.time_unit = NormalisedUnit(
        self.time_unit, self.TIME_UNIT_MAP)
    self.capacitance_unit = NormalisedUnit(
        self.capacitance_unit, self.CAPACITANCE_UNIT_MAP)
    self.resistance_unit = NormalisedUnit(
        self.resistance_unit, self.RESISTANCE_UNIT_MAP)
    self.inductance_unit = NormalisedUnit(
        self.inductance_unit, self.INDUCTANCE_UNIT_MAP)

  def ReadHeader(self, tokens):
    if len(tokens) == 1:
      return False
    first = tokens.pop(0)
    if first in self.HEADER_PARAM_TO_ATTR_MAP:
      attr = self.HEADER_PARAM_TO_ATTR_MAP[first]
      setattr(self, attr, ' '.join(tokens))

    if self.bus_delimiter:
      # Annoyingly, some synthesis tools (*COUGH* Genus *COUGH*) use [ and ]
      # to index `generate`d instances and flattened wires. They're nice enough
      # to escape these, at least sometimes, so for now we'll just ignore
      # things that look like bus suffixes but aren't:
      #    lut0.mem\[0\]
      #    lut0.mem_reg\[8\]
      bus_prefix, bus_suffix = self.bus_delimiter
      search_string = (r'(.*)' + r'(?<!\\)' + re.escape(bus_prefix) + r'(.*)' +
                       r'(?<!\\)' + re.escape(bus_suffix))
      self.bus_delimiter_re = re.compile(search_string)

    return True

  def ReadNameMap(self, tokens):
    if len(tokens) != 2:
      return False
    new_name, original_name = tokens
    self.name_map[new_name] = original_name
    return True

  def MapSPEFPortDirection(self, spef_direction):
    if spef_direction == 'I':
      return circuit.Port.Direction.INPUT
    elif spef_direction == 'O':
      return circuit.Port.Direction.OUTPUT
    elif spef_direction == 'B':
      return circuit.Port.Direction.INOUT
    else:
      raise SPEFUnknownDirection(direction)

  def GuessInternalToCurrentNet(self, node):
    if node is None:
      return
    if node not in self.current_net.connections:
      node.internal_to_nets.add(self.current_net)

  # Node names looks like:
  #   - b[0]
  #   - *1423
  #   - *1423:A
  #   - *1423:10
  #   - some/nested/U351:Y
  # where ':' is the delimiter and '/' is the separator mentioned in the SPEF
  # header section.
  #
  # Buses/slices have the BUS_DELIMITERs, e.g. a[0]
  #
  # Renamed things can include cells and wires, but
  #   *1245:5   is a syntheic net derived from the original *1234 net
  #             if the *1234 net was a wire
  #   *1234:A   is a reference to port A on cell *1234, suggesting that
  #             *1234 is a cell
  # The synthesised nets seems to only appear within *D_NET stanzas, so we can
  # hint that they are internally-fabricated when we read those parts.
  # The other hint that we get is that the tage *1234:A might be mentioned in
  # the CONN section of a *D_NET listing with loading or driving information, e.g.
  #   *I *3115:A I *D BUFx2_ASAP7_75t_R
  # suggests that *3115 is a BUFx2_ASAP7_75t_r cell.
  # The *other* biggest hint is that the referenced name is a known *D_NET
  # itself, I suppose.
  def DigestNodeReference(self, name):
    original_name = name
    if original_name in self.nodes:
      return self.nodes[original_name]

    # First split the name in case there are two parts:
    suffix = None
    if self.delimiter is not None and self.delimiter in original_name:
      name, suffix = name.split(self.delimiter)

    # Then map the root name part to whatever it used to be called:
    name = self.name_map[name] if name in self.name_map else name

    # Then check if it's a bus:
    if self.bus_delimiter_re:
      bus_match = self.bus_delimiter_re.search(name)
      if bus_match:
        signal_name = bus_match.group(1)
        index = int(bus_match.group(2))
        node_ref = SPEFNodeReference(src=original_name,
                                     root=signal_name,
                                     suffix=suffix,
                                     bus_index=index)
        self.nodes[original_name] = node_ref
        return node_ref

    node_ref = SPEFNodeReference(src=original_name,
                                 root=name,
                                 suffix=suffix,
                                 bus_index=None)
    self.nodes[original_name] = node_ref
    return node_ref

  def ReadPorts(self, tokens):
    if len(tokens) != 2:
      return False
    name, direction = tokens
    node = self.DigestNodeReference(name)
    if name not in self.ports:
      self.ports[name] = SPEFPort(name, node, direction)
    else:
      raise SPEFDuplicatePort()

  # A CONN line like
  #   *I *2757:C I *D MAJx3_ASAP7_75t_R
  # tells us that the net is driven by port C of cell *2757, which is of type
  # MAJx3_ASAP7_75t_R. We expect *2757 to be mapped to the original name of
  # MAJx3 instance, and for 'C' to be a named port on that instance, too.
  def ReadConn(self, tokens):
    node = None
    while tokens:
      keyword = tokens.pop(0)
      if keyword == '*I':
        # Name of net connected to this one, direction
        name = tokens.pop(0)
        direction = tokens.pop(0)
        node = self.DigestNodeReference(name)
        node.connection_to_nets.add(self.current_net)
        #TODO(growly): What is this doing?
        self.current_net.connections.add(node)
      elif keyword == '*P':
        # Port connection to net
        pass
      elif keyword == '*C':
        # Coordinates
        pass
      elif keyword == '*D':
        # Driving cell
        if node is None:
          raise SPEFBadAssumption('Assume *I would define node name before we saw *D')
        node.cell_type = tokens.pop(0)
      elif keyword == '*L':
        # Loading cell
        pass

  def NodeToSignalName(self, node):
    if node.IsBusReference():
      return node.root
    if node.root is not None and node.suffix is not None:
      if node.bus_index is not None:
        return f'{node.root}.{node.bus_index}{self.delimiter}{node.suffix}'
      return f'{node.root}{self.delimiter}{node.suffix}'
    return node.original_name

  def ExtractBuses(self, nodes):
    buses = {}
    for node in nodes:
      if not node.IsBusReference():
        continue
      if node.root in buses:
        bus = buses[node.root]
        buses[node.root] = (max(bus[0], node.bus_index),
                            min(bus[1], node.bus_index))
      else:
        buses[node.root] = (node.bus_index, node.bus_index)
    return buses

  def CollectBusSignals(self, nodes, module):
    buses = self.ExtractBuses(nodes)
    # Again, make sure the buses are correctly combined into single signals:
    for spef_name, bus in buses.items():
      if spef_name in self.signals:
        continue
      name = circuit.VerilogIdentifier(spef_name).raw
      high_index, low_index = bus
      signal = module.GetOrCreateSignal(name)
      signal.width = high_index - low_index + 1

  def ConnectNode(self, node, to):
    # TODO(growly): Now we have to decide what these nodes mean.
    # We know if we're referring to a bus: a[0]
    # How do we know if we're referring to a port on a cell or a synthetic
    # internal net?
    # 1) We use the hint that the net is internal only to nets, which is to say
    # that it doesn't appear in the "connections" list of a net, with a driving/
    # loading cell name (maybe).
    # 2) We look up whether nets are listed in an input connection to some
    # net, with what driving or loading cell name (though I'm not sure how
    # much of this data is always available)
    signal_name = node.root if node.IsBusReference() else self.delimiter.join(
        (node.root, node.suffix))
    _ = module.GetOrCreateSignal(name)
    if node.IsBusReference():
      print(f'bus: {signal_name}')
    elif node.IsInternalOnly():
      print(f'internal: {signal_name}')
    else:
      print(f'cell:port: {signal_name}')

  def ToModule(self):
    """Generate a Module describing the netlist encoded by the SPEF file."""
    module = circuit.Module()
    if not self.design_name:
      raise SPEFNoTopDesignName()
    module.name = circuit.VerilogIdentifier(self.design_name.strip('"')).raw

    port_nodes = [spef_port.node for _, spef_port in self.ports.items()]
    # Buses are special because we have to deduce their width from references
    # to their substituent signals. Create bus signals for ports.
    self.CollectBusSignals(port_nodes, module)

    # All bus ports should refer to known signals now; go through and create ports:
    for name, spef_port in self.ports.items():
      node = spef_port.node
      signal_name = node.root if node.IsBusReference() else name
      signal_name = circuit.VerilogIdentifier(signal_name).raw
      direction = self.MapSPEFPortDirection(spef_port.direction)
      if signal_name in module.ports:
        if module.ports[signal_name].direction != direction:
          raise SPEFBadAssumption(
              'one bus wire has a different direction to the others')
        continue
      _ = module.GetOrCreatePort(signal_name, width=1, direction=direction)

    #for _, port in self.ports.items():
    #  print(port)
    #for name, port in module.ports.items():
    #  print(port)

    # Make sure any remaining buses are combined:
    self.CollectBusSignals(list(self.nodes.values()), module)

    def SignalOrSlice(node):
      signal_name = circuit.VerilogIdentifier(
          self.NodeToSignalName(node)).raw
      signal = module.GetOrCreateSignal(signal_name)
      if node.IsBusReference():
        net_slice = circuit.Slice()
        net_slice.signal = signal
        net_slice.top = node.bus_index
        net_slice.bottom = node.bus_index
        return net_slice
      else:
        return signal

    # Go through all primitive elements in the network.
    capacitor_count = 0
    for left, subdict in self.capacitors.items():
      for right, capacitance in subdict.items():
        # Make sure both nodes exist.
        connect = []
        for node in (left, right):
          signal_or_slice = SignalOrSlice(node)
          connect.append(signal_or_slice)

        # Create a Capacitor instance.
        capacitor = circuit.Capacitor(connect[0], connect[1], capacitance)
        for signal_or_slice in connect:
          signal_or_slice.Connect(capacitor)
        capacitor.name = f'C{capacitor_count}'
        capacitor_count += 1
        module.instances[capacitor.name] = capacitor

    resistor_count = 0
    for left, subdict in self.resistors.items():
      for right, resistance in subdict.items():
        connect = []
        for node in (left, right):
          signal_or_slice = SignalOrSlice(node)
          connect.append(signal_or_slice)

        resistor = circuit.Resistor(connect[0], connect[1], resistance)
        for signal_or_slice in connect:
          signal_or_slice.Connect(capacitor)
        resistor.name = f'R{resistor_count}'
        resistor_count += 1
        module.instances[resistor.name] = resistor

    for _, node in self.nodes.items():
      signal_name = circuit.VerilogIdentifier(
          self.NodeToSignalName(node)).raw
      if node.IsInternalOnly():
        signal = module.GetOrCreateSignal(signal_name)
        signal.parent_name = node.root
        continue
      if not node.cell_type:
        raise SPEFBadAssumption(
            'I thought non-internal-only nets were all cells? {}'.format(node))
      # So we know we have an instance:
      instance_name = circuit.VerilogIdentifier(node.root).raw
      instance = None
      if instance_name in module.instances:
        instance = module.instances[instance_name]
      else:
        instance = circuit.Instance()
        instance.name = instance_name
        instance.module_name = node.cell_type
        module.instances[instance_name] = instance
      # The node we're inspecting should be a unique reference to a port on the
      # instance, which we model by creating a Connection to the eponymous Port
      # on the Module (which might not exist).
      port_name = circuit.VerilogIdentifier(node.suffix).raw
      connection = circuit.Connection(port_name)
      # TODO(growly): It should be possible to refer to a slice of a bus port
      # here, but I'm not sure how that would look in SPEF.
      if node.IsBusReference():
        # Create a Slice instead of a Signal.
        raise NotImplementedError()
      connection.signal = module.GetOrCreateSignal(signal_name)
      connection.instance = instance
      signal.Connect(connection)
      if port_name in instance.connections:
        raise SPEFBadAssumption(f'How is this port connected twice? {port_name}')
      instance.connections[port_name] = connection

    return module

  def ReadCap(self, tokens):
    left, right, capacitance = None, None, None
    if len(tokens) == 3:
      _, left, capacitance = tokens
    elif len(tokens) == 4:
      _, left, right, capacitance = tokens
    else:
      raise SPEFUnrecognisedCapLine(tokens)
    left_node = self.DigestNodeReference(left)
    right_node = self.DigestNodeReference(right) if right is not None else self.ground
    self.GuessInternalToCurrentNet(left_node)
    self.GuessInternalToCurrentNet(right_node)

    multiplier, unit = self.capacitance_unit
    normalised_value = NumericalValue(float(capacitance) * multiplier, unit)

    # This line:
    #   2 regcontrol_top/GRC/U9409:A regcontrol_top/GRC/U10716:Z 0.622675
    # means that there is a 0.622675<units> capacitance between the _signals_
    # regcontrol_top/GRC/U9409:A and regcontrol_top/GRC/U10716:Z. Those signals
    # are in turn implied to be those which connect to port "A" on cell
    # "regcontrol_top/GRC/U9409" and port "Z" on cell
    # "regcontrol_top/GRC/U10716".
    self.AddCapacitor(left_node, right_node, normalised_value)

  def ReadRes(self, tokens):
    _, left, right, resistance = tokens
    left_node = self.DigestNodeReference(left)
    right_node = self.DigestNodeReference(right)
    self.GuessInternalToCurrentNet(left_node)
    self.GuessInternalToCurrentNet(right_node)
    multiplier, unit = self.resistance_unit
    normalised_value = NumericalValue(float(resistance) * multiplier, unit)
    self.AddResistor(left_node, right_node, normalised_value)

  def ReadParasiticsHeader(self, tokens):
    assert(len(tokens) == 3)
    # TODO(growly): Maybe total_capacitance is not included?
    _, net_name, total_capacitance = tokens
    name = self.MappedName(net_name)

    d_net = SPEFNet()
    d_net.name = name
    d_net.total_capacitance = float(total_capacitance)
    self.current_net = d_net
    self.net_descriptions[name] = d_net

  def MappedName(self, name):
    return self.name_map[name] if name in self.name_map else name