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.

[fischermoseley]

Thank you! This answer makes sense.

[fischermoseley]

As a follow-up question, how would I connect this bidirectional signal in the instance to an IO buffer? If I make an IO buffer with io.Buffer("io", pin_from_platform_request), this will have i, o, and oe attributes - and I'll need the information from all three, but I can only assign one to the instance pin. Would it be better to forgo explicit IO buffer definition, and rely on the toolchain to infer one instead?

(I'm not sure if GitHub will send a notification for comments on Q&As that are marked as resolved, so I'll mention @whitequark just in case)

[whitequark]

As a follow-up question, how would I connect this bidirectional signal in the instance to an IO buffer?

You can create a SingleEndedPort yourself and pass that.