APIs for SWIG + Tcl & Python

[tangxifan]

Is your feature request related to a problem? Please describe. As stated in #516 , Tcl and python interface can potentially unlock enormous possibilities for users when exploiting OpenFPGA's commands. To ease such integration, SWIG is a preferred way to bind C++ APIs to the upper-level interface.

However, SWIG requires OpenFPGA APIs to be encapsulated in objects (we do not want to expose any raw data to users unless necessary). Also we do not want to create complicated Tcl/python wrappers. This will require more maintanance for developers, as the wrapper codes may be a duplication to existing APIs to openfpga shell.

Describe the solution you'd like

We would like to build OpenFPGA APIs which can be used by SWIG to bind for Tcl/Python interfaces. Here are some code modification I suggest:

• Create a new class OpenFpgaShell on top-level of the general-purpose shell.h, this shell will contain the global variables, openfpga_context and vpr_context.
• The OpenFpgaShell class will replace the codes in current main.cpp.

https://github.com/lnis-uofu/OpenFPGA/blob/c796deebe01f2575cacd75c8a238683c86d38a90/openfpga/src/main.cpp#L28-L135

The main function will be replaced by

OpenFpgaShell openfpga_shell;
return openfpga_shell.start(argc, argv);

• The OpenFpgaShell has a new API, through which we can call any command.

openfpga_shell.run_command(std::string)

The input is a regular call of a command like

read_openfpga_arch --file ~/OpenFPGA/arch/example.xml --verbose

• The OpenFpgaShell will be object to be linked to Tcl/Python, through a SWIG include file (*.i).
• In the tcl file, we can simply call the openfpga command like #555

catch { load $home/libopenfpga[info sharedlibextension] openfpga}
openfpga_shell OPENFPGA_TCL
OPENFPGA_TCL.run("read_openfpga_arch --file ~/OpenFPGA/arch/example.xml --verbose")

• If we want to improve the user friendliness of the Tcl API, we may create wrappers in another Tcl script, where we encapsulate the low-level APIs

proc read_openfpga_arch{options} {
  global OPENFPGA_TCL
  OPENFPGA_TCL.run($options)
}

Some references:

• https://github.com/Mizux/cmake-swig
• https://blog.mbedded.ninja/programming/languages/python/python-swig-bindings-from-cplusplus/#the-interface-file

• 555

• https://www.swig.org/
• https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/OpenRoad.tcl
• https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/OpenRoad.i

Describe alternatives you've considered

• We may consider integrate Tcl directly into the shell.h, which is a tight integration.

• We may consider to use pybind11 to create python binding for C++ APIs.

[ganeshgore]

@tangxifan Thank you again for the great detail.

Quick question, why can't we call read_openfpga_arch as a native command from the TCL (as detailed in #516) instead of going through OPENFPGA_TCL.run(***) wrapper I thought we would replace the current OpenFPGAshell implementation with a clean TCL and PYTHON interface with SWIG, not just a wrapper. Eventually, we want to make more granular calls quickly and cleanly. Do you think this wrapper idea scale well for that? I see you mentioned, "We may consider integrate Tcl directly into the ....." is it something we are still evaluating?

[tangxifan]

@ganeshgore These are good thoughts. I share my thoughts after my investigation on current codebase.

Concerns about Raw API

I was planning to open some native APIs from C++ to Tcl/Python. But it will expose a lot of data structures to users/developers, such as the complete architecture APIs, as well as many internal options. My concerns is that at the current stage of OpenFPGA APIs (we lack a lot of documentation on APIs), the exposure will bring a lot of confusion, which cause users/developers to make many mistakes and see many clueless errors.

Current Plan and Future

My current plan is to reveal the APIs which users/developers are already familiar with. They can easily pick-up and try to do some exploration. As you said, they may not be able to manipulate the data structure in memory through APIs. But they can

• manipulate files by developing scripts to reorganize data
• repeatedly run commands to explore best options and decide what to do.

The wrapper is required for end-users, who just need Verilog-to-Bitstream flows. They are not power users or developers who are very familiar with codebase. Offering a simple and straightforward interface caters their needs, IMHO.

