Welcome to the user-defined TigerSBC DDE (Disintegrated Design Environment).
TigerSBC is fun to program, and if you like being in the driver's seat, this machine might be for you.

TigerSBC_yyyy_mm_dd.zip is a snapshot of experimentally verified hardware and software source files, for free use at one's own risk.

Many Python3 and Verilog source iterations led to this snapshot. Mistakes were made along the way, and corrected. (See doc/koans.txt.)
It is hoped that users will enjoy making and correcting their own mistakes, and sharing their successes.

This DDE implements a 12-bit 36 MHz lab/maker computer on a Lattice iCE40-HX8K FPGA Breakout Board, and its assembler.

Why 12 bits versus industry norms?
1) more powerful than 8 bits
2) simpler and faster than 16/32/64 bits
3) object code is compact, minimizing memory overhead
4) naturally matches popular 12-bit SPI ADCs and DACs for the lab/maker computer mission

TigerSBC's performance and code-density apparently rivals commodity MCUs. The entire 4Kx12 code/data/io memory space is on-chip. All reads and writes complete in one (1) clock cycle.

5V0 power and the host interface are provided via USB. Memory-mapped io includes a 28-bit signed multiplier/accumulator and a 48-bit timer. Efficient 12-bit bit-banging parallel io, and an 8-bit mode 0 master SPI interface are also provided for 3V3 user io. doc/EB85_pins.txt summarizes user io on the J2 and J4 2x20 0.1 inch (2.54 mm) pitch connectors.

Software libs and apps include Fast Fourier Transform and convolution DSP amenities. A 512-point complex FFT takes ~13 ms. An 8-point complex FFT takes ~78 us.

Tigerasm is written in Python3, providing a powerful syntax and interactive user interface. New users should first learn how to program their own Tigerasm libs and apps for the existing hardware implementation. Experienced users who speak Verilog might mutate the hardware as they see fit.

The Tiger CPU executes all (16) instructions in one (1) clock cycle. See Verilog/Tiger_opcodes.v for the summary. The data and program counter stacks are register arrays with RPN arguments and results (smells like, but is not Forth). Unique instruction fetch logic frequently saves clock cycles. See doc/instruction_fetch.txt for the commentary.

Tigerasm macros and procedures provide additional (multi-clock) operators. Flagship examples are in lib/fft.py and apps/fft_test.py. A simple example is in apps/hello.py.

A minimal DDE to use TigerSBC as-is requires:
* TigerSBC_yyyy_mm_dd.zip
* a Lattice iCE40-HX8K Breakout Board and included USB cable, and a reset switch (see doc/reset.txt)
* a text editor (e.g. Notepad++)
* Python3 for the Tiger assembler
* a serial terminal emulator with raw file send capability for communication via USB/UART at 115200,8,n,1 (e.g. Tera Term)
* Lattice Semiconductors Diamond to burn the existing FPGA configuration (pre-generated by iCEcube2 on the author's host)

A full DDE to create your own hardware mutations also requires:
* Lattice Semiconductors iCEcube2 for FPGA design
* Icarus Verilog for new module design and simulation

Getting started (Win10 example, Linux translations are straightforward):
0) Unzip TigerSBC_yyyy_mm_dd.zip to your desktop and study doc/overview.html (this file).
1) Obtain the requisite hardware and install the requisite software (punt to vendor doc).
2) Rename asm.cmd.txt to asm.cmd.
3) Rename sim/ivsim.cmd.txt to sim/ivsim.cmd.
4) Connect your board (with closed reset switch connected on J2) via USB. Be curious about which COMx the OS decided to assign.
5) Launch Diamond to burn your board as a TigerSBC with the USB/UART app loader:
     select Create a new blank project, click OK
     under the Device Family heading, select iCE40
     under the Device heading, select iCE40HX8K
     under the Operation heading
       select Access mode: SPI Flash Programming
       select Programming file: FPGAburn/TigerSBC_bitmap.bin
       click OK
     click the Program icon
       if failure, try hot-switching to another USB physical connection and retry (this happens if you have more than 1 board)
       on success, quit Diamond without saving the configuration
6) Launch a command prompt and enter these lines to test the assembler:
     cd Desktop/TigerSBC
     asm apps/hello.py
     save_app('apps/hello.app')
     (optional: investigate the suggested Python3 amenities)
     exit()
7) Launch the serial terminal emulator, configured 115200,8,n,1 on the currently-assigned COM port:
     close the reset switch
     open the reset switch, you should see
       Tiger is ready to load...
     raw file send apps/hello.app
     you should now see:
       Tiger is ready to load...done
       Hello, world!
     the red led D7 on the board should be blinking
For hints on writing your own apps, see FPGAburn/appload.py, lib/*.py, apps/*.py, and Tigerasm.py.

Tigerasm.py defines a 2-pass assembler that reads in source scripts via the include('filename') core procedure. In the first pass, new symbols and (explicit) forward references are collected. In the second pass, the final object code image is generated, ready to be saved to disk as an app (or a hex) file.

Although based on Python3, indentation in Tigerasm source is purely cosmetic. The examples in this snapshot reflect the author's preferred style.

All Tigerasm symbols are global and must be unique. The order of encounter in source is important. If an error occurs, inspect _includes_ to see the list of included source files. The last file in _includes_ is where the error was detected, but not necessarily the root cause. Python3 dir() and globals() list the known symbols for further inspection. Tigerasm dump_ram(start_adr, end_adr) shows raw hexadecimal object code and data.

Typical Tigerasm libs and apps inherit the following host interface procedures from FPGAburn/appload.py:
  lbl('rx') # -> d
  # await zero-extended 8 lsbs from USB/UART

  lbl('tx') # d ->
  # transmit 8 lsbs of d to USB/UART

  lbl('tx_ascii') # adr ->
  # transmit a zero-terminated ascii string to USB/UART
Those interested in Verilog will find hints in Verilog/*.v. Edit ram.v to correct the absolute reference to FPGAburn/ram.hex (the USB/UART app loader initial memory image). iCEcube2 might then be used to build a new TigerSBC project for the board. (Arcana: this snapshot required using the Synthesis Tool: Synplify Pro option.) Hardware mutations require followup changes to Verilog/TigerSBC.pcf and the io addresses defined in Tigerasm.py.

To try the Icarus Verilog simulator, launch a command prompt and enter these lines:
  cd Desktop/TigerSBC/sim
  ivsim spi
The simulation display was also saved to spi.log for posterity, try:
  copy spi.log con
For further consideration:
This single-core implementation left most of the iCE40-HX8K FPGA resources available.
Future mutations might explore parallel execution of multiple cpu+ram cores and their io interfaces.

Have fun being in the driver's seat!
Myron!Plichota@at#gmail$dot%com