Interface definition library

[whitequark]

Rendered

[tannewt]

How does this fit into Python's type system? Ideally it could be used for verification.

[whitequark]

How does this fit into Python's type system? Ideally it could be used for verification.

I agree. I'm still exploring options here, so I have no definite answer for you. I am definitely going to make sure that whatever solution we end up with can fit into Python's type system.

[josuah]

This is an interesting approach!

Trying to come-up with an example: we could end-up with something like this?

input_port_template = Signature({
    "data": In[unsigned(4)],
    "vld":  In[Signal(1)],
    "rdy":  Out[Signal(1)]
})

output_port_template = Signature({
    "data": Out[unsigned(4)],
    "vld":  Out[Signal(1)],
    "rdy":  In[Signal(1)]
})

class DebugTap(Elaboratable):
    def __init__(self):
        self.i = Interface(input_port_template)
        self.o = Interface(output_port_template)
        self.debug = Interface(output_port_template)

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

        # pass data from input port to output port
        m.d.comb += self.o.eq(self.i)

        # also pass it to an extra debug port
        m.d.comb += self.debug.eq(self.i)

[josuah]

The __getitem__ binding greatly helps making the syntax more lightweight.

Member(Flow.Out, unsinged(4)) becomes Out[unsigned(4)].

With the [] syntax, I picture In and Out being some mathematical set defined as all possible signatures, from which we would drag one in particular (they [contain] a signature).

Was it voluntary to avoid small wrapper classes?

class In(Flow):
    def __init__(self, signature):
        super().__init__(self, Flow.In, signature):

class Out(Flow):
    def __init__(self, signature):
        super().__init__(self, Flow.Out, signature):

Then they look like some wrapper around a shape, adding a direction to them.

input_port_template = Signature({
    "data": In(unsigned(4)),
    "vld":  In(Signal(1)),
    "rdy":  Out(Signal(1))
})

[galibert]

Why is there both Interface and Signature? What is Interface adding?

[josuah]

I understand Signatures a templates that can be used to create an Interface.

I think the use-case is to be able to define a Signature for commonplace internal ports like Wishbone, FIFOs, valid/ready, etc. and then plug multiple instances of these.

Multiple Interfaces instantiated from the same Signature are likely compatible with each other.

[whitequark]

Yep!

[josuah]

A Signature is a bit like a "class", and an Interface is a bit like an object of that class.

Maybe it is possible to have signatures defined as classes (inheriting from a Signature class), and interfaces defined as objects of these?

Something a bit like how data.Structs are made?

class WishbonePort(data.Interface):
    dat_r:  In(Signal(32))
    addr:   In(Signal(32))
    stb:    In(Signal(1))
    ack:    Out(Signal(1))
    ...

That looks good on paper, but:
Maybe that would require metaclasses.
Maybe that would be too cumbersome to use or implement.

[whitequark]

Maybe it is possible to have signatures defined as classes (inheriting from a Signature class), and interfaces defined as objects of these?

Something a bit like how data.Structs are made?

It's simpler. Any class that has a compatible interface matches a Signature. It doesn't have to be an Interface, it just needs to have the right fields.

[galibert]

Ah, I think I'm starting to see. Signature (or its derivatives) are objects that hold the prototype of the composite port. Interface(signature) is an object instance that essentially replaces the pile-of-signals and give you pluggability. It could be an instanciation method on the signature object, that's just a matter of taste.

[josuah]

It could be an instanciation method on the signature object, that's just a matter of taste.

Indeed, there is a possible confusion for users who would try (A):

1. Define an Interface as a class,
2. Instantiate this class as part of their module (i.e. from __init__).

While it would need to be (B):

1. Define a Signature class,
2. Instantiate a signature object out of this class (eventually inline) as part of an Interface
3. Define an Interface class,
4. Instantiate class taking a single Signature object, as part of a Module (i.e. from __init__).

I suppose (B) which adds more types was chosen instead of (A) for some reason?
I think I missed it, so maybe it helps with the implementation? This would be good enough of a reason for me.

Just trying to spot what I might have missed.

For anyone who would prefer (A), it would likely be possible to implement (B) as part of Interface's __init__, with the Signature that never leaves Interface's __init__().

[josuah]

Answers to my own question: "Why is Signature in addition to Interface?":

The flow!

I imagine it would be possible to have a same Signature used for an Input interface, and a separate Output interface, which are not having the same helper functions depending of their direction (i.e. self.read() or self.write()).

[whitequark]

Yeah

[josuah]

I am trying to summarize a typical usage for that RFC:

# defining the controller side in the signature by convention?
spi_signature = Signature({
    "cs":   Out[Signal(1)],
    "copi": Out[Signal(1)],
    "cipo": In[Signal(1)],
    "clk":  Out[Signal(1)],
})

