Documentation: How to keep install instructions up to date?

[nelsobe]

The last step of the installation is to install a set of tar files like this:

mkdir -p $INSTALL_DIR/xc7/install
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/20220404-212755/symbiflow-arch-defs-install-afbfe04.tar.xz | tar -xJC $INSTALL_DIR/xc7/install
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/20220404-212755/symbiflow-arch-defs-xc7a50t_test-afbfe04.tar.xz | tar -xJC $INSTALL_DIR/xc7/install
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/20220404-212755/symbiflow-arch-defs-xc7a100t_test-afbfe04.tar.xz | tar -xJC $INSTALL_DIR/xc7/install
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/20220404-212755/symbiflow-arch-defs-xc7a200t_test-afbfe04.tar.xz | tar -xJC $INSTALL_DIR/xc7/install
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/20220404-212755/symbiflow-arch-defs-xc7z010_test-afbfe04.tar.xz | tar -xJC $INSTALL_DIR/xc7/install

However, on more than one occasion this semester the documentation was not updated with the latest packages, causing confusion amongst our users when supposed fixes were not reflected in the installed version.

A mechanism to keep the docs up to date would be helpful.

Or, can instructions be put in place to tell users how they can determine the latest packages to use (is there a file somewhere they could access to determine this information)? If so, then there would not be a need to regularly update the docs.

[mkurc-ant]

Hi @nelsobe.

The packages mentioned in the documentation are not necessarily the most recent ones but are the ones known to work as their use with f4pga-examples is tested in CI. Links to them are not automatically updated (yet) so if newer ones are needed one has to issue a PR that updates those links.

There is no possibility of the documentation and the packages versions getting out of sync because the CI uses the documentation itself as a source of links for downloading and commands to run. This is done via tuttest (https://github.com/antmicro/tuttest/). So in the end there is the one and only place where package versions are stored.

[nelsobe]

@mkurc-ant Any word on whether the instructions are now up to date so the latest fixes are inckluded?

[mkurc-ant]

Hi @nelsobe. Apparently there was an issue in the docs deployment system and the docs you could access on RTD were outdated. Nevertheless all the relevant fixes are in place. Pleas report if you still observing any failures.

[JamesTimothyMeech]

My installation does not work (f4pga command not found) after following these instructions: https://f4pga-examples.readthedocs.io/en/latest/getting.html#getting

I have a feeling that last the command to get and install the packages is not working. If I try to run the first command:
https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-install-xc7-${F4PGA_HASH}.tar.xz from the for loop manually I get random characters printed to the terminal:

�v+6�sI�t�Ʒ}J�69E�����u@ӟo�~Qe��)��H��a<���F�o�C

[kgugala]

the command is:

wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-${PKG}-${F4PGA_HASH}.tar.xz | tar -xJC $F4PGA_INSTALL_DIR/${FPGA_FAM}

So at the end it pipes the downloaded tar.xz file into tar. If you remove the tar piping you'll see garbage output in your terminal. I'd assume you didn't copy/paste the whole command

[JamesTimothyMeech]

When I run this command I get a lot of errors
(base) james@james-System-Product-Name:~/Desktop/Casino/f4pga-examples$ for PKG in $F4PGA_PACKAGES; do wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-${PKG}-${F4PGA_HASH}.tar.xz | tar -xJC $F4PGA_INSTALL_DIR/${FPGA_FAM}; done tar: share/f4pga/techmaps/xc7_vpr/techmap/iobs.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/clean_carry_map.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/cells_map.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/cells_sim.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/unmap.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/retarget.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap/carry_map.v: Cannot open: File exists tar: share/f4pga/techmaps/xc7_vpr/techmap: Cannot utime: Operation not permitted tar: share/f4pga/techmaps/xc7_vpr: Cannot utime: Operation not permitted tar: share/f4pga/techmaps: Cannot utime: Operation not permitted tar: xc7_env/xc7_requirements.txt: Cannot open: File exists tar: xc7_env/requirements.txt: Cannot open: File exists tar: xc7_env/xc7_environment.yml: Cannot open: File exists tar: xc7_env: Cannot utime: Operation not permitted tar: Exiting with failure status due to previous errors

