ZX Spectrum emulator !

BitboZx

Hi, here is the first release of the BitBoxZx, a 48k ZX Spectrum emulator !

Simple modes

Some have expressed the interest for simple modes for the Bitbox. An recent commit is providing such mode , on top of the standard kernel.

The so-called simple modes are called like this because they provide a frame buffer interface, so the application programmer will only have to write bits and bytes to the video memory - much like it's done on PC. So the interface is a vram buch of memory and a color palette (because the tradeoff is a reduced palette or resolution)

There are two examples in the bitbox SDK (one of them below), but generally you'll need to define a simple makefile variable VGA_SIMPLE_MODE=X with the given mode and include the bitbox.mk standard makefile.

(Yes it's currently defined at compile time - if your program needs to switch between two modes at runtime, it might be time to switch to a standard kernel / engine - it's not difficult !)

Beat Blocks beats hit Bitbox !

New program ! A Beat Box project on the Bitbox. Used to make rhythms with drums samples, you know.

It sports 8 tracks with two possible instruments on each of them (16 different instruments max), looped on a 16 beats track.

It is controlled by a USB gamepad or a keyboard, and can be used live (ie changing patterns or editing them)

It works by playing and modifying patterns on a mod file on the SD card (samples can be bigger than the bitbox memory), so you can create drumkits quite easily with a Tracker and play/modify it on the bitbox.

Of course, it's free and open sourced ! See sources and graphics on GitHub

developing for bitbox under windows

Even if I'm personally working under linux, it is quite possible to develop for bitbox under windows.

The following article / page is a reference for it, and will be updated accordingly. Also, if there is any part missing, please tell it !

A very thorough reference can be found by example there : http://www.jann.cc/2013/10/10/embedded_development_with_open_source_tools_on_windows.html#install-the-gcc-arm-embedded-toolchain

Most of the current guide is taken from there.

It targets development on a cortex-m4 chip so it's quite similar and adds a ton of optional software which can be very useful. The proposed method is quite barebones (or light), because, well I tend to prefer lighter solutions, but integration with eclipse could be done I'm sure.

Alternatively, DIYDSP has an page with instructions to setup a linux virtual machine suitable for stm32 development, as well as various other tips.

Playing TitanFall and Super Mario 3D World on the bitbox

 Well, playing a video of Titanfall on a Bitbox, of course playing a demanding PC / nextgen console videogame is out of reach :) But OK, then, can we have video on the bitbox ?

Full motion video on a very small hardware like the bitbox poses some interesting optimization issues and challenges. That's the kind of challenges you're faced with when you've got a few k on RAM - too few to store the image you're showing entirely- and 180MHz to generate the content and synthetise you VGA signal by software ...

Can we made nice cinematic cutscenes for the game, i.e. full motion video on the bitbox ? Can we make it 4K 3D video ? Well, no (What did you think ? 1080p50 with an Arduino ?)

But ... how far can we go ?

Uploading to the bitbox, part II (bootloaders)

Bitbox has now a 2-stage bootloader : here is how it works.
Game programmers shall not worry about this since it's automatically taken care of by standard building scripts.

The principle is the following : a small first bootloader loads a second, more featureful bootloader to RAM and runs it. The second bootloader loads a program and writes it to flash.

Devices API design

Revision 1 API

the preceding API for gamepads on rev1 was very simple : in fact it was only a halfword (!), representing the bits of each button on the SNES gamepad. This was simple, convenient and closest to the hardware.

Now with the different class of devices that can be used and the fact the USB HID is used, I think we will need to have a different API.

BitBoy : a gameboy emulator for bitbox !

BitBoy is a port from the gnuboy emulator heavily modified to fit in the Bitbox console.

The Gameboy emulator successfully emulates several games and homebrews for this venerable console.

Screenshots

Screenshots of the emulator.

The menu to select the on-chip games


NB :  Emulators are standard SDL games built with all bitbox programs running on the bitbox kernel with no modification of the game source code as the normal build of any game.
Meh, an emulator. But not only, it runs also on the real hardware : 

Available features

