Command-line interface definition

[rodrigomelo9]

In this issue, I will summarize the currently supported sub-commands and their arguments. @mithro @kgugala @acomodi could you provide me feedback?

• What about sub-commands and arguments names?
• Need I split commands (imp) to have a more granular control?
• Missing arguments that I haven't into account?

Please, add other users to the talk if needed, and feel free to ask any doubt.

For more details, the following is defined here.

Sub-commands

• syn: Performs synthesis
• pnr: Performs Place and Route
• bit: Performs bitstream generation
• all: Performs from synthesis to bitstream generation (runs together syn, imp and bit in one step)
• pgm: Performs programming (when available).

Command-line arguments

Shared by all the sub-commands:

• --project: basename for generated files.
• -p, --part: name of the target FPGA part (something like 'hx8k-ct256)
• -o, --outdir: location for generated files
• --oci-engine: OCI engine internally employed (docker, podman)
• --oci-volumes: volumes for the OCI engine. Can be specified multiple times.
• --oci-work: working directory for the OCI engine

For syn (and all)

• -t, --top: specify a top-level name
• --param: specify top-level Generics/Parameters (as NAME VALUE). Can be specified multiple times.
• --arch: specify a VHDL top-level Architecture
• --define: specify [System] Verilog Defines (as DEFINE VALUE). Can be specified multiple times.
• --include : specify [System] Verilog Include Paths. Can be specified multiple times.
• --scf: a Synthesis Constraint Files (not yet implemented). Can be specified multiple times.
• hdl: (positional, mandatory) a list of HDL files (which can be specified as FILE[,LIBRARY] in case of VHDL)

For imp (and all)

• --pcf: a Physical Constraint Files (IO place). Can be specified multiple times.

[mithro]

Some random comments;

• Any reason not to use abbreviation pnr for the imp stage?
• It would be great to separate out the "tooling provider" (IE container, system, conda, etc). Each tooling provider can then have various command line options.
• I think specifically separating out the files being provided from the arguments controlling things would also be useful.

[mithro]

FWIW - I think basing this CLI on edalize would be a good idea. An alternative is to have a "basic" mode and an "advanced mode" where the advanced mode uses edalize?

[mithro]

Useful resources;

• https://docs.google.com/document/d/1Q8vaqD67aqPO7JbSDZtVvbg4BD7XBVuA_JJTwcYHprk/edit#
• https://docs.google.com/drawings/d/15sVUnCHS1ex3lmuD3J7nDR-F1Xst6Panotc-2WlNRtQ/edit

[rodrigomelo9]

Any reason not to use abbreviation pnr for the imp stage?

Historical reasons. When I started what today is known as PyFPGA, I borrowed the term from Vivado, as a broader concept (opts + pnr). But ok, I will change it to pnr.

It would be great to separate out the "tooling provider" (IE container, system, conda, etc). Each tooling provider can then have various command line options.

I am not a Conda user, but as far I understand, you can activate an environment and still be working on your "system" (the same file system). With an OCI engine, you are running inside of a container, where you need to map volumes, share devices (USB), etc. I am no against using Conda, but I haven't the expertise at this moment.

I think specifically separating out the files being provided from the arguments controlling things would also be useful.

Sorry, but I am not sure what it means. Maybe, do not provide files in the command-line and use something like a fileset (.f) file?

FWIW - I think basing this CLI on edalize would be a good idea. An alternative is to have a "basic" mode and an "advanced mode" where the advanced mode uses edalize?

I started what I am doing here as part of PyFPGA. Then, I moved it to OpenFlow, to simplify the code at PyFPGA. Finally, I realized that my idea behind OpenFlow was so similar to SymbiFlow, and we agree that is better to join efforts instead of several similar projects.

I see edalize, PyFPGA and others, as wrappers that provide a unified interface to employ multiple programs. My idea behind symbiflow_cli is to replace the toolchain_wrappers of symbiflow-arch-defs, and then it can be used by edalize or others. Do you agree? Maybe there is something of a chicken-and-egg situation here :-D

Thanks for the feedback and the resources.

[rodrigomelo9]

I think specifically separating out the files being provided from the arguments controlling things would also be useful.

Or maybe are you talking about do not specify --vhdl, --vlog or --slog? Are you suggesting simply providing them as files after the arguments?

[mithro]

I think specifically separating out the files being provided from the arguments controlling things would also be useful.

Or maybe are you talking about do not specify --vhdl, --vlog or --slog? Are you suggesting simply providing them as files after the arguments?

Something along this line I think...

[rodrigomelo9]

Ok... I agree, would be beautiful... but there are some technical difficulties:

• I am using argparse and some arguments are space-separated lists (files, and also defines, generics/parameters, Verilog includes, etc). It can be solved using multiple specifications of the same argument. So, instead of program --arg1 value1 value2 --arg2 value 3 it will be program --arg1 value1 --arg1 value2 --arg2 value 3
• Here, we have not only Verilog files. There are at least VHDL and for the future, I want to add System Verilog. Do we need to agree on how to identify the file type: file extension? (probably problematic), heuristics? (is relatively easy to distinguish VHDL against Verilog, not sure System Verilog against Verilog, and we will have time penalities).

Again, I agree that is a good idea. The problem is that I am not sure about the solution. Let me know your thought about that (and of course, if you know a project where it is already solved to use as an example, it will be welcome).

[rodrigomelo9]

Hi @mithro I changed imp by pnr. Moreover, HDL files are now specified together, without a particular argument. Examples here

Hi @mkurc-ant. I was doing some simplification related to command-line arguments. Maybe you can take a look.