Things to test or do before next apio release (2024)

[zapta]

@Obijuan, @cavearr, this issue lists functionality of apio that may have changed but was not tested, for example because lack of boards or platforms. Please make sure to revisit and test it before the next release.

I will add comments to this thread as we go.

[zapta]

'apio upload' command with a tinyprog board.

To Test

Run an apio upload command with a tinyprog board. Verify that the progress percentage report stays on a single line instead of scrolling down.

Notes

The scons filter was changed to preserve formatting and empty lines and this may cause the percentage report to scroll down. If this is the case, the likely fix would be to add erasure of a second line in the tinyprog filter.

https://github.com/FPGAwars/apio/blob/5c4762060f20de8e2fb14a0117205449a3a23e52/apio/managers/scons_filter.py#L288

print(CURSOR_UP + ERASE_LINE + CURSOR_UP + ERASE_LINE, end="", flush=True)

[zapta]

'apio upload' command with a fumu board.

To Test

Run an apio upload command with a fumo board. Verify that the progress percentage report stays on a single line instead of scrolling down.

Notes

The scons filter was changed to preserve formatting and empty lines and this may cause the percentage report to scroll down. If this is the case, the likely fix would be to add erasure of a second line in the fumu filter.

https://github.com/FPGAwars/apio/blob/5c4762060f20de8e2fb14a0117205449a3a23e52/apio/managers/scons_filter.py#L260

print(CURSOR_UP + ERASE_LINE + CURSOR_UP + ERASE_LINE, end="", flush=True)

[cavearr]

Ok @zapta ! good work! i'm try to prepare a rig with some fpgaboards to automtize the checks, i think could be very interesting

[zapta]

Test all commands with a Gowin project

Currently we have test projects, with testbenches, for ICE40 and ECP5 (see below) but not for Gowin such that some of the development we are doing is with no testing, even not manual.

https://github.com/FPGAwars/apio/tree/develop/test-examples/TB/Alhambra-II/icestudio/ledon

https://github.com/FPGAwars/apio/tree/develop/test-examples/TB/ColorLight-5A-75B-V8/icestudio/button

[cavearr]

I'm working on gowin fpgas support i'm push very soon.

[zapta]

Address the FTDI driver change on windows

Windows that upgraded to the new release may need to change the ftdi driver they installed using zadig. We should test this upgrade path, streamline it with code if possible (e.g. provide a warning if we see an old driver) and include that in the release notes.

[cavearr]

Hi @zapta! with the developer version (apio upstream) zadig does't launch , has you changed the apio command to enable the driver?

[zapta]

@cavearr, it does launch on my windows 10. For testing, try also 'apio raw zadig --env'.

Are you sure that windows doesn't ask you for permission to elevate zadig to high privileges? Look at the task bar at the bottom of the screen, it may be blinking.

[cavearr]

i'm updating icestudio, apio works well, thanks!

[cavearr]

Hi @zapta the command that fails from Icestudio is "apio install drivers" , now, what is the equivalent?

Thanks!

[zapta]

@cavearr, apio install drivers installs the drivers package which is available only on windows.

The new equivalent is apio packages --install drivers. Another option is to run apio packages --install to install all the packages that are applicable to this platform which is more cross platform from user's perspective.

https://github.com/FPGAwars/apio/blob/f0aca517130994989a97d9ac063ac9bd32c9adae/apio/resources/packages.json#L82

[zapta]

Test migration to the new version

Some of the changes in this version are

• apio.ini is required.
• Packages added/removed/changed.
• Windows requires a different driver (WinUsb vs libusbk).
• Artifact files are now in _build instead of the src directory.
• Commands added/removed/changed.
• Other changes we can't recall.

This entry is for the testing of the transition to the new apio version. The starting point can be, the user has a 'non-clean' working project (without apio.ini? using a custom board? using icestudio?), and release notes, and needs to migrate to the new version. This should be tested and tweaked to achieve a high success rate.

