Skip to content

Latest commit

 

History

History
310 lines (238 loc) · 19 KB

0156-2023-10-10.md

File metadata and controls

310 lines (238 loc) · 19 KB

10 Oct 2023

Previous journal: Next journal:
0155-2023-10-09.md 0157-2023-10-11.md

tt05-vga-spi-rom improvements

Accomplishments

  • Adjusted to send SPI read preamble before visible end of line.
  • Now up to full 128-bits (16 bytes) storage. Even try more and see if still fits in 1x1.
  • Created initial dumb cocotb test in order to prove we can generate a VCD file. See: Automated Tests.
  • Made tests run in GitHub Action.
  • Added spiflash to test, and it runs as expected in GHA. Some unexpected X signals but probably due to some regs not having reset (esp. byte_alt?)

Goals

  • Implement cocotb/verilator and add in Claire Wolf's spiflash so we can prove it works in sim.
  • Rework posedge/negedge and byte bars, with registers for start/stop.
  • SMELL: RESET signal should drive SPI /CS high and keep it high until the next valid sequence starts.
  • Test out extra RGB333 range. Show colour bars/palette in otherwise unused screen area?
  • Ensure that RGB111, RGB222, RGB333 all give results that can be visually interpreted.

Stretch

  • Add instructions to README for setting up and running tests
  • DPI/QPI
  • Delay line
  • Attempt re-display of data as mapped to tiny hex characters -- do colour pairs for bytes.
  • For interest, besides just more inputs to switch things, try periodically incrementing the address high bits. Have a way to control the speed, and it could be an animation! Even have the option to let the data in the SPI ROM specify the delay, or have an actual data stream elsewhere in the ROM that specifies which 'frames' to display, in what order, with what timing.
  • Find out how to use GTKWave filters to:
    • Generate colours from signal values (e.g. RGB combo).
    • Decode SPI.

Next steps

  • Add to README to describe how to set up everything and run the tests.
  • Find out in cocotb how to do things like:
    • Prove that for the duration of a multi-step test, given signals maintain a fixed state (e.g. uio_oe stays constant).
    • Count the number of edges of something during a multi-step test.

Later

  • Submit cocotb bug report for Makefile python errors.
  • Consider installing pytest per: pytest not found, install it to enable better AssertionError messages

Automated Tests

Inspiration for cocotb tests:

Notes

  • Throwing back to 0152, I've got Python installed. Now I need: cocotb; iverilog.
  • I've now got these 3 in my user PATH: 
    C:\msys64\usr\bin
C:\msys64\mingw64\bin
C:\msys64\ucrt64\bin
  • It might be possible to install Verilator using pacman, i.e. run pacman -Ss verilator to search for a version, then pacman -S packagename to install it. Not sure I need to do that because on Windows I've already got C:\msys64\mingw64\bin\verilator_bin.exe in my PATH via MSYS2. --version says: Verilator 4.228 2022-10-01 rev UNKNOWN.REV
  • Should the tests (namely tb.v) target the TT05 top module, or just our main design (vga_spi_rom)? For now it's the latter.
  • What is the TT05 convention for where to place and how to configure tests? I'm putting them all in test/ to stay tidy, but in the past I've put them in src/ directly and I've seen others do this too (e.g. robojan).

Setup steps

  1. I'll use cocotb for now. Follow 2310B to install cocotb and iverilog on Windows. This includes gtkwave also.
  2. Go into the project dir...
  3. Create a .venv for cocotb and these tests. In PowerShell: 
    py -m venv .venv --prompt venv:tt05-vga-spi-rom
echo '*' >> .venv/.gitignore
.\.venv\Scripts\Activate.ps1
  4. In my repo, I now have requirements.txt containing cocotb, so install those Python packages: 
    py -m pip install -r requirements.txt
  5. NOTE: From this point forwards, I'm using the cocotb 1.8.1 Quickstart Guide...
  6. In the project dir, go into src. NOTE that TT projects conventionally have their tests in src/...? Certainly the .gitignore from the TT05 template project is set up to expect this. Otherwise, I would've created test/ and put everything in there.
  7. Now in src/, create the testbench, tb.v. Main points:
    • Define inputs and outputs that we want the tests to have control over, giving them meaningful names.
    • Have an initial block that specifies the $dumpfile (in this case tb.vcd).
    • Instantiate and wire up the design, calling it uut. In this case, it's the vga_spi_rom module.
  8. Create test.py and fill it in. Using Example: 
    import cocotb
from cocotb.clock import Clock
from cocotb.triggers import Timer, ClockCycles

