HowTo ‐ A New DeMiSTify Guide - Maverick-Shark/retroGuru GitHub Wiki

HowTo DeMiSTify - A new Guide!!!

DeMiSTify is a procedure created by Alastair M. Robinson to port MiST cores to other FPGA systems. This code is copyrighted by the same author.

In this guide, we'll DeMiSTify a Vic-20 core to Poseidon FPGA system (Thanks to Rampa069).

Fork a MiST core

Fork a MiST core to your GitHub (better if it has converted to SiDi128 first).

Clone forked project choosing SSH link

$ cd /Cores
$ git clone --recursive [email protected]:Maverick-Shark/VIC20_MiST.git
$ cd VIC20_MiST/

Create a new branch

$ git branch demistified
$ git checkout demistified
$ git branch
* demistified
  master

Add DeMiSTify as a submodule

$ cd /Cores/VIC20_MiST/
$ git submodule add [email protected]:Maverick-Shark/DeMiSTify.git

And update it

$ git submodule update --init

Submodule 'T65' (https://github.com/mist-devel/T65.git) registered for path 'T65'
Submodule 'mist-modules' (https://github.com/mist-devel/mist-modules.git) registered for path 'mist-modules'
Cloning into '/Cores/VIC20_MiST/T65'...
Cloning into '/Cores/VIC20_MiST/mist-modules'...
Submodule path 'T65': checked out '7027ad169553911b1d55ce6d220364e7c8595b94'
Submodule path 'mist-modules': checked out '544540d1f69b1cf087a3402242ad7419bfb812a5'
$

$ cd DeMiSTify/
$ git submodule init
$ git submodule update

Create or copy (from other existent project) site.mk file

This file contents all Quartus routes related with the project. You can create a new one or copy and edit it from site.template file. Or copy from another site.mk file from other DeMiSTify project.

Copy site.mk file from other project to DeMiSTify folder

$ cd /Cores/VIC20_MiST/DeMiSTify/
$ cp /Cores/site.mk .

Create files.qip file (like project.qip) from .qsp file

Open .qsf file (preferably *_SiDi128.qsf) and select and copy all set_global_assignment entries related with VERILOG, SYSTEMVERILOG and QIP files (MiST project files), then paste to files.qip as a new file.
Look for

	set_global_assignment -name VERILOG_FILE <.v>
	set_global_assignment -name SYSTEMVERILOG_FILE <.sv>
	set_global_assignment -name QIP_FILE <.qip>

vic20_SiDi128.qsf file path

	/Cores/VIC20_MiST/vic20_SiDi128.qsf

Edit (create) files.qip file

$ vi /Cores/VIC20_MiST/files.qip

And paste selected entries

# set_global_assignment -name VERILOG_FILE ../build_id.v
set_global_assignment -name QIP_FILE ../T65/T65.qip
set_global_assignment -name QIP_FILE ../mist-modules/mist.qip
set_global_assignment -name SYSTEMVERILOG_FILE ../vic20.sv
set_global_assignment -name VERILOG_FILE ../keyboard.v
set_global_assignment -name SYSTEMVERILOG_FILE ../sdram.sv
set_global_assignment -name VERILOG_FILE ../sigma_delta_dac.v
set_global_assignment -name VHDL_FILE ../c1530.vhd
set_global_assignment -name VHDL_FILE ../tap_fifo.vhd
set_global_assignment -name QIP_FILE ../pll27.qip
set_global_assignment -name VHDL_FILE ../vic20/vic20_clocks.vhd
set_global_assignment -name VHDL_FILE ../vic20/vic20.vhd
set_global_assignment -name VHDL_FILE ../vic20/rc_filter_1o.vhd
set_global_assignment -name VHDL_FILE ../vic20/m6561.vhd
set_global_assignment -name VERILOG_FILE ../vic20/megacart_nvram.v
set_global_assignment -name VERILOG_FILE ../vic20/megacart.v
set_global_assignment -name VHDL_FILE ../c1541/via6522.vhd
set_global_assignment -name VHDL_FILE ../c1541/spram.vhd
set_global_assignment -name SYSTEMVERILOG_FILE ../c1541/mist_sd_card.sv
set_global_assignment -name VHDL_FILE ../c1541/gcr_floppy.vhd
set_global_assignment -name VHDL_FILE ../c1541/c1541_sd.vhd
set_global_assignment -name VHDL_FILE ../c1541/c1541_logic.vhd
set_global_assignment -name VHDL_FILE ../memories/ram_conf_8192x8.vhd
set_global_assignment -name VHDL_FILE ../memories/ram_conf_2048x8.vhd
set_global_assignment -name VHDL_FILE ../memories/ram_conf_1024x8.vhd
set_global_assignment -name VHDL_FILE ../memories/ram_conf_1024x4.vhd
set_global_assignment -name VHDL_FILE ../memories/gen_rom.vhd
set_global_assignment -name SDC_FILE vic20.sdc
set_global_assignment -name QIP_FILE pll_vic20.qip
set_global_assignment -name QIP_FILE pll_reconfig.qip
set_global_assignment -name QIP_FILE rom_reconfig_pal.qip
set_global_assignment -name QIP_FILE rom_reconfig_ntsc.qip

NOTE: Remember to put the correct path (i.e. adding '../').

Create Firmware folder

Create firmware folder and two important files that need to be present (config.h and overrides.c)

$ cd /Cores/VIC20_MiST
$ mkdir firmware
$ :> firmware/config.h
$ :> firmware/overrides.c

Makefile file

Copy template files

$ cd /Cores/VIC20_MiST
$ cp DeMiSTify/templates/Makefile .
$ cp DeMiSTify/templates/project_files.rtl .
$ cp DeMiSTify/templates/project_defs.tcl .
$ cp DeMiSTify/templates/demistify_config_pkg.vhd .

Edit Makefile file

$ vi /Cores/VIC20_MiST/Makefile
PROJECT=project                    // <- Remove this line!!!
PROJECT=vic-20                     // <- Add this!!!

$ ls -la /Cores/VIC20_MiST/*.tcl
-rw-r--r-- 1 root root 1407 Jan 30 00:43 build_id.tcl
-rw-r--r-- 1 root root  102 Feb  1 18:21 project_defs.tcl

Edit project_files.rtl file

Change project.qip file by files.qip

$ vi /Cores/VIC20_MiST/project_files.rtl
project.qip                    // <- Remove this line!!!
files.qip                      // <- Add this!!!

Remove all lines below line 15 if not used or it will give error

# or:  standard firmware
# DeMiSTify/controller/firmware_std.qip

# Pre-flow scripts
# rtl/build_id.tcl

And add build_id.tcl (or build_id_altera.tcl) entry at the end of file

build_id.tcl

Compile firmware

$ cd /Cores/VIC20_MiST
$ make firmware

Board folder

$ ls -la /Cores/VIC20_MiST/DeMiSTify/Board/poseidon-ep4cgx150/

Make init

$ cd /Cores/VIC20_MiST
$ make BOARD=poseidon-ep4cgx150 init

Go to Poseidon folder

$ cd /Cores/VIC20_MiST/poseidon-ep4cgx150

Copy all pll related files to the board folder (Poseidon folder)

$ cp ../pll_vic20.qip .
$ cp ../pll_vic20.v .
$ cp ../pll_vic20_ntsc.mif .
$ cp ../pll_vic20_pal.mif .
$ cp ../pll_reconfig.qip .
$ cp ../pll_reconfig.v .
$ cp ../pll27.qip .
$ cp ../pll27.vhd .

Copy all memory controllers related files to the board folder (Poseidon folder)

$ cp ../rom_reconfig_pal.qip .
$ cp ../rom_reconfig_pal.v .
$ cp ../rom_reconfig_ntsc.qip .
$ cp ../rom_reconfig_ntsc.v .

Copy SYSTEMVERILOG file (.sv)

$ cd /Cores/VIC20_MiST/poseidon-ep4cgx150
$ cp ../DeMiSTify/templates/poseidon-ep4cgx150/poseidon_top.sv .

Edit demistify_config_pkg.vhd file

$ vi /Cores/VIC20_MiST/demistify_config_pkg.vhd

And comment the following line (CLOCK_27 entry) or you can't delete the line bellow if you want

--CLOCK_27      :       IN STD_LOGIC_VECTOR(1 downto 0);        -- to match the guest core

Edit vic20.sv file and change module entry

$ vi /Cores/VIC20_MiST/vic20.sv
        module vic20_mist                    // <- Remove this line!!!
        module guest_top                     // <- Add this!!!

Create top.qip file

Go to Poseidon folder

$ cd poseidon-ep4cgx150

Add edit/create top.qip file

$ vi /Cores/VIC20_MiST/poseidon-ep4cgx150/top.qip
set_global_assignment -name QIP_FILE pll27.qip
set_global_assignment -name QIP_FILE pll_vic20.qip
set_global_assignment -name QIP_FILE pll_reconfig.qip
set_global_assignment -name QIP_FILE rom_reconfig_pal.qip
set_global_assignment -name QIP_FILE rom_reconfig_ntsc.qip

Modify all pll .vhd files (clk and frequency)

$ vi /Cores/VIC20_MiST/poseidon-ep4cgx150/pll27.vhd

        clk0_divide_by => 27,                               // <- Remove this line!!!
        inclk0_input_frequency => 37037,                    // <- Remove this line!!!

        clk0_divide_by => 50,                               // <- Add this!!!
        inclk0_input_frequency => 20000,                    // <- Add this!!!

Edit pll_vic20.v file

# vi /Cores/VIC20_MiST/poseidon-ep4cgx150/pll_vic20.v

        altpll_component.clk0_divide_by = 27000000,                    // <- Remove this line!!!
	altpll_component.inclk0_input_frequency = 37037,               // <- Remove this line!!!

        altpll_component.clk0_divide_by = 50000000,                    // <- Add this!!!
        altpll_component.inclk0_input_frequency = 20000,               // <- Add this!!!

Change mist-modules branch to master

$ cd /Cores/VIC20_MiST/mist-modules/
$ git log
$ git checkout master

Open the project (file .qpf) in Quartus

        \Cores\VIC20_MiST\poseidon-ep4cgx150\vic-20_poseidon-ep4cgx150.qpf

And run it.

That's all folks!!!

Push to Github

$ git status                                      // Check files to push
$ git diff
$ git add .                                       // Add files
$ git commit -am "DeMiSTify Poseidon board"
$ git remote add origin [email protected]:Maverick-Shark/DeMiSTify.git
$ git push --set-upstream origin demistified

$ git remote -v
$ git remote remove origin

$ ssh-keygen -t rsa -b 4096 -C "[email protected]"

Changing committed files (amend)

Check last commits

git log -n 2 --oneline

git log --oneline --all --graph --decorate

git log --reflog
git reset --soft 55d43e9ff8571c3f323441748046c461a85e3869

Example:

# Edit files.qip and top.qip and add only files.qip file
git add files.qip
git commit

# Realize you forgot to add the changes from top.qip 
git add poseidon-ep4cgx150/top.qip 
git commit --amend --no-edit
git push --force

# Move the current head so that it's pointing at the old commit
git reset --soft HEAD@{1}
# Commit the current tree using the commit details of the previous
# HEAD commit.
git commit -C HEAD@{1}

Remove last commit from GitHub

First way

git reset --hard HEAD^
git push origin -f

Another way

git reset --hard HEAD~1
git push --force

Recover the deleted commits

git reflog
git reset --soft e0814474

Where 'e0814474' is the head number of the previous step.

git reflog
git reset --hard e0814474

Return removed commit to GitHub

Step 1. Find full SHA of deleted commit

git fsck --lost-found

Example output:
Checking object directories: 100% (256/256), done.
Checking objects: 100% (3/3), done.
dangling commit 5601624a8926d4426ad42768bd0637fd82b70b80
dangling commit d5ee3e10a2c8b17b4e3cd7ee0562d6cdafacc5fa
dangling commit 1b0b23f462cb4c560c3adfa821bcddd4e53e6a43
dangling blob b99c193caeccb77af13df8adb0358cee0b93eb82

Step 2. Recover the dangling commit with rebase

git rebase 5601624a8926d4426ad42768bd0637fd82b70b80
git push

Fork a branch

$ cd /path/to/local/repo
$ git remote add upstream /url/of/original/repo
$ git fetch upstream
# That last fetch will include the new branch (in the remotes/upstream namespace)

# From there, you can easily create a local branch starting from that upstream/newBranch
# and push it to your fork (referenced by the remote named 'origin')
$ git checkout -b newBranch upstream/newBranch
$ git push -u origin newBranch

Change submodule branch

$ git clone --branch demistified --recursive [email protected]:Maverick-Shark/TatungEinstein_DeMiSTify.git

$ git clone --recursive [email protected]:Maverick-Shark/TatungEinstein_DeMiSTify.git
$ git switch -c demistified
$ git branch
* demistified
main
$ git branch -a

Add submodule branch

# Get the submodule initially
$ git submodule add [email protected]:Maverick-Shark/DeMiSTify.git
$ git submodule init

Steps

# Time passes, submodule upstream is updated
# and you now want to update

# Change to the submodule directory
$ cd DeMiSTify

# Check current branch
$ git branch

# Checkout desired branch
$ git checkout main

# Update
$ git pull

# Get back to your project root
$ cd ..

# Now the submodules are in the state you want, so
$ git commit -am "Pulled down update to submodule_dir"

# Update remote submodule (not needed)
$ git submodule update --remote --merge

Remove a submodule

Delete the relevant section from the .gitmodules file.
Stage the .gitmodules changes git add .gitmodules.
Delete the relevant section from .git/config file.
Run git rm -r --cached path_to_submodule (no trailing slash).
Run rm -rf .git/modules/path_to_submodule (no trailing slash).
Commit git commit -m "Removed submodule".
Delete the now untracked submodule files rm -rf path_to_submodule.

Where path_to_submodule is the module to remove (i.e. mist-module).

Deinit a submodule:

git submodule deinit -f mist-module

Script

DeMiSTify-Vic20.sh

Notes

Thanks to Somhic and Rampa for sharing their knowledge!!!
All repos (vic20_mist and DeMiSTify) have been cloned from rampa069 github.
The Best Guide (by Somhic) DeMiSTifying-a-MiST-core
Install make, gcc, build-essencial and ncurses lib

$ apt install make
$ apt install gcc
$ apt install build-essential
$ gcc --version
$ apt -y install libncurses-dev

Change environment (LANG LOCALE)

$ vi /etc/environment
# add following lines...
LANG=en_US.utf-8
LC_ALL=en_US.utf-8

# and Create locale file manually
$ localedef -i en_US -f UTF-8 en_US.UTF-8

Alternatively, Create locale file manually: localedef -i en_US -f UTF-8 en_US.UTF-8

Other useful references

Porting the VIC20 core https://retroramblings.net/?p=1752
Mist-devel Porting Cores