If needed, we can add additional code to simplify the migration. So far we have:

• apio clean also cleans old artifact files in the src directory.
• apio packages --fix followed by apio packages --install --force should take care of the packages changes.

[cavearr]

Hi @zapta ! i'm working in icestudio migration in a couple of days (along the weekend as most) i'll can test it.

I think all the tests should be formed in apio alone, and icestudio, independently.

The first test i'll do with alhambra-ii board but once all works i'll test with some ecp5 boards , gowin boards (por apicula support), and custom boards to test raw commands.

[zapta]

Hi @cavearr, you are right, apio should be tested independently.

Your plan sounds great. On what platforms can you test?

Also, I suggest to test only projects with apio.ini (that is, no --board, --fpga, --size, etc flags) since this will be the coming release.

If you encounter any problem with apio or have some wish, please let me know and I will fix it.

[cavearr]

Hi @zapta, the plan is once the development is finished, I will test it on Linux, Linux Arm64 and Osx Arm. @Democrito will test it on Windows with the Alhambra-ii

I will try the Alhambra-ii, colorlight-i5, radiona ulx3s, tinyfpga, icebreaker, fomu and for apicula on the tang nano 1k and 9k

Look forward to some fun days XD

[zapta]

Hi @cavearr, that's exciting!

You don't need to test the deprecated commands since they will go away anyway.

Deprecated commands:
  modify     [Depreciated] Modify the apio.ini project file.
  time       [Depreciated] Report design timing.
  verify     [Depreciated] Verify the verilog code.
  install    [Depreciated] Install apio packages.
  uninstall  [Depreciated] Uninstall apio packages.

[zapta]

@cavearr, also no need to test command lines flags that are marked as DEPRECATED since they will go away soon. You can find them in the command --help text. For example, the build command has 6 deprecated options:

$ apio build --help
Usage: apio build [OPTIONS]

...

Options:
  -p, --project-dir path  Set the root directory for the project.
  -v, --verbose           Show detailed output.
  --verbose-yosys         Show detailed yosys output.
  --verbose-pnr           Show detailed pnr output.
  -t, --top-module name   [DEPRECATED] Set the top level module name.
  -b, --board str         [DEPRECATED] Set the board.
  --fpga str              [DEPRECATED] Set the FPGA.
  --size str              [DEPRECATED] Set the FPGA size (1k/8k).
  --type str              [DEPRECATED] Set the FPGA type (hx/lp).
  --pack str              [DEPRECATED] Set the FPGA package.
  -h, --help              Show this message and exit.

[zapta]

Verify packages.json and distribution.json

During development I sometimes point a package to a dev version or to my own temp repo.

This item is for verifying the package sources and versions in packages.json() and distribution.json().

[cavearr]

Hi @zapta ! i'm going step by step with the tests, i'm posting you here doubts ok? if you prefer that i open new issues tell me how do you want to manage it.

• I have doubts if you remove this parameteR: apio examples -d Alhambra-II/Blinky

in the new way i'm trying:

apio packages --install examples

This works as spected and download the full example dir in .apio dir but i ask you if there is a way to install examples in particular like the old way.