@cocotb.test()
async def test_basic_waveform_dump(dut):
    """
    Just start a clock, apply reset, and let the design free-run for 500,000 cycles;
    enough to generate at least 1 full VGA frame and dump to VCD
    """

    cocotb.start_soon(Clock(dut.clk, 40.0, units='ns').start())

    # Start with 'reset' low (released):
    dut.reset.value = 0

    # Wait an arbitrary 150ns...
    await Timer(150, units='ns')
    # ...then assert 'reset':
    dut.reset.value = 1
    # ...and wait another 250ns...
    await Timer(250, units='ns')
    # ...then release 'reset'
    dut.reset.value = 0

    # ...now the design free-runs for another 500,000 cycles:
    await ClockCycles(dut.clk, 500_000)
  9. Create Makefile, but BEWARE: Indentation must be TAB characters, not SPACES which might be given below. If necessary, use the VSCode Command Palette to select 'Indent using tabs' and then again to do 'Convert indentation to tabs': 
    # Makefile
# See https://docs.cocotb.org/en/stable/quickstart.html for more info

# defaults
SIM ?= icarus
TOPLEVEL_LANG ?= verilog

VERILOG_SOURCES += $(PWD)/tb.v \
	$(PWD)/../src/tt05_top.v \
	$(PWD)/../src/vga_sync.v \
	$(PWD)/../src/vga_spi_rom.v

# TOPLEVEL is the name of the toplevel (testbench) module in your Verilog (typically tb.v file):
TOPLEVEL = tb

# MODULE is the basename of the Python test file (i.e. typically from test.py):
MODULE = test

# include cocotb's make rules to take care of the simulator setup
include $(shell cocotb-config --makefiles)/Makefile.sim

At this point, I then tried running the tests with simply make, and things went wrong. NOTE: When I originally ran this, my tests were in test/ but I've since moved them to src/ as is the TT convention. Accordingly, fewer errors should result because the sources are all in the same dir

bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
rm -f results.xml
/usr/bin/make -f Makefile results.xml
make[1]: Entering directory '/c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test'
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
mkdir -p sim_build
/ucrt64/bin/iverilog -o sim_build/sim.vvp -D COCOTB_SIM=1 -s tb -f sim_build/cmds.f -g2012   /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/tb.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/tt05_top.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/vga_sync.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/vga_spi_rom.v
C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/tt05_top.v:5: Include file helpers.v not found
C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/tb.v:12: syntax error
C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/tb.v:1: Errors in port declarations.
make[1]: *** [/c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/.venv/Lib/site-packages/cocotb/share/makefiles/simulators/Makefile.icarus:81: sim_build/sim.vvp] Error 2
make[1]: Leaving directory '/c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test'
make: *** [C:\Users\Maurovics\Documents\projects\tt05-vga-spi-rom\.venv\Lib\site-packages\cocotb\share\makefiles/Makefile.inc:40: sim] Error 2

Let's unpack this:

  • bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
    • Can't find python. Evidently venv is giving Windows paths to bash (belonging to MSYS2?)
  • C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/tt05_top.v:5: Include file helpers.v not found
    • OK, need to figure out how to help it find this src/helpers.v include file. Maybe just an -I parameter or something? Yes: VERILOG_INCLUDE_DIRS.
  • C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/tb.v:12: syntax error
    • Oops, simple missing comma in ports list. Fixed.

Updated Makefile:

# Makefile
# See https://docs.cocotb.org/en/stable/quickstart.html for more info

# defaults
SIM ?= icarus
TOPLEVEL_LANG ?= verilog

VERILOG_SOURCES += $(PWD)/tb.v \
	$(PWD)/../src/tt05_top.v \
	$(PWD)/../src/vga_sync.v \
	$(PWD)/../src/vga_spi_rom.v

VERILOG_INCLUDE_DIRS += \
	$(PWD)/../src

# TOPLEVEL is the name of the toplevel (testbench) module in your Verilog (typically tb.v file):
TOPLEVEL = tb

# MODULE is the basename of the Python test file (i.e. typically from test.py):
MODULE = test

# include cocotb's make rules to take care of the simulator setup
include $(shell cocotb-config --makefiles)/Makefile.sim

When I run make now, I still get errors about ...python.exe: command not found but it actually runs:

bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
rm -f results.xml
/usr/bin/make -f Makefile results.xml
make[1]: Entering directory '/c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test'
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
bash: line 1: C:UsersMaurovicsDocumentsprojectstt05-vga-spi-rom.venvScriptspython.exe: command not found
/ucrt64/bin/iverilog -o sim_build/sim.vvp -D COCOTB_SIM=1 -s tb -f sim_build/cmds.f -g2012  -I/c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src  /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/tb.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/tt05_top.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/vga_sync.v /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/test/../src/vga_spi_rom.v
rm -f results.xml
MODULE=test TESTCASE= TOPLEVEL=tb TOPLEVEL_LANG=verilog \
         /ucrt64/bin/vvp -M C:/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/.venv/Lib/site-packages/cocotb/libs -m cocotbvpi_icarus   sim_build/sim.vvp 
     -.--ns INFO     gpi                                ..mbed\gpi_embed.cpp:106  in set_program_name_in_venv        Using Python virtual environment interpreter at C:\Users\Maurovics\Documents\projects\tt05-vga-spi-rom\.venv\Scripts\python
     -.--ns INFO     gpi                                ..\gpi\GpiCommon.cpp:101  in gpi_print_registered_impl       VPI registered
     0.00ns INFO     cocotb                             Running on Icarus Verilog version 12.0 (devel)
     0.00ns INFO     cocotb                             Running tests with cocotb v1.8.1 from C:\Users\Maurovics\Documents\projects\tt05-vga-spi-rom\.venv\Lib\site-packages\cocotb
     0.00ns INFO     cocotb                             Seeding Python random module with 1696900272
     0.00ns INFO     cocotb.regression                  pytest not found, install it to enable better AssertionError messages
     0.00ns INFO     cocotb.regression                  Found test test.test_basic_waveform_dump
     0.00ns INFO     cocotb.regression                  running test_basic_waveform_dump (1/1)
                                                          Just start a clock, apply reset, and let the design free-run for 500,000 cycles;
                                                          enough to generate at least 1 full VGA frame and dump to VCD
VCD info: dumpfile tb.vcd opened for output.
20000360.00ns INFO     cocotb.regression                  test_basic_waveform_dump passed
20000360.00ns INFO     cocotb.regression                  ***************************************************************************************
                                                          ** TEST                           STATUS  SIM TIME (ns)  REAL TIME (s)  RATIO (ns/s) **
                                                          ***************************************************************************************
                                                          ** test.test_basic_waveform_dump   PASS    20000360.00          19.37    1032760.04  **
                                                          ***************************************************************************************
                                                          ** TESTS=1 PASS=1 FAIL=0 SKIP=0            20000360.00          19.40    1031193.10  **
                                                          ***************************************************************************************

View the VCD file it generated: gtkwave tb.vcd tb.gtkw -- NOTE: I already wrote the tb.gtkw "Save File" into this repo.

GTKWave might appear blurry or oversized if High DPI is used in Windows. While GTKWave is running, right-click it in the taskbar, go to Properties => Compatibility => Settings => Change high DPI settings => then tick Override high DPI scaling behavior and set Scaling performed by: to Application. Launch it again, and it should look much clearer and at a normal size.

Adapting tests

Notes

Add test GHA to replace wokwi_test

This comes from here.

  1. Go into .github/workflows/
  2. Delete wokwi_test.yaml: git rm wokwi_test.yaml
  3. Download test.yaml and save it in the workflows.
  4. Add it: git add test.yaml
  5. Add this snippet to README, replacing the wokwi one: ![](../../workflows/test/badge.svg)

Run tests again from new home in src/

  1. Modified Makefile
  2. make -d (note extra debug option -- oh wow it spits out a lot!)
  3. It works. Time to check out that debug output and see what's wrong with Python.

Working out Python/cocotb/Makefile weirdness:

Gate-level tests

  • I need to do more research on this. Check out my tt03p5-solo-squash Makefile which has all the extra args that might assist this, but also check latest TT05 stuff that Uri has been working on for GL-sim.
  • Actually, maybe just start in the official TT guide

Adding spiflash

  1. Download spiflash.v from this page.
    • Claire Xenia Wolf created the original spiflash.v (see here).
    • The file we're getting, though, is a modified version used in Caravel, and it includes support for a filename parameter and Continuous Mode.
  2. Put it in src/
  3. Grab a copy of the ROM we want to use. In this case it's the one I extracted in 0150 from an ESP-01 board.
  4. Convert it to a hex file compatible with $readmemh. I couldn't use hexdump format strings properly in PowerShell (maybe it was mucking up my args?) but it worked OK in MSYS2 and Linux: 
    cd /c/Users/Maurovics/Documents/projects/tt05-vga-spi-rom/src
hexdump -v -e '16/1 "%02X ""\n"' test_rom.bin > test_rom.hex
head -10 test_rom.hex
# E9 03 02 20 20 04 10 40 00 00 10 40 40 07 00 00 ...
  5. Add reference to it and its original sources in the README.
  6. Wire it up in tb.v and add it to Makefile.
  7. CHECK: Make sure all design signals are connected, or at least accounted for: clk, rst_n, ena, ui_in, uo_out, uio_in, uio_out, uio_oe.

Notes