topology

The topology statement is a means of labeling a topology with a human-readable name. This label can be applied to complex hierarchical bundles of signals that participate in the topology system.

Named topologies can also be used in the definition of signal constraints.

The topology statement is only valid within the pcb-module context.

Signature

[public|private] topology <NAME> (<EXP>)

Notes:

• The <NAME> must be a valid Symbol that identifies this topology.
• The <EXP> is expected to resolve to KeyValue where the key and value are Port objects that resolve to the endpoints of a topology.
• Each port can be a SinglePin, Bundle, or PortArray.
• The endpoint ports must be of the same type. If each port is a bundle, the bundle types must also match type.
• The endpoint ports must be unique - ie, you should not pass the same port as both endpoints.
• Making a topology public allows referencing that topology within an instance of the containing module in the same way that making a port public works. Topologies are private by default.

Usage

The topology statement is an aid in debugging and documenting a signal integrity route defined in the topology system. The basic concept is to add a label for any topology or constraint that is bound by the provided endpoints.

Here is an excerpt from the ethernet-io project:

    within [src, dst] = constrain-topology(P.MDI => conn-IF, mdi-constraint):
      require prot-MDI : dual-pair[NUM_PAIRS_1000Base-T] from esd

      topology MDI (src.TP => dst.TP)
      for i in 0 to NUM_PAIRS_1000Base-T do:
        topo-pair(src.TP[i] => prot-MDI[i].A => prot-MDI[i].B  => dst.TP[i])

If we look in the issues list of the physical design tool when routing these signals, we will see messages like these when these routes have not satisfied their constraints:

This issue is telling us that the intra-differential-pair skew timing constraint is violated in the current realized routes. We would need to add a signal tuning section to add skew matching.

In this case, notice the core. prefix on the MDI symbol name because the topology statement was defined in the core module instance.

The topology statement can come before the construction of the topology-segment statements and other constraint constructs. What matters is that the endpoints of those topologies and constraints match with the endpoints defined for the topology statement.

You can dot into a topology to get sub-topologies. You can also use topologies or sub-topologies to define timing or loss constraints e.g.:

  port src : diff-pair
  port dst : diff-pair
  topology diff-topo (src => dst)
  timing-difference(diff-topo.P, diff-topo.N) = TimingDifferenceConstraint(-0.5e-12, 0.5e-12)
  ; Note: The topology-segments and nets between src and dst must still be defined

topology-ends(<NAME>) can be used to retrieve the original ends of a topology or sub-topology. Ends will be returned as a KeyValue pair. e.g. to continue the example above topology-ends(diff-topo) would return src => dst.

If you want to write helper functions that can operate on named topologies or KeyValue pairs of ports you can match against the TopologyName type. e.g.:

defn as-ends (arg:KeyValue<JITXObject, JITXObject>|JITXObject):
  match(arg):
    (name:TopologyName): topology-ends(name)
    (kv:KeyValue<JITXObject, JITXObject>): kv
    (other:?): throw(Exception("Expected a KeyValue pair of ports or a named topology. Got %_" % [other]))