README.md

QNICE-FPGA 16-bit System-on-a-Chip

What is QNICE-FPGA?

QNICE-FPGA is a 16-bit computer system build as a fully-fledged system-on-a-chip in portable VHDL on an FPGA. Specifications:

• 16-bit QNICE CPU featuring 16 registers, 8 of them in 256 register banks (learn more in qnice_intro.pdf)
• 32k words ROM (64kB)
• 32k words RAM (64kB)
• UART 115,200 baud, 8-N-1, CTS
• VGA 80x40 character textmode display (640x480 resolution)
• PS/2 keyboard support (mapped to USB on the Nexys 4 DDR)
• SD Card and FAT32 support (microSD card on the Nexys 4 DDR)
• 4-digit 7-segment display
• 16 hardware toggle switches

The main purpose of QNICE-FPGA is learning, teaching and having fun.

Platforms

Due to the portable nature of the way this project has been developed, QNICE-FPGA is able to run on any sufficiently powerful FPGA platform. Additionally, there is an emulator available for macOS, Linux and WebGL.

Out of the box, this repository contains support for the Nexys4 DDR and Nexys A7 development boards as well as for the MEGA65.

Nexys4 DDR and Nexys A7	MEGA65

Getting Started

If you do have FPGA hardware, then read on to learn how to get started. If you don't, then you might want to use the emulator to experience QNICE: Try it online or have a look at emulator/README.md to learn how to build and run your own emulator.

Get started using actual FPGA hardware:

• Clone GitHub repo: Make sure you have git installed on your computer, open a Terminal or Command Line. We will automatically create a subdirectory called QNICE-FPGA, so navigate to an appropriate folder. Use this command to clone the master branch of QNICE-FPGA, as the master branch always contains the latest stable version: git clone https://github.com/sy2002/QNICE-FPGA.git (Hint: It is important, that you clone the repository instead of just downloading it as a ZIP. The reason is, that some build scripts rely on the fact, that there is an underlying git repository.)

• Hardware: Currently, we develop QNICE-FPGA on a Nexys 4 DDR development board. Nexys updated and renamed it to Nexys A7. So, if you own one of those, the fastest way of getting started is to download the bitstream file dist_kit/bin/QNICE-V16.bit on a microSD card or an USB stick, insert it into the Nexys board and set the jumpers to read the FPGA configuration from the SD card or USB stick. Do not copy more than one *.bit file on the SD card, i.e. do not copy dist_kit/bin/QTRIS-V16.bit, yet.

  Do empty the "Recycle Bin" or similar of your host OS between two *.bit copies, so that the Nexys board does not accidentally read the *.bit from your trash instead of the recent one.

  If you have a MEGA65, then you can directly use the Core files .cor in dist_kit/bin, as described in hw/README.md.

• If you do not own a Nexys 4 DDR or A7 board or if you want to synthesize the FPGA configuration bitstream by yourself, then go to the hardware folder hw. It contains the FPGA, board and toolchain (IDE) specific files. QNICE-FPGA has been designed to be portable. Have a look at hw/README.md to learn more.

• Attach an "old" USB keyboard supporting boot mode to the board and attach a VGA monitor. Attach the USB cable to your desktop computer, so that you can setup a serial (terminal) connection between the desktop and the FPGA. (The file doc/constraints.txt contains a list of known-to-work USB keyboards.)

• On your host computer: Open a command line and head to the root folder of the QNICE-FPGA GIT repository.

• Compile the toolchain: You need to have the GNU compiler toolchain installed, particularly gcc and make will be used. Open a terminal in the QNICE root folder. Enter the following (it is important, that you cd into the folder):

  cd tools
  ./make-toolchain.sh
  

  You will be asked several questions. Answer them using the default answers by pressing Enter instead of answering manually by choosing y or n. When done, cd .. back to the QNICE root folder.

• Compile the mandelbrot demo by entering assembler/asm demos/mandel.asm.

• On macOS and if you have xclip installed also on Linux, you now have an ASCII file in the clipboard/pasteboard that starts with the line 0xA000 0x0F80. Alternatively, you can manually copy the file demos/mandel.out into your clipboard/pasteboard.

• Open a serial terminal program, configure it as 115,200 baud, 8-N-1, CTS ON, attach the QNICE-FPGA, turn it on, after the bitstream loaded from the SD card, connect the terminal program to the serial interface of the FPGA and press the reset button. You should see a welcome message and the QMON> prompt in your terminal program's window.

• Enter M then L there. You should see something like "Memory/Load".

