Change the memory map and refactor MMIO registers

[sy2002]

EDIT 31.7.20, 21:57: Changed/Updated TODO LIST

@bernd-ulmann @MJoergen

Here are all steps necessary that came to my mind spontaneously. Please add your thoughts, maybe I forget something:

DONE BY SY2002 and VAXMAN Let's discuss the new Memory Map in monitor/sysdef.asm here based on the assumption: The standard is 8 words for 8 registers per device, but we also allow devices to have 16 words. 256 words of MMIO space starting at FF00.

• This will break all existing code, but a simple recompile should fix it.

DONE BY VAXMAN * There are some programs in test_programs that still use hard-coded registers and the emulator also uses hardcoded register addresses: We need to sift through them and fix them.

DONE BY VAXMAN * The emulator should include ../dist_kit/sysdef.h (**) instead of using hardcoded own #defines to access registers

• Recompile standard C library

• Update MMIO hardware

• Recompile all qbin files and update it in GitHub

DONE BY SY2002 Add MEGA65 MMIO to sysdef.asm and adjust MEGA65 samples and VHDL CODE

re (**) @MJoergen : FYI: The file monitor/sysdef.asm is the single source of truth. There is a script called monitor/compile_and_distribute.sh which is copying monitor/sysdef.asm to dist_kit/sysdef.asm and while doing so also generates a dist_kit/sysdef.h for being used e.g. in the emulator but this dist_kit/sysdef.h is also used in the implementation of the standard C library of QNICE that you find in c/qnice (off-topic and by the way, a small intro how to use the C compiler is here: https://github.com/sy2002/QNICE-FPGA#programming-in-c)

[bernd-ulmann]

I just had a look at the test programs. The following ones use hard coded IO space addresses:

regbank.asm, til_count.asm, uart.asm

The remaining programs are OK. :-)

[bernd-ulmann]

I have replaced all of the magic constants to the IO area within the test programs by the appropriate constants read from ../dist_kit/sysdef.h, so the test programs should now be clean regarding the pending restructuring of the IO address space. :-)

[bernd-ulmann]

The emulator now also uses the constants defined in ../dist_kit/sysdef.h instead of its own #defines. :-)

[sy2002]

For not increasing the amount of loose ends: There is a branch called dev-IO-addr that is a descendant of dev-int that contains these breaking changes. We will merge it to dev-int when dev-int is kind of stable just before merging dev-int back into develop.

[sy2002]

TODO: When all qbin files are recompiled, then also the default disk image that emulator/run_vga.bash uses needs to be recreated/updated: DISK_IMAGE=http://sy2002x.de/hwdp/qnice_disk.img and after that emulator/run_vga.bash also needs to be updated.

BUT: As this file is also used by the online emulator at https://qnice-fpga.com/emulator.html and as I do not want to update the online emulator to the new MMIO addresses right now (because nobody would notice and it takes some effort) I guess we need to introduce a new version here: The current disk image download file http://sy2002x.de/hwdp/qnice_disk.img will be for pre V1.6 and then there will be a new disk image file http://sy2002x.de/hwdp/qnice_disk_v16.img for V1.6 and later.

[sy2002]

Smoke Test for the "new" emulator with the modified MMIO map successful. I just played a quick round of Q-TRIS in the emulator. Admitably not very successful - but good enough for a smoke test 😆 See screen:

[sy2002]

As we used EDIT to update the above-mentioned TODO list, here are the remaining TODOs for this:

• Recompile standard C library
• Perform some smoke tests for the recompiled standard C library
• Update MMIO hardware
• Test the updated MMIO hardware
• Search for old addresses in the comments in the VHDL files (e.g. keyboard.vhd) and replace them all
• Recompile all /qbin demos and tools and check-in the new /qbin
• Create a new disk image as described here
• Modify emulator/run_vga.bash to support the new disk image
• Put the new disk image also to the two standard SD card (Nexys4DDR and MEGA65) and test them there
• Do not update the website http://qnice-fpga.com/emulator.html as nobody would notice the MMIO change there, BUT: We need to update the source code to download the V1.6 version of the disk image. Then: Do a smoke test locally by recompiling and testing the WebAssembly version of the emulator.

