Getting set up with Calyx

[bcarlet]

Hello!

I've started experimenting with Calyx recently and I've accumulated some questions while setting things up. Also, I've encountered a few (minor) issues with the instructions which I've noted below. Hopefully the latter is useful.

Questions

• I am still somewhat confused by the role of invoke. I don't see it mentioned in the original Calyx paper; all the examples there appear to use the go-done interface directly. I understand that it is used for passing cells by reference. In what other cases is it necessary? Or is it just syntactic sugar? Interestingly the group2invoke pass seems to transform in the opposite direction, but Implement group2invoke pass #679 indicates that this is done only to make analysis easier. As an aside, the format of ref cells, inputs, and outputs isn't specified in the Language Reference (there are examples elsewhere in the documentation, but it would be helpful to have it fully specified here).
• I get an error from iverilog when using port names in Calyx that are reserved words in SystemVerilog. Are these intended to be reserved words in Calyx as well? I don't recall seeing any mention of such in the documentation.
• Is there a way to use non-decimal numbers as parameters to standard primitives? Verilog-style literals don't appear to be accepted. (This came up when trying to use std_const.)

Thanks!

Issues

Also, in case these notes are helpful...

• The documentation for guarded assignments is explicit that the guard expression must produce a 1-bit value; however, the documentation for control operators such as while refers only to the port being non-zero. This reads to me as though multi-bit ports are allowed, but experimentation (and the original Calyx paper) indicates that this is not the case. When running with Icarus Verilog it appears that the port is silently sliced; when running with the interpreter, the interpreter panics. I think it would be good to clarify in the docs (or, better perhaps, to add compiler warnings where appropriate).
• In the setup instructions here and here, it appears that fud config global.futil_directory <path> needs to be run with --create.
• The suggested method of installation for VSCode syntax highlighting (documented here and here) didn't work for me (it seems that $HOME/.vscode/extensions/extensions.json does not get updated even after a restart). I was able to install via the Command Palette using Developer: Install Extension from Location... instead.

[EclecticGriffin]

I'll take a stab at answering a few of these, though @rachitnigam may need to chime in as well.

1

I am still somewhat confused by the role of invoke. I don't see it mentioned in the original Calyx paper ...

So Invoke, to the best of my knowledge, was added after the original paper. The basic idea is that Invoke fulfills a sort of function call like roll in the language and is the sort of defacto way for working with Calyx defined sub-components since it frees the user from needing to manually interact with the go-done interface. It is also possible to use invoke with primitives which can make for easier analyses on certain groups with clearly defined rolls (e.g. write this value to this register).

Currently (please correct me if I'm wrong @rachitnigam) I believe it is the only way to use sub-components with ref cells as they need to be materialized by some cell in the parent's execution context.

Thanks for the note about the language reference! If you wouldn't mind opening an issue that would be helpful, otherwise I can try to open one a bit later.

2

I get an error from iverilog when using port names in Calyx that are reserved words in SystemVerilog. Are these intended to be reserved words in Calyx as well? I don't recall seeing any mention of such in the documentation.

Hmm, I am not sure what the prevailing attitude is on this, but there are two possible apporaches to take. Either these can be added to the list of reserved keywords or the iverilog backend could be adjusted to check for naming conflicts only when being output to verilog. @rachitnigam thoughts?

Regardless, please open an issue with the keywords you ran into so we can either resolve this or make a proper error!

3

Is there a way to use non-decimal numbers as parameters to standard primitives? Verilog-style literals don't appear to be accepted. (This came up when trying to use std_const.)

This is currently not supported. Though there is nothing preventing it from being added in the long term! If this would be useful to you, please open an issue!

[bcarlet]

Thanks very much for the clarifications! I'll open issues for the things you mentioned.

[sampsyo]

Thanks, @EclecticGriffin!! On reserved names in particular, we’ve basically just been trying to make those outright errors (not very friendly but it’s the path of least resistance). The list is here—any chance the keywords you were seeing are missing from it, @bcarlet?
https://github.com/cucapra/calyx/blob/ef1b584f050c02c03064ec7bff7d9b8786c98e68/calyx/src/ir/reserved_names.rs

[bcarlet]

It looks like that list contains the reserved words from Verilog, but not the ones from SystemVerilog. The words that gave me errors were from the latter (namely, bit and const, IIRC). Actually, I don't get an error from futil (or interp) even when using words from the RESERVED_NAMES list. For example, I can name a component reg, and futil will succeed, but iverilog fails with a syntax error.

Edit: On closer inspection, it seems that the reserved words check is only applied to cells.

[rachitnigam]

Ah, that’s troublesome! Can you open an issue about this? The check should be applied to all names in the program. Alternatively, it should be added to all NameGenerator objects so they automatically rename any clashing keywords.