• Paste the demos/mandel.out file to your terminal program's window. Alternatively, some terminal programs offer a "Send File" command. (If you are using CoolTerm: Please do paste by using CTRL+V on Windows or on a Mac by using CMD+V, because using the "Paste" menu command that is available via the context menu is not always working properly, when it comes to sending data.)

• Press CTRL+E to leave the memory loading routine.

• Enter C then R and then A000 in the terminal window. You should now see a Mandelbrot output similar to the above-mentioned screenshot in your serial terminal window.

• Now set the toggle switches #0 and #1 to '1' (on the Nexys 4 DDR board, these are the two rightmost switches). Press the reset button. STDIN/STDOUT are now routed from the serial terminal to the PS2/USB keyboard and to the VGA screen.

• A reset does not clear the memory, so enter C and then R and then A000 again. Done! You now should see the same mandelbrot on your VGA screen as shown in the above-mentioned screenshot. Use cursor keys and page up/down keys to scroll.

Using the File System

• QNICE-FPGA supports SD Cards (microSD Cards on the Nexys 4 DDR), that are formatted using FAT32. Make sure that you read the file doc/constraints.txt to understand what works and what does not.

• Copy the folder qbin from the QNICE-FPGA root folder to your SD Card. It contains some nice demo programs in the directly loadable .out file format.

• In the Monitor, enter F and then D to browse a directory.

• Enter F and then C and then enter /qbin to change into the qbin folder that you copied (in case you copied it to the root folder of the SD Card, otherwise enter the right path and use / as a delimiter for subfolders).

• Enter F and then R and then enter adventure.out to load and run a small text adventure.

• Browse the qbin folder using F and D for more .out files, which are QNICE demos. Particularly nice examples are:

  • q-tris.out Tetris clone for QNICE-FPGA, VGA and USB keyboard mandatory
  • sierpinski.out Draws Sierpinski fractals on UART or VGA
  • ttt2.out Tic-Tac-Toe on UART or VGA
  • wolfram.out Draws cellular automata according to Wolfram's New Kind of Science

Q-TRIS

Q-TRIS is a Tetris clone and the first game ever developed for QNICE-FPGA. The rules of the game are very close to the "official" Tetris rules as they can be found on http://tetris.wikia.com/wiki/Tetris_Guideline.

Clearing a larger amount of lines at once (e.g. Double, Triple, Q-TRIS) leads to much higher scores. Clearing a certain treshold of lines leads to the next level. The game speed increases from level to level. If you clear 1.000 lines, then you win the game.

Q-TRIS uses the PS2/USB keyboard and VGA, no matter how STDIN/STDOUT are routed. All speed calculations are based on a 50 MHz CPU that is equal to the CPU revision contained in release V1.4.

Have a look at the current highscore in doc/demos/q-tris-highscore.txt.

The game can run stand-alone, i.e. instead of the Monitor as the "ROM" for the QNICE-FPGA: Just use dist_kit/bin/QTRIS-V16.bit instead of the above-mentioned dist_kit/bin/QNICE-V16.bit. Or, you can run it regularly as an app within the Monitor environment:

• If you copied the qbin folder on your SD Card, you can load and run it directly from the Monitor by entering F R and then /qbin/q-tris.out.

• Alternately, you can open a command line, head to the root folder of QNICE-FPGA and enter this sequence to compile it:

  cd demos
  ../assembler/asm q-tris.asm
  

  Transfer the resulting q-tris.out via your terminal program using Monitor's M L command sequence and start Q-TRIS using C R and the address 8000.

Memory map

The QNICE CPU has a 16-bit address bus and a 16-bit data bus. Each value of the memory address bus addresses an entire 16-bit word. There is no byte-level access. So the total memory area addressable by the QNICE CPU is 64 kWords = 128 kBytes.

In the QNICE system the following simple memory map is used:

Address	Use
0000 - 7FFF	ROM (32 kW = 64 kB)
8000 - FEFF	RAM (32 kW = 64 kB)
FF00 - FFFF	Memory Mapped I/O devices

I/O devices

The I/O memory area is divided into chunks of 8 words, leading to a total of 32 possible I/O devices.

Address	Use
FF00 - FF07	Fundamental I/O (switches, TIL, keyboard)
FF08 - FF0F	System Counters (cycles and instructions)
FF10 - FF17	UART
FF18 - FF1F	EAE
FF20 - FF27	SD CARD
FF28 - FF2F	Timers
FF30 - FF37	VGA
FF38 - FF3F	VGA
FF40 - FFEF	Reserved
FFF0 - FFFF	HyperRAM (MEGA65)

The registers for the individual I/O devices are described in the assembler header file monitor/sysdef.asm.

