Idiomatic way to handle top-level IO from within an `Instance` in a submodule

[fischermoseley]

I have a design with a top-level module that has a submodule it shares some signals with, about like the following:

class Foo(Elaboratable):
    def elaborate(self, platform):
        m = Module()
        m.submodules.bar = bar = Bar()

        m.submodules.led = led = io.Buffer("o", platform.request("led", 0, dir="-"))
        m.d.comb += led.o.eq(bar.baz)
        return m

class Bar(Elaboratable):
    def __init__(self):
        self.baz = Signal()

    def elaborate(self, platform):
        m = Module()
        return m

This is simple enough, but now I'd like to add an Instance as a submodule within bar. Among other IO, this instance has a bidirectional inout port, so I've gone ahead and connected an IOPort to it:

class Bar(Elaboratable):
    def __init__(self):
        self.baz = Signal()

    def elaborate(self, platform):
        m = Module()

        m.submodules += Instance(
            "io", "qux", IOPort(1),
            ...
        )

        return m

My question is - if foo is my design's top-level module, what's the most idiomatic way to connect pins obtained via platform.request to my Instance within bar?

Ideally, I'd like to be able to assign the IOPort to some signal that's an attribute of Bar, and then use.eq to connect that to my top-level IO. However, the IOPort class has no .eq() method, so I'm not able to do this. If the signal didn't have to be bidirectional, I could pass a Signal instead of an IOPort in the Instance call and then use .eq(), but unfortunately this signal must be an inout.

Possible solutions I've thought of:

1. Calling platform.request in Bar.elaborate, and taking the pins and passing them to the instance. I can see this being confusing, since it would move some top-level wiring out of Foo.elaborate, which I feel is the natural place for it.
2. Passing the IO pins to Bar's constructor. This doesn't feel right either, as it kind of violates Amaranth's signals-are-members-of-their-modules paradigm.

I'm using Amaranth 0.5.0 on Ubuntu 22.04, if that matters at all. Thank you!

[whitequark]

When you use platform.request(..., dir="-"), you get back a SingleEndedPort object (or possibly a DifferentialPort object, which works the same). Its .io attribute holds an IOValue that you can pass to an Instance like this:

led = platform.request("led", 0, dir="-")
m.submodules += Instance("led_driver_external",
    io_pin=led.io,
    i_value=Const(1),
)

There are a few ways in which you could structure this.

Ideally, I'd like to be able to assign the IOPort to some signal that's an attribute of Bar, and then use.eq to connect that to my top-level IO. However, the IOPort class has no .eq() method, so I'm not able to do this. If the signal didn't have to be bidirectional, I could pass a Signal instead of an IOPort in the Instance call and then use .eq(), but unfortunately this signal must be an inout.

There is an intentional distinction between Value/Signal (unidirectional) and IOValue/IOPort (bidirectional) because they're not really compatible on the netlist level; most of the operations on Value are meaningless on IOValue. This isn't really a language limitation so much as a reflection of the properties of the underlying netlist; before we had that, these meaningless operations would silently do the wrong thing.

1. Calling platform.request in Bar.elaborate, and taking the pins and passing them to the instance. I can see this being confusing, since it would move some top-level wiring out of Foo.elaborate, which I feel is the natural place for it.

I agree with this reasoning.

2. Passing the IO pins to Bar's constructor. This doesn't feel right either, as it kind of violates Amaranth's signals-are-members-of-their-modules paradigm.

There isn't yet a well developed body of I/O components in Amaranth, but the ones that I've developed so far accept a single ports argument in the constructor that is an aggregation of several io.PortLike values.