• Based on (heavily modified to fit in memory constraints : 1MB incl. games & vga generation+ 192k RAM !) gnuboy emulator, as GNU GPL code available on github
• Working Commercial and homebrew GameBoy titles (public domain homebrews or rightfully licensed games !)
• 4 color palette B&W display, with custom palettes (fixed colors by game) to colorize the games.
• Working on rev1 hardware including gamepad
• Several ROMs can be embedded in on-chip flash (up to 1MB), with a selection menu

Source code

Code (including original very good gnuboy emulator heavily modified) is available here : https://github.com/makapuf/bitboy

Making of 

The adaptation of gnuboy to bitboy consisted of : 

• mapping the inputs to bitboy rev1 gamepad
• rewriting the main loop & main function (from command line to bitbox kernel frame interface), remapping time-relating functions.
• interfacing the sound callbacks of bitbox to gnuboy engine generation.
• removing / disabling all file related functions. Some could be re enabled to save some backup RAM to SDCard by example or load data cart from SD Card.
• rewriting all the display code, not to fit bitbox display model -this adaptation was done quite simply by blitting a virtual framebuffer, but to make it faster and not depend on huge (100k) in-memory precomputed tables. Now only B&W GB has been done, but color could be done.
• writing a blitter for the gnuboy pseudo-vram to Bitbox graphical kernel. Maybe this step (and the 2 VRAM buffers) can be skipped and real Bitbox lines be generated on the fly by the new gnuboy, faking Gnuboy v-syncs from the real Vsync bitbox interrupts.
• modifying the memory mapper to use bitbox flash / Ram & mapping some RAM data (2 VRAM buffers) to ccm ram in order to save place in sram, disabling many functions like rom compression, battery-powered ram.
• making a menu loader of ROMs in Flash, replacing the file loader. This is currently done by embedding roms as C data. Some quick "compression" could be done. (removing zeros or const data at end of pages)
• menu selection of ROM as several ROMs can be placed in flash
• linking ROM to custom palettes : Color games are not supported yet (colorized games using custom palettes are supported however), but given the size of those color games, they often wouldn't be able to be stored on the box anyway.
• cutting color gameboy features to simplify development and lower memory requirements (standard GB has 8k, GBC has 32k of RAM, which could fit in CCM RAM, 16k VRAM vs 8k, and much larger games - often starting at 1MB).

Future work

Many things could be done (contribs welcome ! ) to further development :

• Some graphical glitches on games (or frankly ugly artifacts), yes, they exist.
• Sound has been neglected, ie should work, has worked, but now doesn't.
• Loading ROMs from SDCard to RAM (64k max cartridges) - or even flash programming from uSD ?
• Saving games states as  SDCard files
• HiDef Scale2x type graphical output ?
• Support of GBC seems doable, maybe in a future release, this would include working around memory limitations and reimplementing color GB features in graphical layer, on the fly loading some pages in RAM from SD to handle large ROMs?
• Maybe adapting this emulator or graphical engine for NES ?

An efficient scanline blitting algorithm

For the bitbox kernel, we need to have a fast graphical objects blitting library, since we will often have the same needs. Blitting from low Z to high Z of a fixed tiled background + overdrawing small sprites (to keep the 5k cycles budget) only goes so far, because as we are overdrawing pixels, we will be hitting the 5k cycles / lines pretty soon.

We will sum up the needs of such a library and propose an algorithm.

Tutorial : blitting graphics

(this is the second part of the tutorial about making a Fire game for the bitbox)

If you need basic information about writing software for the bitbox console, please read this introductory tutorial 

Tutorial : developing for Bitbox (the basics)

We're going over the course of this tutorial to program and build a simple program for the bitbox console on ubuntu. I'm trying it on a 13.04 Ubuntu, so adapt accordingly.

For windows, there is a small guide on the blog, you can use is in parallel with this page.

storing pixels

So as output is in theory solved by having the DMA send a lines of 16bits halfwords, we need to focus on the storage and memory.
As with horizontal resolution, different choices can lead to different modes, but I’ll show some generic principles, you can adapt and create your own mode. Or reuse one.
There are several general ways to store pixels in order to output them.


The first, direct approach is a frame buffer.

