Stream port name conventions

Summary

Settle on and document name conventions for stream components.

Motivation

Having a name convention for stream ports makes stream components easier to work with and allows automating the connection of pipelines like this:

pipeline = [component_a, component_b, component_c]
for upstream, downstream in itertools.pairwise(pipeline):
    wiring.connect(m, upstream.o, downstream.i)

Guide- and reference-level explanation

Document the following conventions:

  • Whenever the name of a stream member of the component interface includes an indication of its direction, the indication must match one of the following forms:

    • For In members, either the complete name is i (for components that have one primary input), or the name must start with i_ (for more complex components).
    • For Out members, either the complete name is o (for components that have one primary input), or the name must start with o_ (for more complex components).

  • It is also acceptable to have a name that doesn't indicate directionality explicitly, e.g. requests or packets.

Update existing stream components to follow these conventions.

Drawbacks

None.

Rationale and alternatives

Without a common convention, components will be written with different naming schemes, requiring more care when interconnecting them.

Prior art

Stream ports in LiteX components are conventionally named sink and source.

Unresolved questions

None.

Future possibilities

A connect_pipeline() function can be added that takes an iterable of components and connects them in sequence like shown above.