/s/sfbuild/f4pga/ CI testing

[umarcor]

/cc @kboronski-ant @acomodi @mkurc-ant @kgugala

As discussed in a meeting, this is a subset of the work-in-progress to update/continue sfbuild.

• The subdir is renamed to f4pga.
• The docs are moved from subdir f4pga/docs to docs/f4pga (i.e. they are integrated in the Sphinx site, as a section).
• The documentation is reorganised (headings, splitting, etc.) in order to better use the sidebars of the Sphinx theme. However, the meaning/content is unmodified.

Before going into further modifications to the code, the purpose of this PR is to have a minimal CI test to ensure things are not broken during refactorisation.

Testing the scripts alone does work:

PYTHONPATH=$(pwd)/f4pga python3 f4pga/sfbuild.py
PYTHONPATH=$(pwd)/f4pga python3 f4pga/sfbuild.py -h

However attempting to run a build fails:

make env
PYTHONPATH=$(pwd)/f4pga python3 f4pga/sfbuild.py build --platform xc7a50t -t bitstream

As discussed, the make env command of this repository is not the correct way to "bootstrap" an environment for testing "how to generate a bitstream from HDL sources using the F4PGA environment installed through Conda". Furthermore, I'm not even activating the environment explicitly, so CI fails.

So, shall I follow the f4pga-examples.readthedocs.io: Getting F4PGA instructions and then use sfbuild?

[umarcor]

I tried installing the environment from f4pga-examples, and activating it. However, sf_module_runner is failing:

https://github.com/antmicro/f4pga-arch-defs/runs/5383595255?check_suite_focus=true#step:4:1999

Traceback (most recent call last):
  File "f4pga/sfbuild.py", line 633, in <module>
    cmd_build(args)
  File "f4pga/sfbuild.py", line 546, in cmd_build
    flow_def = FlowDefinition(flow_definition_dict, r_env)
  File "/home/runner/work/f4pga-arch-defs/f4pga-arch-defs/f4pga/sf_flow_config.py", line 217, in __init__
    self.stages[stage_name] = Stage(stage_name, modstr, opts)
  File "/home/runner/work/f4pga-arch-defs/f4pga-arch-defs/f4pga/sf_stage.py", line 49, in __init__
    ModuleClass = get_module(module_path)
  File "/home/runner/work/f4pga-arch-defs/f4pga-arch-defs/f4pga/sf_module_runner/__init__.py", line 40, in get_module
    mod = import_module_from_path(path)
  File "/home/runner/work/f4pga-arch-defs/f4pga-arch-defs/f4pga/sf_module_runner/__init__.py", line 25, in import_module_from_path
    spec = importlib.util.spec_from_file_location(absolute_path, absolute_path)
AttributeError: module 'importlib' has no attribute 'util'

@kboronski-ant, any guess?

I tried isolating the snippet and testing it with multiple Python versions: https://github.com/umarcor/f4pga-arch-defs/actions/runs/1919246644

[umarcor]

Got further by importing importlib.util explicitly in sf_module_runner.

The current error is the following:

Couldn't open .symbicache cache file. This will cause flow to re-execute from the beggining.
Error: : yosys non-zero return code.
stderr:
ERROR: TCL interpreter returned an error: couldn't read file "/home/runner/work/f4pga-arch-defs/share/symbiflow/scripts/xc7/synth.tcl": no such file or directory

[umarcor]

Another step forward: fixed the path to .../share/symbiflow by reading INSTALL_DIR from environ.

Now, it's failing to process one of the fields in the platform JSON file:

https://github.com/antmicro/f4pga-arch-defs/runs/5385182587?check_suite_focus=true#step:4:18

Couldn't open .symbicache cache file. This will cause flow to re-execute from the beggining.
Error: : yosys non-zero return code.
stderr:
ERROR: Can't open input file `${:xdc}' for reading: No such file or directory

[mkurc-ant]

@umarcor This Couldn't open .symbicache cache file. This will cause flow to re-execute from the beggining. does not seem to be a problem. .symbicache is a cache file for tracking which targets have been built and when you start sfbuild from the first time it's normal that the file is missing.

I can see that you are specifying xdc as a one element list:

"xdc": [
    "arty.xdc"
],

Maybe try as a string like:

"xdc": "arty.xdc"

I guess @kboronski-ant should help you with that.

[umarcor]

@mkurc-ant thanks! I could work around it by hardcoding the path to the constraints file in the platform JSON file: f24273c
Not ideal, but it allows to generate the bitstream!

@kboronski-ant shall I use the "relative path" in the flow JSON and revert the change to the platform JSON?

[umarcor]

Superseeded by chipsalliance/f4pga#530.