class SpiControllerInterface(Interface):
    def __init__(self):
        super().__init__(spi_signature)

class SpiPeripheralInterface(Interface):
    def __init__(self):
        super().__init__(~spi_signature)

This looks rather minimal.

And if we add extra helpers:

# defining the controller side in the signature by convention?
spi_signature = Signature({
    "cs":   Out[Signal(1)],
    "copi": Out[Signal(1)],
    "cipo": In[Signal(1)],
    "clk":  Out[Signal(1)],
})

class SpiControllerInterface(Interface):
    def __init__(self):
        super().__init__(spi_signature)

    # for simulation:

    def read_byte(self, data):
        pass

    def write_byte(self, data):
        pass

class SpiPeripheralInterface(Interface):
    def __init__(self):
        super().__init__(~spi_signature)

    # for simulation:

    def transfer_callback(self, fn):
        self.simulation_transfer_callback = fn

Maybe it would be convenient to turn a Resource into a Signature (or rather, the other way around?) to share data formats between those.

[whitequark]

Resources will be more or less replaced by Signatures at a later point.

[josuah]

Here is my attempt at using Records in a way that looks like Interfaces/Signatures,
so that I can write new code ready for when they come:

class SPISignature(Record):
    def __init__(self, *, ctrl, peri):
        return super().__init__([
            ("clk",     1,  ctrl), # ctrl and peri here are to
            ("copi",    1,  ctrl), # tell who drives the signal
            ("cipo",    1,  peri),
            ("cs",      1,  ctrl),
        ])

class SPICtrlInterface(SPISignature):
    def __init__(self):
        super().__init__(ctrl=DIR_FANOUT, peri=DIR_FANIN)

    def spi_ctrl_methods(self):
        pass

class SPIPeriInterface(SPISignature):
    def __init__(self):
        super().__init__(peri=DIR_FANOUT, ctrl=DIR_FANIN)

    def spi_peri_methods(self):
        pass

[jfng]

EDIT: answered or made obsolete by 53e5dc3.

• Would it be possible to expose other Signal parameters to the Member constructor ? I think decoder could be useful here.

• Will there be cases where signature.freeze() is implicitly called ? e.g. when signature.__eq__(), or Interface(signature) are called.

• How would one attach metadata to an Interface ? The RFC mentions that Signature can be subclassed, is this an intended use case ?

[ghost]

I have some (very) minor comments from a read through of the changes since last week.

[ghost]

Suggested change

	* `member.flip()` returns a `flipped_member` where `flipped_member.flow` == `~member.flow`.
	* `member.flip()` returns a `flipped_member` where `flipped_member.flow == member.flow.flip()`.

[ghost]

Suggested change

	1. There is exactly one interface in `rest`, and for every pair of members `first_member` and `rest_member`, `first_member.flow == ~rest_member.flow`.
	1. There is exactly one interface in `rest`, and for every pair of members `first_member` and `rest_member`, `first_member.flow == rest_member.flow.flip()`.

[ghost]

This could also be stated non-pairwise.

[ghost]

It is worth nothing that, depending on the CSS in use, (1) and (2) here may not resemble the list item numbers above. Here they're rendered i. and ii. since they're second-level list items. It may be clearer to say "In both of these cases", and/or to indent this text and the code block at the same level as the sublist as follows:

---

...

• Either:

  1. There is exactly one interface in rest, and for every pair of members first_member and rest_member, first_member.flow == rest_member.flow.flip().
  2. There is any amount of interfaces in rest, and for every pair of members first_member and rest_member, first_member.flow == Out and rest_member.flow == In.

  In both of these cases, the function, for each pair of an input port and an output of port with the same path, the function connects these as follows:

  m.d.comb += output_port.eq(input_port)

Drawbacks

...

[ghost]

I think the overloading of "out"/"output" and "in"/"input" in this illustrative code block has great potential to confuse — e.g. it's the output stream of SequenceSource (which is described in the source with the member Out[16]) from the above example which would be the input_port here, and it's the input stream of the NumberSink (described with In[16] in its signature) which is the output_port.

In the context of knowing only fan-out is supported (as noted later in § Future work), this makes sense, but in the context of case (2) saying "if you have multiple rest interfaces, all their members must be Flow.In", it may read as if there would be multiple input_ports and thus some kind of fan-in instead.

[ghost]

Suggested change

	- Replace the `interface.lib.module.connect` free function with a function `Interface.connect` or a function `amaranth.hdl.dsl.Module.connect`.
	- Replace the `amaranth.lib.module.connect` free function with a function `Interface.connect` or a function `amaranth.hdl.dsl.Module.connect`.

Also, this RFC no longer proposes an Interface class, and Signature.connect wouldn't work.

[whitequark]

We have discussed this RFC on the 2023-08-21 weekly meeting. The disposition was to merge.