[feature request] Verilog like parameters for FIRRTL module for debugging purposes.

[Nic30]

Verilog like parameters for module for debugging purposes.

Type of issue: feature request

What is the use case for changing the behaviour? It would be great to have a possibility to serialize parameters which were used in during FIRRTL generation for better readability and debugging purposes.

Parameter serialization is not good only for debugging. Some other tools like hwt are currently using custom FIRRTL like format and would like to use this library and format instead to make opensource meta hardware description languages compatible in future.

Is it possible to add module parameters which can be string or arbitrary integer and allow to use parameter ids as values in code?

Impact: API addition (no impact on existing code) Development Phase: request

[seldridge]

Thanks for checking out FIRRTL!

FIRRTL's annotations allow you to express arbitrary information about a circuit, some subset of a circuit (e.g., a module), or meta-information. This information can either be generated by FIRRTL or used by FIRRTL to guide the build process (e.g., to tell you what transforms to run with what parameters). Other tools within the FIRRTL ecosystem (Chisel, other frontends/backends) best integrate with FIRRTL by either consuming or emitting annotations. This is all intentionally done to make annotations act as containers of arbitrary data that you can bend to your needs.

I expect that there would be enough here to fit your use case. However, maybe you could elaborate with an example?

[Nic30]

Hello,

do you meen "info" https://github.com/freechipsproject/firrtl/blob/master/src/main/antlr4/FIRRTL.g4#L145 It may be sufficient.

I was thinking more about verilog paramter/ VHDL generic representation in FIRRTL.

module MyModule :
    const STAGE_CNT: UInt := 4 @[  This constant could be just annotation. ]
    const DATA_WIDTH: UInt := 10 @[ This constant is actually used in width expressions.  ]
    input myinput : UInt<DATA_WIDTH> @[ Input width is specified by constant ]
    output myoutput : UInt<DATA_WIDTH>
    myoutput <= myinput

But as you suggest using annotations is maybe better because all other software would require to evaluate values of the constant over and over. Annotation can be used for an extra specifications of width/value expressions which can be then converted to nice HDL.

module MyModule : @[{"params":[{"name":"DATA_WIDTH", "type": "UInt", "value": "10"}]}]
    input myinput : UInt<10> @[ {"expr": "DATA_WIDTH"} ]
    output myoutput : UInt<10> @[ {"expr": "DATA_WIDTH"} ]
    myoutput <= myinput

Do you know about any other project which does similar thing (Using the annotations to extract some constants as Verilog parameters/VHDL generics to improve HDL readability?)

[seldridge]

So, "Info" (used for source locators) commonly gets confused with annotations. However, they're different (and the info could eventually could be replaced with annotations). Annotations are separate from the IR. They're a generic mechanism to attach metadata to circuit components.

Maybe an example, used in the tests, would help clarify things. https://github.com/freechipsproject/firrtl/blob/master/src/test/resources/annotations/SampleAnnotations.anno.json shows annotations (serialized as JSON) that control which modules in a circuit will be inlined. Those annotations are then consumed by FIRRTL's inline transform and will inline specific modules or instances. Those annotations can be written manually, emitted by Chisel (via it's inlining API), emitted by another tool or language, or emitted by FIRRTL transforms.

FIRRTL (as far as I'm aware) doesn't have a concept of parameters (though it can have uniferred widths at certain times). It does have black box support and the generation of a FIRRTL circuit or Verilog to fill that black box can be controlled via annotations. E.g., the FIRRTL compiler can call the Chisel compiler with certain module parameters (that are communicated via an annotation) to populate that black box. Additionally, you could use FIRRTL to regenerate a module with different parameters if the annotations communicated enough information to do so. Essentially, annotations should let you do whatever you want.

However, usually you want to handle complex parameterization in a higher level generator language and not in the IR. (Chisel naturally interfaces with FIRRTL, but hwt, Magma, Spinal, are all playing in this generator space.) FIRRTL is trying to solve a different problem, namely, automating specialization as opposed to complex parameterization. With that model, the underlying Verilog target is a fixed circuit stripped of parameterization.

I'm not aware of other projects doing this or other (program) IRs that deal with parameterization natively.

That being said, one thing that is currently close in FIRRTL is having Chisel enumerated types emit annotations to cause FIRRTL's verilog emitter to emit well-named localparams that match the enum names for better Verilog readability.

[Nic30]

Verilog names for enum values and parameters would be great. But the simulation agents are the things I can not live without. I can not find an example of any simulation agent for any interface in chisel3. Does this mean that there is not possible to define custom agents for simulator in chisel3? It is possible to directly access simulator trough java native c calls. I have similar feature and it is very very useful. If chisel3 does not have it maybe I can help.

(I thinking about agent logic written in c++ and interface for scala to make testing easier.)

[seldridge]

(I'm traveling so will be slow to respond.)

Not sure what you mean about "simulation agents". Maybe you could clarify with an example?

We're working towards genericizing what a simulation backend is and there have been dicsussiona about how to interface with the outside world (via Verilog DPI/VPI or otherwise). Currently simulation is either Verilog or FIRRTL Interpreter/Treadle (a faster, newer replacement for the interpeter). Some mixture of these or interfacing with other tools sounds interesting. There's been a push to make these sufficient without having to rely on C++, though very old Chisel (2) designs did do this. Hardfloat is one notable example that I'm aware of.

[Nic30]

UVM interface agent, slide 52 basically it is object which manages communication between interface in simulator and the code of test. For example agent for AXI-stream interface allows you to receive or send frames from this interface in test code.

UVM interface agents can be interpreted in scala if VPI or other simulator interface is available. Note that if you have interface agents you can just write verifications in scala = greatly simplify the verification process.

I was thinking that there was some simulator interface and Interface agents implemented. How can I help with simulator abstraction an possible implementation of VPI for chisel3+?

[seldridge]

Cool, so something that interfaces the hardware with some model of the outside world. Sounds useful to me. I'm not aware of this existing explicitly, but I know people have written custom C++ test benches that use VPI (I think I did this for loading memories a long time ago, though there's a better solution for doing that currently). I'm just not aware of this already being there or in one of the backends. Maybe @chick can correct me.

I don't have UVM experience, but @jackkoenig may have some thoughts there. Also, some of the industry folks have been trying to align things with more standard verification methodologies (which usually means UVM). Likely @chick has some thoughts, too.

So I view all of this as feature requests that'll get implemented given a sufficiently motivated contributor. As this hasn't come up, yet, I expect that would be you! Usually that's a request for comments (RFC) as a GitHub issue followed by a GitHub PR. Some concrete examples in the RFC and some options on how this could be implemented with the associated tradeoffs usually is how that goes (we're working on formalizing this process to make it more clear).

[Nic30]

OK, I do not know java native calls and VPI much. I will look at it and try to write some demonstrative example of usage. Maybe I am motivated, but I have lot of work to do, but I try to do my best.