In the next stage, we can then expose more APIs which allows users/developers to manipulate the data structures. I suggest we do this in a gradual way (one API per PR, after sufficient discussion and consideration).

About OpenFPGA shell

For the sake of a smooth transition to more powerful interface, before we have very stable Tcl/Python interface through SWIG, I will not abandon current shell interface. For Tcl/Python interface, it is still unknown about the easiness in debugging through gdb or other tools. Current OpenFPGA shell is still a good way for developers when debugging internal errors.

We will discuss again about OpenFPGA shell after the community start embracing Tcl/Python interface.

Direct integration of Tcl into OpenFPGA shell

Currently, my preference is not to follow this path. It may be easy to do for now. But in long term, it has some problems

• we may have to maintain both SWIG and the Tcl in OpenFPGA shell, if we do not Tcl through SWIG.
• we have to maintain the Tcl codes in OpenFPGA shell, upon upgrades in Tcl APIs, which is another burden.

I have similar concerns for pybind11.

So my opinion is that SWIG is currently the best option, once we have it, it will be easier to switch between high-level interfaces. More options is what I would like to offer to our community.

[ganeshgore]

@tangxifan Thanks for all the detail again. Let me provide some clarity on my previous reply, I was not suggesting to abandon openfpgashell now. My proposal was start developing TCL/Python interface simultaneously (while keeping openfpgashell stable)which not just a wrapper on top of openfpgashell.

Let me provide my view of use cases you provides above

• Manipulating file .... : If I understand correct you mean using variables in the OpenFPGAshell script, I believe we do that already in our current workflow If you mean changing command based on output of previous command, there are very few usecase for that, and even if its required there are several ways to do it without any further development, (1) Call openfpgashell using subprocess and provide command in temp file (2) Create Unix pipe and send inputs to openfpga shell. All this approaches do not much overhead as well

• Repeatedly run commands... There is hardly anything we can run repeatedly, while keeping session active, for example: If you want to run build_fabric command multiple times with different fabric keys, to achieve better distribution of config bit. I dont think we can do that. Certainly we can run VPR multiple times with different channel width and different option, but its as good as launching new session

My concern here is, even with current Interactive shell, there is no datastructure or a design to interact with. It mainly used as an input console. Integration of scripting language (TCL/python) will not provide much advantage here. In near future we need to understand how to store context and have more granular APIs for netlist and bitstream manipulation.

I agree with your caution approach (one API per PR) for exposing internal APIs to the user, In my opinion it should be done with direct interface to the codebase and not via creating wrapper to existing openfpgashell.

Let me know your thought?

[tangxifan]

@ganeshgore Thank you for the inputs.

I agree that the first integration may not provide the technical features that you want. I agree that your technical features should be included in future version of OpenFPGA. However, doing an aggressive upgrade (a big jump on existing codebase) is always a big risk. We have experienced so when upgrading RRGraph in VTR. In addition, exposing raw data structure to developers may be a strong risk. You may face a lot of unknow errors reported every day. Your regression tests may not be able to catch such a large amount of combinations. Therefore, I would suggest to go in steady way. Develop APIs to get data from internal data structures, which is easier for us to maintain regression tests and control the quality of OpenFPGA.

[ganeshgore]

Agreed, Not asking for aggressive upgrade. All I am saying here is if we are integrating TCL/Python we should do it a correct way, which is scalable and usable and most importantly scriptable. Just having some for of TCL or python interface will not provide any advantage.

You can take call when to expose which data structure, I dont think just direct integration exposes everything. We still need to have specific interface files.

[tangxifan]

@ganeshgore No worries. I think what you are asking for is reasonable and OpenFPGA should provide them eventually (after several major iterations on Tcl/Python binding). However, in the first milestone, we may not be able to reach that level immediately. It may take some time but I believe we will be there.

For interface files, we still have to learn some detailed syntax, so that we know how to control API exposures on internal data structures. I would like to accumulate some experience before starting massive integration.