I guess, when all this is successfully done, we can close this issue.

Everything regarding this issue needs to take place in branch dev-io-addr

[sy2002]

@bernd-ulmann I just discovered, that you need to update the programming card at doc/programming_card/programming_card.tex and generate and check-in two new versions of the print and screen PDFs: programming_card_printable.pdf and programming_card_screen.pdf. Please switch to branch dev-io-addr before doing so.

[MJoergen]

I would like a short section on Memory Map somewhere, perhaps in the top-level README just before the section on "Programming in Assembler".

Later, when the VGA module gets updated with colours etc, I would like to add a section on the memory map of the video memory.

[sy2002]

Sounds great, Michael. Would you like to do that (in the branch dev-io-addr)? A great test for your new commit rights :-)

Bernd also already updated the programming card, that is mentioned in the top-level README as the first bullet point in the "Programming in Assembler" section. There, the memory map is also shown: https://github.com/sy2002/QNICE-FPGA/blob/dev-io-addr/doc/programming_card/programming_card_screen.pdf If you also want to see this in the README, then you might want to copy/paste the info from the .tex file so that you don't need to re-write it from scratch.

[MJoergen]

Done.

[sy2002]

We should add "refactor keyboard.vhd" as described in Issue #22 to the list of "things to be done before we can close this issue and merge the branch dev-io-addr". So here is the TODO list:

• Refactor keyboard.vhd
• Update MMIO hardware
• Search for old addresses in the comments in the VHDL files (e.g. keyboard.vhd) and replace them all
• Test the updated MMIO hardware
• MEGA65: Update the hardware, update the test programs, retest on hardware
• Recompile standard C library
• Perform some smoke tests for the recompiled standard C library
• Recompile all /qbin demos and tools and check-in the new /qbin
• Create a new disk image as described here
• Modify emulator/run_vga.bash to support the new disk image
• Put the new disk image also to the two standard SD card (Nexys4DDR and MEGA65) and test them there
• Do not update the website http://qnice-fpga.com/emulator.html as nobody would notice the MMIO change there, BUT: We need to update the source code to download the V1.6 version of the disk image. Then: Do a smoke test locally by recompiling and testing the WebAssembly version of the emulator.

[MJoergen]

Recompile all /qbin demos and tools and check-in the new /qbin

I think it would make sense to write a Makefile and include in the qbin directory to automate the build process. As it is now, the source files are scattered all over the repository, and it is a rather tedious and manual process to recompile those files.

[sy2002]

I think it would make sense to write a Makefile and include in the qbin directory to automate the build process. As it is now, the source files are scattered all over the repository, and it is a rather tedious and manual process to recompile those files.

Very good point: DONE: Create makefile and recompile all /qbin demos with the new memory map

[sy2002]

Update: Done regarding dev-io-addr:

• Recompile standard C library
• Perform some smoke tests for the recompiled standard C library
• Recompile all /qbin demos and tools and check-in the new /qbin
• Create a new disk image
• Modify emulator/run_vga.bash to support the new disk image
• Do not update the website http://qnice-fpga.com/emulator.html as nobody would notice the MMIO change there, BUT: We need to update the source code to download the V1.6 version of the disk image (with the old memory map, as the online demo of the emu is still working in the old world). Then: Do a smoke test locally by recompiling and testing the WebAssembly version of the emulator.

What remains to be done regarding dev-io-addr:

• MEGA65: Update the hardware, update the test programs, retest on hardware
• Put the new disk image also to the two standard SD card (Nexys4DDR and MEGA65) and test them there
• Fix newly found bug while smoke testing recompiled qbins: emulator crashes on sierpinski.out (see new issue Emulator crashes on EAE (?) in sierpinski.c #32)
• Sift through all documentation parts (such as doc/README.md and others) and fix old MMIO addresses
• Due to the fact, that this branch also contains the refactored mmio_mux (issue Refactor mmio_mux #22) and due to the fact that mmio_mux was also heavily enhanced in regards to IGRANT_N in the dev-int branch: Think about how to merge

Looks like we are nearly there, when it comes to the topic of "Change the memory map and refactor MMIO registers"

[sy2002]

CONSOLIDATION => CLOSED/DUPLICATE => Will continue to finish this in issue #69