Programming in Assembler

• Read the Intro and have a look at the Programming Card.

• The dist_kit folder contains important include files, that contain command shortcuts (RET, NOP, SYSCALL), register short names (PC, SR, SP), addresses for memory mapped I/O of peripheral devices and commonly used constants.

• You can choose between two assemblers: The native QNICE assembler located in the folder assembler and the VASM assembler, which is a part of the VBCC toolchain and which is located in c/vasm (source code) and in c/vbcc/bin (executable binary).

• Native QNICE assembler:

  • A typical assembler program starts with the following sequence that first includes the above-mentioned include file sysdef.asm plus the definition file of the "operating system" functions monitor.def. Then the program's start address is set to 0x8000, which is the first address in RAM.

    #include "../dist_kit/sysdef.asm"
    #include "../dist_kit/monitor.def"
    .ORG    0x8000
    

  • You can use any other address greater or equal to 0x8000 for your program. test_programs/mandel.asm for example uses 0xA000. Make sure that you leave enough room for the stack, which grows from top to bottom.

  • The folder test_programs contains a wealth of examples. You might want to start with hello.asm, which combines the classical "Hello World!" example with some more advanced things like using "operating system" functions and sub routines.

• VASM assembler:

  • Each time you open a new command line (terminal) window, make sure, that you go to the folder "c" and enter source setenv.source, which sets up the right path and environment variables.

  • In your command line, navigate to c/test_programs.

  • Enter qvasm vasm_test.asm. Use the M L mechanism to transfer the resulting vasm_test.out to the RAM of QNICE. Run the program using C Rand then 8000.

  • VASM has another syntax than the native QNICE assembler, so you need to use other include files. Have a look at dist_kit/README.md for more details.

Programming in C

QNICE also features a fully-fledged C programming environment. This is how you are getting started:

• The vbcc toolchain is automatically build, when you follow the above-mentioned "Getting Started" guide and run make-toolchain.sh.

• Open a terminal and from the QNICE root folder enter cd c.

• Let's compile a small shell, that can be used to browse the microSD Card of the FPGA board. Enter the following commands:

  source setenv.source
  cd test_programs
  qvc shell.c -c99
  

• Just as described above in "Getting Started", on macOS you now have the excutable in your clipboard so that you can use the M L Monitor command to load the shell. On other operating systems you need to copy shell.out manually to your clipboard and then transfer it using the M L Monitor command.

• Run the shell using C R 8000.

• Browse the microSD Card using dir, cd, cat and cathex commands. Exit the shell using exit.

• Important hint: You either need to run source setenv.source each time you open a new terminal when you want to work with C - or - you need to add the paths and the enviornment variables in your shell preferences, so that they are being set automatically.

• Switch from ANSI-C to C99 using the -c99 command line switch.

• Standard C Library: When using the qvc shell script, located in the folder c/qnice and to which source setenv.source automatically sets up a path, all the include and library paths are automatically set correctly, so that you can just work with the Standard C Library as you would expect it. For example, have a look at fread_basic.c, which shows how to read files and some printf examples. (Make sure you run fread_basic.out while being in the folder /qbin, because only there are the text files needed by the program.)

• Additionally and sometimes alternatively to the Standard C Library, you might want to use the "operating system" library aka the Monitor library. All include and library paths are set, so just include qmon.h for getting started. You find it in c/qnice/monitor-lib/include. The above-mentioned shell.c is an example of how to read files without using the Standard C library but by directly using Monitor functions.

Documentation

If you are new to QNICE-FPGA, then reading the documentation in the following order is recommended:

1. Introduction to the QNICE Instruction Set Architecture

2. Hardware: Description of supported hardware platforms, how to build, and guides for porting to other platforms

3. Overview of directory structure and available documentation as well as QNICE-FPGA basics such as STDIN/STDOUT routing, file transfer mechanisms and platform specifics

4. Emulator and mounting FAT32 devices

5. Constraints

6. Programming Best Practices

7. Programming Card

Acknowledgements

• sy2002: Creator and maintainer of QNICE-FPGA: hardware development (VHDL), FAT32 library, additional Monitor libraries and functions, Q-TRIS, additional QNICE specific vbcc toolchain, VGA and WebAssembly versions of the emulator, MEGA65 port.

• vaxman: Inventor of the QNICE ISA: system architect, assembler, original POSIX version of the emulator, Monitor and Monitor libraries, tools.

• Volker Barthelmann: vbcc compiler system, QNICE specific vbcc backend incl. standard C library.

• MJoergen: Performance improvements and bugfixes, CPU functional test suite.