Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
Constraints of QNICE-FPGA
=========================
Today's hardware landscape is extremely diverse. As a relaxed hobbyist project
QNICE-FPGA is at this time not able to offer a robust support of all
peripheral devices such as USB keyboards and SD cards on the market.
Furthermore, there are also still constraints in our software stack.
We are working to resolve as many constraints as possible over time.
**Constraint categories:**
HARDWARE:
* [SD card](#sd-card)
* [USB keyboard](#usb-keyboard)
* [VGA](#vga)
* [MEGA65](#mega65)
TOOLCHAIN:
* [Windows](#windows)
* [Serial port software](#serial-port)
* [ISE](#ise)
* [Emulator](#emulator)
* [C programming via VBCC](#VBCC)
QNICE-FPGA SYSTEM:
* [Encoding / Languages / Fonts](#encoding--languages--fonts)
Hardware
--------
### SD Card
* We tested microSD and microSDHC cards in the built-in card slot using a
Nexys 4 DDR board. Presumably everything also works fine with normal sized
SD cards and miniSD cards on other boards and other readers.
* All SD V1 and SD V2 cards are working. We tested capacities between
64 MB and 2 GB using also different card brands (Nokia, SanDisk, Transcend).
* When it comes to SDHC cards, i.e. cards larger than 2 GB, the following are
tested as working: SanDisk 32 GB microSDHC Class 4,
Transcend 32 GB microSDHC Class 10, Elegant 32 GB, Verbatim Premium 8 GB,
Kingston 16GB SDHC Class 4, SanDisk Ultra 32 GB microSDHC Class 10,
Intenso 4GB microSDHC Class 4
* NOT WORKING are some cards like SanDisk "Ultra" Class 10 cards (80 MB/sec) or
Kingston Class 10 cards. Use slower cards instead, like
SanDisk's 32 GB Class 4 card. So for summing it up: If you want to be on the
safe side, then use SD cards (no SDHC, no SDXC) with a capacity of a
maximum of 2 GB.
* MBR partition table.
* FAT32 with a 512 byte sector size.
ATTENTION: FAT16 and others are not supported, you probably need to
manually format the SD Card to be sure that you are running with FAT32.
* Maximum 65.535 files per folder.
* File names are ASCII only (no Unicode).
* MAC USERS: Do not use the GUI version of the disk utility, as you cannot
control, if the tool creates FAT16 or FAT32. Use the command line
version of diskutil instead:
`sudo diskutil eraseDisk FAT32 <name> MBRFormat /dev/<devicename>`
Find out <devicename> using "diskutil list". <name> can be chosen
arbitrarily.
### USB Keyboard
When attaching an USB keyboard, be sure to use one that supports the old
**USB boot mode standard**. Not all newer keyboards are compatible. These
keyboards are tested and work:
* Cherry KC 1000
* Logitech Ultra-Flat Y-BP62a
* Tacens Scriba
* VIVANCO 36641 IT-KB USB PS2
* ASUS KU-0902
### VGA
* The display needs to support 640x480 and 640x400 in 60 Hz.
### MEGA65
* The HyperRAM is currently not stable, yet. See the following issues:
- https://github.com/sy2002/QNICE-FPGA/issues/90
- https://github.com/sy2002/QNICE-FPGA/issues/91
* HyperRAM does not synthesize on ISE due to the following not yet fixed
warning. This is why HyperRAM is deactivated on ISE:
```
[Synth 8-5787] Register current_cache_line_update_flags_reg in module
hyperram is clocked by two different clocks in the same process. This may
cause simulation mismatches and synthesis errors. Consider using different
process statements ["QNICE-FPGA/vhdl/hw/MEGA65/drivers/hyperram.vhdl":491]
```
* For the QNICE @ MEGA65 release at hand, we used the very first MEGA65
prototype computer, which has the board revision 2 (MEGA65R2). There were
only a couple of those prototypes produced, so you will probably have a
newer board revision: The first publicly available MEGA65 computer will be
the MEGA65 DevKit with board revision 3 (MEGA65R3). Acording to our current
knowledge R3 will have a different way of producing HDMI output so we
expect that the R2 HDMI output will not work on R3.
Toolchain
---------
### Windows
Currently, we do support **macOS** and **Linux** when it comes to compiling
and running the QNICE-FPGA toolchain. This does not mean, that you could not
get it running under Windows: There are multiple ways what you can do, ranging
from Windows-Subsystem for Linux over things like MinGW to investing some
work to port the build-, data-transformation and run-scripts themselves to
Windows.
Currently, none of the maintainers of QNICE-FPGA uses Windows.
[Contributions](../CONTRIBUTING.md) to facilitate using QNICE-FPGA on Windows,
are very welcome and might range from smaller things like "how-to"
documentation and tutorials to ports of the toolchain.
### Serial port
On Linux, the serial (UART) connection has been tested using the terminal
program `picocom`. However, the packaged version of this program (at least in
Ubuntu) is version 2.2, which is buggy and occasionally drops characters (the
bug report can be found here:
https://bugs.launchpad.net/ubuntu/+source/picocom/+bug/1895521). The solution
in this case is to manually download and compile the latest version (3.1) of
`picocom` from the official source repository:
[https://github.com/npat-efault/picocom](https://github.com/npat-efault/picocom).
Remember to enable hardware flow control (RTS/CTS) when running the terminal
program. With `picocom` the relevant command line parameter is `--flow h`.
On MAC, there are no known problems with the serial port connection.
### ISE
* Using ISE is deprecated. We are still supporting it while accepting
certain constraints.
* The ROMs are too large and waste FPGA resources. When the FPGA is large
enough (such as the Artix-7 used on the Nexys 4 DDR and in the MEGA65),
this is not a problem. On Vivado this was solvable by introducing
dynamic ROM sizes depending on the ROM file that is being loaded,
but on ISE this did not work, so we needed to use `vhdl/block_rom_ise.vhd`
which has a constant ROM size of 8k words (16kB) per ROM.
### Emulator
TODO RELEASE V1.7: REVISIT THIS SECTION, AS THE EMULATOR IS RECEIVING
QUITE SOME CHANGES IN V1.7. ALSO CHECK, IF THE EMULATOR IS ABLE TO EMULATE
SCANLINE INTERRUPTS OR NOT AND DOCUMENT IT HERE.
* The WebAssembly (WASM) emulator does not support the timer interrupt module.
* The emulator does not support the following bits in `VGA$STATE`:
- Bit 7: right now, VGA is always on
- Bit 5: right now, if the HW cursor is on, then it always blinks
- Bit 4: right now, the cursor is always large (i.e. a block)
### VBCC
TODO RELEASE V1.7: REVISIT THIS SECTION DUE TO ISSUE #100
* We are currently on a rather old version of VBCC
#### Standard C Library
* No support for float and double, yet.
* stdin works line buffered and the buffer size is 160 words, i.e. when
pressing DEL or BS you can maximally go back 159 characters. There is no
limit on the amount of characters that can be entered, the only limit is
how "far you can go back" when pressing DEL or BS. If you want to
enlarge the buffer, then you need to compile the standard C library while
defining `QMON_LINEBUFFER_SIZE` to the value you want it to be.
* While the C compiler, linker and assembler of the VBCC toolchain are
open source and therefore included to our distribution package, the
standard C library is not. Therefore you need to contact the author,
if you need the sources. We are delivering a linkable version of the
standard C library, though: `c/vbcc/targets/qnice-mon/lib/libvc.a`
and of course all the header files in `c/vbcc/targets/qnice-mon/include`.
So you are able to work with the standard C library as you would expect
it, even without having the source of the lib itself.
* The heap size is currently set to 4096 words. Short version: It grows
upwards coming from the end of the application and therefore grows towards
the stack which is coming downwards from somewhere near 0xFEFF. Currently
there are no checking mechanisms that check a collision between stack and
heap.
Some more details: For avoiding having a lot of 0x0000 elements in the .out
files, we currently use the so called "unsafe heap" mechanism, which means,
that the heap is basically a pointer to one word after the last word of the
application program itself. Have a look at
`c/qnice/vclib/targets/qnice-mon/libsrc/stdlib/_heap.c` to learn more. In the
standard C library Makefile, which is located at
`c/qnice/vclib/targets/qnice-mon/Makefile` the heap size can be changed by
defining HEAPSIZE.
Currently, we are not having any memory and/or heap
management mechanisms on operating system level, so obtaining "core memory"
currently just means increasing the heap pointer, as you can see here:
`c/qnice/vclib/targets/qnice-mon/libsrc/stdlib/_core.c`
That also means, we cannot free core memory and that means, for avoiding
memory leaks, it is important, that the THRESHOLD defined in the Makefile
is 2 words lower than HEAPSIZE / 4, so in our case as we have 4096 words
of heap, THRESHOLD = (4096 / 4) - 2 = 1022.
For more details about why is that, you need to know details of the malloc
implementation, which is currently not open source (see above).
* If you happen to have access to the standard library source code, then
copy it to `c/vclib` and run the script `c/make-vclib.sh` to compile it.
(Don't forget to enter "source setenv.source" before doing so.) The script
is merging the QNICE specific changes of the standard c library, which
are located at `c/qnice/vclib` with the vanilla version of the c library
and then starts the compilation.
The result, i.e. the binary standard library and the startup code are then
copied to `c/vbcc/targets/qnice-mon/lib`: `libvc.a` and `startup.o`.
QNICE-FPGA System
-----------------
### Encoding / Languages / Fonts
* PS/2 (USB) keyboard: Currently, the monitor switches hardcoded to the
German keyboard layout. Though, the hardware is capable to handle an English
layout also (hw register `IO$KBD_STATE`, bits 2 .. 4). If you have a non-german
keyboard, you might want to change this in monitor/qasm.asm (search for
the string `KBD$LOCALE_DE`).
* No support for UTF-8
* All monitor library functions, including gets and puts, are assuming, that
one character is one byte in size. That means, for example, that if you use
gets to enter the German character "ä" (Umlaut for ae) or
"ß" (Umlaut for ss), the following is happening:
a) On a modern OS like Mac OS or Windows, the default encoding is UTF-8.
So, if you press the "ä" key, while using STDIN=UART on real hardware
using terminal software or on the emulator using the command line of
the OS, the operating system will send the UTF-8 encoded "ä", which are
the following *TWO* bytes: C3 A4.
Obviously, this means that QNICE will store these two bytes within the
string. If you use puts to print this string on a UTF-8 enabled system,
you will see the right character "ä" again, so it kind of feels seamless
for the end user and nearly everything works.
But: If you enter e.g. "ä" and then press Backspace (BS) - as gets is
not aware of UTF-8 - the remaining character in the string is C3, which
will lead to funny effects.
Also, if you entered an "ä" using gets via STDIN=UART/STDOUT=UART, then
everything looks good, as your OS and the resulting terminal emulation
will be aware of UTF-8. But if you then output exactly this string on
STDOUT=VGA, then you will see the two charactes "À", because this is
how the modified "lat9w-12_sy2002" font is encoded in Q-NICE currently.
b) If you entered an "ä" using STDIN=USB, then a German keyboard would
send the code E4, which would be displayed correctly on the STDOUT=VGA
screen as "ä".
But if you used STDIN=USB and STDOUT=UART, then pressing an "ä" or any
other non standard ASCII key will result to displaying wrong characters.
* As a summary, and with the exception of some funny, but not really
dangerous, effects when using Backspace (BS) or DEL, you can already
currently, where no UTF-8 support is there, use non standard characters on
QNICE, as long as you stick either to (STDIN=STDOUT=UART) or to
(STDIN=USB and STDOUT=VGA). As soon as you stard mixing, it is not working
correctly, any more.
* The VGA display uses a slightly modified version of "lat9w"
which is mostly compatible with ISO/IEC 8859-15 as described here:
[https://en.wikipedia.org/wiki/ISO/IEC_8859-15](https://en.wikipedia.org/wiki/ISO/IEC_8859-15).
You can look at the font by browsing this textfile:
vhdl/vga/lat9w-12.txt
b1fb36c56This file is pinned to the selected release. Download the original to open it in your design tool.