apio error, can find ram.v for j1a

I don't know how to fix this, or even if it should be fixed.

It looks to me like you're trying to build this project with apio (which automates a lot of stuff that is otherwise done with make).

swapforth long predates apio, and uses make and the FPGA tools directly (including the old placer arachne-pnr) which you would normally have git cloned, built and installed separately. It also uses gforth and verilator, although recent version of the latter tend to break it.

The build is expected to be done like so (with an icestick plugged in!):

cd swapforth/j1a
make -C icestorm j1a

That does the build and also tries to flash it to the icestick.

Once flashed, you connect to it from the same directory with:

make connect

Then you can run words to see what the image has compiled in.

Further explanation:

build/ram.v is built according to recipe listed in swapforth/j1a/Makefile:

build/ram.v: build/nuc.hex mkrom.py
        python mkrom.py

make does this automatically, and then ram.v is included in-place by yosys.

This is the way it is so you can call #flash build/nuc.hex from a connection to the running system (made by make connect OR make sim_connect) to save the state of the system (eg, with all compiled forth words) overwriting the hex file.

You then rebuild ram.v again with make, before rebuilding the fpga bitfile again (make -C icestorm j1a), but now it comes up out of the FPGA's power-on with the system as you had it when it was dumped with #flash.

There is an additional mechanism so you can have the system call a word on startup, so it can run an application. If you make connect to that kind of image, it will reset just the j1a so you can talk forth to it again.

The nuc.hex you get if there is none (which initially there isn't - make notices and builds it again if so) contains just basewords.fs and nuc.fs - just the absolute minimum, assembed using gforth cross.fs, to result in a useful ultra-minimal swapforth system that knows nearly no words, but has just enough that it is possible to have it compile it's own swapforth image when swapforth.fs is sent to it.

This is done running an emulation of the j1a under verilator, which you kick off with make clean bootstrap

If or when verilator breaks this (they're a moving target) you can still compile the full swapforth image on the actual hardware, after connecting with a make connect:

#include ../swapforth.fs
#flash ../build/nuc.hex
#bye

then re-run make -C icestorm j1a and it should rebuild the full swapforth ans-almost-compliant image.

This was all written long before icestorm had the facility to replace block ram initial contents without rebuilding the bitfile, which is a thing now, although swapforth doesn't (yet) use it.

I'm not sure what apio is doing - but I'm sure it's just not expecting the build procedure to be how it is (which is decidedly a bit complex).

This therefore isn't a swapforth bug, so much as it's a apio bug.

I think apio tries to guess how to build a particular project, taking the place of make and a relatively complex Makefile like this.

I'd say the problem here is that apio isn't noticing that there's a perfectly usable Makefile nearby, and is instead trying to do its own thing? Or it's just not calling it in the expected way (which, to be fair, isn't very 'normal').

make isn't that bad - it's a very useful, flexible tool that rebuilds only things you've changed more recently than the last build (by default), swapforth's use of it isn't that complex, either - merely not guessable enough.

Typically, if you don't know how to drive make for a particular project, it's good to look for and read all the Makefiles, keeping a special eye out for the targets declared .PHONY: at the bottom. I.E. tail Makefile or so.

Those names are the 'shortcuts' used to kick off various things, and are probably the 'user interface' the author uses. Some make targets, like 'all', 'clean', 'install' are pretty common/standardized.

In this case swapforth only has 'clean', which just cleans up (almost) all the intermediate files. This actually doesn't include build/ram.v : it's mentioned in j1a/build/.gitignore as not to be checked in.

There are other projects using much more obtuse make target patterns that are more opaque to build bitfiles for FPGA's, usually so you don't have to edit said file, because it is possible to write one that knows the general steps for this, and I think this is what apio is using.

jamesbowman / swapforth

apio error, can find ram.v for j1a #82