In other hand i'm asking you for a command to launch zadig in windows. In some tests , i am founding that in some windows is necesary launch zadig and install winusb from there, and now apio not launch zadig or i don't know how (i don't find a pattern, could be depending the driver for the usb port, for this is important to have an option to launch zadig).

Thanks!

[zapta]

Hi @cavearr, posting here is ok.

1. apio examples -d Alhambra-II/Blinky copies an example from the installed examples package to the user's directory and I think it works the same way as it used to be. That is, it requires the entire 'examples' package to be installed, as it used to be.

2. apio packages --install examples installs the examples packages and it replaces the old apio install examples' The functionality is the same as the old way, just the command changed.

3. Regarding zadig, when you run apio drivers --ftdi-install on windows, does it start zadig? If not, do you see some blinking task at the bottom of the screen? Also, try apio raw zadig. Does it start zadig (again, look for blinking at the bottom of the screen).

[zapta]

When I start zadig from apio I get this blinking at the bottom of the screen (play the video below). When I click on it windows asks me for permission to run zadig. This is because zadig needs administrator privileges. This is on windows 10.

https://github.com/user-attachments/assets/c2ade042-d402-4893-a5e3-0e7c18b9cb7c

[cavearr]

Hi @zapta ! thanks for your sooner reply! is strange ecause i know the "blinking" popup for permissions, but this doesn't work, could be a problem in my setup, i'll review it, don't worry.

Thanks for your detailed reponse!

[zapta]

Try to see if you have the zadig.exe in a package installed under ~/.apio/packges. If you find it, try to run it from a python script, similar to the ay apio does in the link below.

import os
os.system("<path to zadig.exe>")

here https://github.com/FPGAwars/apio/blob/1b28d89205ad8627b2107d3a1df198d169bd8e63/apio/managers/drivers.py#L476

On Sat, Nov 30, 2024 at 12:08 PM Carlos Venegas Arrabé < @.***> wrote:

Hi @zapta https://github.com/zapta ! thanks for your sooner reply! is strange ecause i know the "blinking" popup for permissions, but this doesn't work, could be a problem in my setup, i'll review it, don't worry.

Thanks for your detailed reponse!

— Reply to this email directly, view it on GitHub https://github.com/FPGAwars/apio/issues/444#issuecomment-2509186511, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAQVMQLGEFXXNW6XUP2KAPL2DILKVAVCNFSM6AAAAABQHQ2PJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBZGE4DMNJRGE . You are receiving this because you were mentioned.Message ID: @.***>

[cavearr]

Don't worry problem in my system, i'm on it

[zapta]

It's interesting, on my windows computer, I get the blinking tab only when I run apio from git bash. When I run apio from windows cmd, zadig starts up with no blinking. That's good because most windows users, I presume, use windows cmd.

On Sat, Nov 30, 2024 at 1:54 PM Carlos Venegas Arrabé < @.***> wrote:

Don't worry problem in my system, i'm on it

— Reply to this email directly, view it on GitHub https://github.com/FPGAwars/apio/issues/444#issuecomment-2509396173, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAQVMQIMPAU52RIBYL75FLD2DIXXVAVCNFSM6AAAAABQHQ2PJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBZGM4TMMJXGM . You are receiving this because you were mentioned.Message ID: @.***>

[zapta]

Inform the user about non obvious changes

• It's now recommended not to use VCD_OUTPUT and $dumpfile in testbenches.

[cavearr]

@zapta ,Why do you don't recomend it? if we modify the documentation could be interesting explain why and what is the preferred format.

[zapta]

@cavearr, I created here an issue for this feature request https://github.com/FPGAwars/apio/issues/481

Using DUMPSTR and VCD_OUTPUT is confusing and and unnecessary and with this new feature, hardcoding $dumpfile("my_tb.vcd") may lead to inconsistency because it may conflict with where apio is expects the file. For example, we moved all the artifact files from the project dir to _build subdirectory and the hard coded $dumpfile() stayed at the old place.

[zapta]

Create new packages releases and update distribution.json

The goal is to make sure that the packages repos and their build script are not broken and that the releases included the latest stuff.

1. For each packages in packages.json create a new release.
2. For each package in packages.json, set it's minimum version in distribution.json to the new release.

[zapta]

Test 'apio raw' on all platforms, using apio generated command

This release changed 'apio raw' with the goal of supporting all apio generated commands. For example the apio build generated command nextpnr-ice40 --hx8k --package tq144:4k --json hardware.json --asc hardware.asc --pcf main.pcf -q fail when run using apio raw on windows.

To test, on each platform, run the apio clean and then the commands apio build, apio lint, and apio sim, copy the commands they generate and run them using apio raw.

Note that with the new apio raw, quoting the entire command is not necessary.