# Steps for Hello World Microwatt ls2 for fpga/boards 

* Currently works for Arty A7-100t, VERSA_ECP5 and in future others
* Bugzilla page <https://bugs.libre-soc.org/show_bug.cgi?id=802>
* NGI POINTER  <https://bugs.libre-soc.org/show_bug.cgi?id=818>
* [Bug #1127 - Generating core with SVP64](https://bugs.libre-soc.org/show_bug.cgi?id=1127)

# Install Instructions

    # devscripts
    git clone https://git.libre-soc.org/git/dev-env-setup.git
    cd dev-env-setup
    sudo bash
    ./mk-deb-chroot ls2-hello-world
    ./cp-scripts-to-chroot ls2-hello-world
    exit # back to user

    schroot -c ls2-hello-world
    sudo bash # helps define SUDO_USER in new chroot
    cd ~/dev-env-setup

    # install dependencies in new chroot
    ./install-hdl-apt-reqs
    ./hdl-dev-repos
    ./hdl-tools-yosys
    ./nextpnr-xilinx-install
    ./hdl-dev-ls2

    # if you intend to upload fpga bitstreams in the same chroot, also need
    # the fpga utilities
    ./fpga-boot-load-prog-install

    cd ~/src

    # make hello_world.bin from microwatt
    cd tercel-qspi/
    cd hello_world/
    make
    cp hello_world.bin ../../ls2
    cd ../..

    # make the Libre-SOC core (for external use)
    cd soc
    make microwatt_external_core
    cp external_core_top.v ../ls2

    # check out ls2 peripheral framework
    cd ../ls2
    git checkout 426e2d9585cd4b1fb96a38987f97878285ee5ba7

    export PATH=/usr/local/nextpnr-xilinx/bin:$PATH
    export XRAY_DIR=/usr/local/nextpnr-xilinx

    # plug in FPGA board (Arty A7-100t, VERSA_ECP5, other)
    # run in 2nd terminal "minicom -D /dev/ttyUSB1"

    python3 src/ls2.py arty_a7 hello_world.bin    # for Arty A7-100t
    python3 src/ls2.py versa_ecp5 hello_world.bin # (for a VERSA_ECP5)

This directly programs a tmp bitstream using xc3sprog to nexys4 board.
If needed modify sources to produce a fixed file bitstream and

    copy build/top.bit to board/server (scp, rsync)
    minicom -D /dev/ttyUSB1
    xc3sprog -c nexys4 top.bit

If there are multiple Arty-A7-100t boards connected you need to know
the serial number (lsusb | grep Serial)

    xc3sprog -c nexys4 -s {insert_full_serial_number} top.bit

# Using ls2 with microwatt

This is doable but tricky.  An older version is required at present.

    git clone https://git.libre-soc.org/git/microwatt.git
    git checkout microwatt_verilator
    make microwatt.v

From there, some hand-editing is required.  search for core_NNNNNNN_XXX_YYY
and rename it to external_core_top. Save the file as external_core_top.v
and it can be used in place of the Libre-SOC Core, above.

In fact any core can be used with ls, as long as it is compliant with
the interfaces.  Both Wishbone Interfaces must be WB4 Pipeline
compliant (proper stall handling) or the stall signal faked externally
with a wrapper: `stall=stb&~ack`

# Using ls2 with verilator

first you need to build hello_world (or any other firmware) to start at 
0xff000000. Then you can run build ls.v using that firmware:

    python3 src/ls2.py sim /tmp/ff000000_hw.bin

The output of that command is:

    platform sim /tmp/ff000000_hw.bin None
    fpga sim firmware /tmp/ff000000_hw.bin
    ddr pins None
    spiflash pins None
    ethmac pins None
    hyperram pins [<lambdasoc.periph.hyperram.HyperRAMPads object at 0x735e9940dd30>]
    fw at address ff000000
    SRAM 0x8000 at address 0x0

To use verilator, make sure to run the devscript:

    ./verilator-install

And set the GHDLSYNTH and update PATH:

    export PATH=/usr/local/verilator/bin:$PATH
    export GHDLSYNTH=ghdl

After that you can compile microwatt-verilator:

	export FPGA_TARGET=verilator
	make microwatt-verilator

# Estimating transistor count using yosys

Use yosys to run synthesis and using `stat` to view gate/transistor count:

    cd src/ls2/
    yosys
    yosys> read_verilog ls2.v external_core_top.v ../uart16550/rtl/verilog/*.v
    yosys> synth
    yosys> tee -a stat_cmos.log stat -tech cmos

Then you can view the resulting log file afterwards. Bare in mind `synth` will probably take a while. **TODO: Find multi-threaded option**