A frame buffer is a chunk of memory storing pixels exactly as they will be output, so that you output to the screen what you’ve got in memory. Sometimes, things can be a little messier with color planes (i.e. one framebuffer per Rn G and B) and banks.

What resolution can we use if we want to use it with the current memory size ?

We can, of course use Flash for static images. But then, only using static images is quite restrictive for a game console.

Let’s pretend use 2 bytes per pixel. We have 192kb of memory on the stm32f4, but we can only use 128 as the other 64k is core coupled memory and won’t be seen by the DMA. So we can store 64k pixels (half that for 16 bits).

For a 4/3 aspect ratio, that’s sqrt(3/4*64*1024) =  221 lines.

We thus could store one screen of  294x221 pixels, or two screens of (only!) 221x147 if we want double buffering !

Which begins to enter the domain of lame for a 32bits game console.

For a better resolution of 640x480 @ 12bpp, we would need 640x480x2 = 614 400 bytes , which is about 5 times the RAM and more than half the Flash size.

For this, we need to compress the image we want in RAM and decompress it at 25 MHz pixel clock. 

So we will need some translation functions that prepares a line of pixels for the current line from the frame buffer while the DMA outputs a line buffer. and then exchange those front and back buffers, exactly timed at 31 000 times per second.

Needless to say we won’t use jpeg.

Note that we need this compressed data to be manipulated by our game, so PNG and the like (really LZ77/LZW in memory pixel storage) will be too CPU intensive also, as well as impractical to manipulate for non static images.


First we can use less bits per pixel by using indexed colors. By example, we could use a 256 colors palette using 1 byte per pixel giving nice colors and practical output. See the article about it on wikipedia, it’s well explained and has nice parrot pictures. Arrr !
The display function will translate the pixel color ids to a table of pixel colors and store it in the buffer. Generally it’s done by hardware by means of a RAMDAC (in : pixel ids, out : VGA signal, inside : some RAM for the palette / a DAC, hence, a ramdac. See wikipedia article.) but those chips are becoming hard to find/expensive and that’s an additional chip and that would force us using indexed color, so no).


Is it feasible by software ?

Let’s calculate how much time lines per seconds we could output.
Let’s consider a naive pixel / byte algorithm, not using 32bit word-aware method.

• Excluding loops housekeeping, that’s around 6 clocks per pixel IIUC the ARM reference latency roughly
• 1 read per pixel for the pixelID, 
• 1 read to read the palette color from memory 
• 1 store per pixel to the buffer. 

So the STM32 @ 168M can output 168e6/(6*640) = 43750 lines/sec. That’ more than 31kHz horizontal refresh rate so that’s possible (note that we include hblank periods) !

(taking 70% of the CPU power - not counting V blank periods where we’re not outputting video, compared to None when we’re using a framebuffer. That’s a serious memory/cpu tradeoff, but if we can do better, having 50% of a 168MHz CPU isn’t so bad after all).

Note that if we can use 16 colors palette, that’s half the RAM also (4bits pp) or in 4 colors that’s 2bpp (with 1/4 less pixel reads and keeping the whole palette in registers so no palette reads … that with combined word writes can make it much faster).

Note also that with a palette you can manipulate the palette individually from the pixel data, so you can do fadeouts quite easily by switching palettes (not for free but because you’re already doing the translation work).

But that is quite expensive, and another method will be used first.


Tiled backgrounds
Another technique, often used for backgrounds and very similar to text mode goes further : instead of having a palette of pixels, lets have a palette of sub-images, composed to make a bigger image : one for a tree top, one for a bottom tree, one for grass : repeat many times and you have a big forest with 3 small images + a map.

It’s similar to text modes in that instead of doing it with letters (buffer of characters on screen + small bitmaps representing letters), you do it with color images (which can be letters).

Nice editors exist for tiled data, and we will use one to compose our images. 

Storing such an image need storing tiles +  a tilemap referencing your elements. The bigger the tile, the less bits you need to store the tilemap, the more you need to store the tiles. Note that tiles can be stored with a palette also.

Many other choices can be made, and combining them is possible, but we have few cycles to spare for now, so let's consider only tiles for now.