When I run this command:
for PKG in $F4PGA_PACKAGES; do wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-${PKG}-${F4PGA_HASH}.tar.xz | sudo tar -xJC $F4PGA_INSTALL_DIR/${FPGA_FAM}; done
it completes without errors.

I suspect that my installation has not worked properly because when I attempt to follow these instructions: https://f4pga-examples.readthedocs.io/en/latest/xc7/counter_test.html to build the examples I get this error:
(base) james@james-System-Product-Name:~/Desktop/Casino/f4pga-examples$ cd xc7/ (base) james@james-System-Product-Name:~/Desktop/Casino/f4pga-examples/xc7$ TARGET="arty_100" make -C counter_test make: Entering directory '/home/james/Desktop/Casino/f4pga-examples/xc7/counter_test' cd /home/james/Desktop/Casino/f4pga-examples/xc7/counter_test/build/arty_100 && symbiflow_synth -t top -v /home/james/Desktop/Casino/f4pga-examples/xc7/counter_test/counter.v -d artix7 -p xc7a100tcsg324-1 -x /home/james/Desktop/Casino/f4pga-examples/xc7/counter_test/arty.xdc /bin/sh: 1: symbiflow_synth: not found make: *** [/home/james/Desktop/Casino/f4pga-examples/xc7/counter_test/../../common/common.mk:67: /home/james/Desktop/Casino/f4pga-examples/xc7/counter_test/build/arty_100/top.eblif] Error 127 make: Leaving directory '/home/james/Desktop/Casino/f4pga-examples/xc7/counter_test'

[JamesTimothyMeech]

Ah it is now working. I had missed the conda activate $FPGA_FAM line in the instructions

[JamesTimothyMeech]

I am confused as to why my linux-on-litex cannot find F4PGA. I have the counter example running which indicates that F4PGA installed properly.

Traceback (most recent call last):
  File "/home/james/Desktop/Casino/litex/litex/build/xilinx/f4pga.py", line 19, in <module>
    from f4pga.flows.flow import Flow
ModuleNotFoundError: No module named 'f4pga'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "./make.py", line 945, in <module>
    main()
  File "./make.py", line 867, in main
    soc = SoCLinux(board.soc_cls, **soc_kwargs)
  File "/home/james/Desktop/Casino/linux-on-litex-vexriscv/soc_linux.py", line 160, in SoCLinux
    return _SoCLinux(**kwargs)
  File "/home/james/Desktop/Casino/linux-on-litex-vexriscv/soc_linux.py", line 34, in __init__
    soc_cls.__init__(self,
  File "/home/james/Desktop/Casino/litex-boards/litex_boards/targets/digilent_arty.py", line 86, in __init__
    platform = digilent_arty.Platform(variant=variant, toolchain=toolchain)
  File "/home/james/Desktop/Casino/litex-boards/litex_boards/platforms/digilent_arty.py", line 346, in __init__
    Xilinx7SeriesPlatform.__init__(self, device, _io, _connectors, toolchain=toolchain)
  File "/home/james/Desktop/Casino/litex/litex/build/xilinx/platform.py", line 40, in __init__
    from litex.build.xilinx import f4pga
  File "/home/james/Desktop/Casino/litex/litex/build/xilinx/f4pga.py", line 25, in <module>
    raise ModuleNotFoundError("Try getting/updating F4PGA tool (https://github.com/chipsalliance/f4pga/)") from e
ModuleNotFoundError: Try getting/updating F4PGA tool (https://github.com/chipsalliance/f4pga/)

[JamesTimothyMeech]

I missed that I had to do all of this again

export F4PGA_INSTALL_DIR=~/opt/f4pga
export FPGA_FAM="xc7"
source "$F4PGA_INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh"
conda activate $FPGA_FAM

Then setup litex again

$ wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
$ chmod +x litex_setup.py
$ ./litex_setup.py --init --install --user (--user to install to user directory)