Specification for Topology Ports, Private Component Instances, Topology Templates

[Kronos3]

My initial pass at a spec for exporting topology ports.

TODO:

• Update wiki

Closes #744

[Kronos3]

Some open questions for @bocchino

• Currently this spec states that you must import a topology to be able to connect to ports exported from the topology. Thinking ahead to sub-topologies, I'm not sure if this is right. I think that composing topologies should potentially be done another way:

Without re-usable sub-topologies

topology T1 {
 instance i

 export i.p[0] as schedIn
}

topology T2 {
  # Not sure of an exact syntax, but something to denote that we are bringing in a topology without doing a full white-box import
  topology T1   
}

With re-usable subtopologies

topology T1(constant baseId) {
  instance i1: Component base id baseId + 0
  instance i2: Component base id baseId + 0x20

  connections {
    # ... internal connections ...
  }

  export i1.port as externalPort1
  export i2.port as externalPort2
}

topology T2 {
  topology t1 = T1(0xA)
  topology t2 = T1(0xB)

  connections {
    t1.externalPort1 -> t2.externalPort2
  }
}

[Kronos3]

Notes from our meeting today:

topology T1 {
  instance I2
  export I2.port as schedOut
}

topology T2 { 
  instance I1
  import T1

  connections {
     # flatten + connect
     I2.p1 -> I1.p2
  }

  connections {
     # connect + flatten
     T1.schedOut -> I1.p2
  }
}

Notes:

• Export in topology can name a connection endpoint
• Endpoint can be either a port instance of a component instance or an exported port of a directly imported topology

TODO:

• Updated the algorithm for topology resolution to include exported ports of imported topologies in the set of endpoints

[Kronos3]

This spec update adds two more keywords, another syntax could be:

port P = instance.P

Port exporting is sort of like a named port instance alias so I think this syntax is cleaner

[Kronos3]

Some breaking changes we identified

• Telemetry packets on private instances
  • We don't want to allow referring to a private instance's telemetry channels in a "parent" topology because that would defeat the purpose of private component names
  • We'd need some mechanism to define packets inside the sub-topology but that breaks the current paradigm of defining all the packets in the outermost topology.
  • There doesn't seem to be a good resolution to this at the moment
• Pattern graph resolution: How to connect to "private" cmdDisp
  • We do this connection after all imported subtopologies are flattened.
  • To refer to a private cmdDisp instance inside a sub-topology, you can just name the sub topology and then the connections will be made to a cmdDisp component inside of the refered topology
• Qualfiers on command mnemonics This one is actually fine