Readable RTL output is a non-goal

[sampsyo]

Just jotting down a brief thought here that I occasionally find myself repeating, so that I have somewhere to link to if it comes up again. But thoughts/comments are of course welcome!

Calyx has not historically prioritized generating "readable" Verilog, and I think we should continue to de-prioritize it. Calyx aims to address many of the popular frustrations with traditional HLS, and non-human-readable Verilog generation is a common complaint about HLS tools, so I think this decision deserves some justification.

As I see it, the people who want readable (and editable!) RTL from HLS tools are RTL engineers. It's a remarkable achievement of modern HLS compilers that there are many mainstream hardware engineers who are already comfortable with RTL but who see HLS as a convenient shortcut that speeds up their development work. For this use case, HLS serves as a labor-saving device that helps obtain more-or-less the Verilog you would have written anyway: it can take the drudgery out of inserting pipeline registers, for example, but shouldn't be expected to do anything you couldn't do yourself, given enough time. In that setting, it makes lots of sense that you would want to read and modify your HLS-generated Verilog. Some good reasons include:

1. You want to know what decisions the tool made—for example, how it allocated operations to pipeline stages.
2. You need your hand-written RTL to interact with the generated RTL.
3. The HLS compiler may make suboptimal decisions, and you can fix them after the fact.
4. The HLS compiler may generate incorrect code, and you can fix the bug.

Calyx targets a different kind of scenario. We aim to support ADLs that fully abstract over RTL as a backend. Correctness, performance, and interfaces should all manifest in the source language, not in the generated Verilog.

By way of analogy, we treat Verilog as an assembly language for the target hardware. In the same way that C programmers sometimes but not often need to peek at and modify the generated assembly code, we expect ADL programmers to rarely need to think about the fact that there is Verilog under the hood. It needs to be there, to cope with edge cases and worst-case scenarios, but these should be the exception and not the rule. (In a fantasy world, we'd be generating a proper assembly language like Reticle or MLIR hw instead of Verilog, but that remains a fantasy for now.)

As a consequence, we aim to satisfy the above needs in other ways:

1. ADL compilers, and the Calyx toolchain itself, should be able to report their nontrivial implementation decisions in a human-readable way, independent of the generated RTL.
2. To the extent that Calyx-generated hardware needs to interact with legacy RTL, we should endeavor to build new, language-independent interfaces to make the obligations clear on both sides.
3. ADLs should give programmers ways to directly control important decisions that affect performance without manually modifying the compiler's output, which is a terrible way to do it anyway.
4. Bugs in the Calyx compiler are our fault and we should fix them. End users should not be forced into a state of learned helplessness where they know that compiler bugs are so common as to be unavoidable.

[rachitnigam]

Thanks for writing this down @sampsyo. One axis of this discussion I'd like to add to: sometimes when people say they want "readable RTL", what they might really want is to understand the behavior of the RTL. For example, when you have some control signal on your critical path, you don't really want to know what RTL is doing. You want to know what ADL-level code is causing the problem. Similarly, you might want "readable RTL" so that you could debug. If you could just debug the ADL, maybe you wouldn't want the RTL level code.

One line of reasoning to apply this is to is people wanting readable netlists (is this even a thing?). Surely you sometimes want to know what the netlist is doing but in most cases, we are okay letting the tools under the RTL flow do their thing. However, once you get to floorplanning, you might want to break apart the abstractions a little bit to understand how to best place things. It is worth distinguishing between what abstractions are held throughout the pipeline and which ones might need to be exposed latter down the pipeline

[cgyurgyik]

+1. While Calyx abstracts over RTLs as a backend, we still emit RTL at the end of the day. If a Calyx program was producing correct behavior on 3/4 RTL backends, and the fourth outputted binary, it would be a very sad day for that Calyx compiler writer. Perhaps it is a Calyx-related bug, but sometimes working from the ground up can help reduce the error space.

[5hayanB]

I need clarification: Does "Human readable RTL" equals "Efficient RTL"?

[rachitnigam]

Those two are unrelated from my perspective: well-written RTL can be quite inefficient while unreadable RTL can be quiet efficient. Our primary goal is to generate high-performance RTL and while we try to make the generated RTL somewhat readable to keep it debuggable, that is not a primary goal