Ion - MIPS(tm) compatible CPU

Quick Start

In order to use any of the software samples, you would need to install a MIPS toolchain on your computer. This may or may not be too much trouble if all you want to do is examine the core and play a bit with it.

In order to save you that trouble, the project ships with a precompiled, pregenerated demo, a SD-card bootloader. Pregenerated in this context means that all the VHDL configuration packages that contain the application object code, among other things, are already included in the SVN repository, ready to be used.
(The documentation explains in some detail how the core uses configuration packages to initialize its internal memories, section 2.2).


This demo can be synthesized and run on a DE-1 board even if you don't have a MIPS toolchain installed; the files included in the project as checked out should be enough. Here's how to use the demo:

Quick Start

1.	Synthesize the bootloader demo as explained in section 9.1 of the project document.
2.	Load the bitfille on the DE-1 board that I assume you have on hand.
3.	Connect a 19200/8/N/1 terminal to the serial interface.
4.	Copy file '/src/sdboot/code.bin' to the root directory of a FAT32 SD card, plug the card on the DE-1.
5.	Reset the board (leftmost switch 9, usually, see the source for the top entity).
6.	The binary will take a few seconds to load (SD SPI interface is bitbanged and slow).
7.	You should see something like the console dump displayed below -- the Adventure prompt.

Well, at least this is how it should go. I have only tested this on my DE-1 and my SD cards. If anyone tries this and finds trouble, let me know about it!

The project document includes set up instructions for Altera's Quartus-2, easily extrapolable to your synthesis tool of choice -- see section 9.1. And the DE-1 demo top entity is very easy to modify for other boards (it's little more than a wrapper around the SoC entity).

Software Samples

The project includes a number of 'software samples': small programs meant to demonstrate the usage of the core and validate the installation.

These software samples typically include one or more C or assembler source files and a makefile. In order to use them, you need to have a MIPS cross-toolchain installed in your computer. All the code samples have been tried with the CodeSourcery MIPS toolchain for Windows, that can be freely downloaded from CodeSourcery's site. They have occasionally been tried with the BuildRoot toolchain for linux -- the makefiles are prepared for both.

All the code samples can be simulated in software (with the MIPS simulator provided with this project), can be simulated in a VHDL test bench (Modelsim 6.3 only) and can be executed on a development board.

The development board targeted in all code samples is Terasic's 'DE-1' cyclone-II development board -- pin location file included.

The project documentation (/doc/ion_project.pdf) includes set up instructions and some directions for porting the demos to other hardware platforms.



The project will eventually include a real test bench and some common benchmark (Dhrystone 2.1). This will be the next demo.

SD Bootloader

As of revision 250, the project includes a bootloader for the ION SoC (directory '/src/sdboot'). This program is little more than an adaption of one of the sample programs included with the FatFs library.

This bootloader runs from BRAM and will load a binary file 'code.bin' from an SD card onto RAM at address 0x00000000 (16-bit SRAM in the DE-1 board), then jump to zero.

This program uses a port of FatFs by Elm-Chan. It has been modified to work on a bit banged SD interface that has been implemented on the DE-1 demo top entity file using the SoC module GPIO ports.

In the same directory you will find a precompiled version of Adventure, suitably renamed 'code.bin', ready to be bootloaded from a FAT32 SD card. Beware that some recent SD cards come in a format that FatFs cannot recognize, you may need to reformat your card. I advise using the oldest, smallest card you can get.


Programs meant to run from RAM have to use a separate link script ('/src/common/xram.lds'). You can see the makefile for the Adventure demo for an usage example -- Adventure can be buil to run from flash or from RAM with target 'sd'.

Adventure demo

One of the software demos included is a port of the classic Adventure game, by Will Crowther and Don Woods.


The documentation includes some usage instructions to help set up this demo. The only major difference with the 'Hello World' demo is that the code is too large to be run from internal BRAM and has to be run from external flash or from RAM, via an SD card.


To run the program from flash, you have to load the program binary onto the DE-1 board flash, using the tools supplied with the board -- explained in the dev board documentation.

In order to run the demo from RAM, first you would have to build Adventure using make target 'sd' (make sd). This will produce a binary file 'code'bin' that you then have to copy to the root directory of an SD card.
Then you have to synthesize and load the sdloader demo and run it.

In order to save you all that trouble, a precompiled copy of the adventure binary 'code.bin' is included in the sdboot directory. Since the project also includes the pregenerated object code package needed to synthesize the boot loader, all you need is to synthesize the sources and plug the SD card in, as explained in the 'quick start' paragraph above :)

After connecting a 19200/8/N1 terminal, this is what you'll see upon reset (assuming you run the demo from flash):






If you choose to use the auto-walkthrough, the program will run itself for about 250 turns and leave you at the well house, having scored 259 out of 430 points. The autowalkthrough was made by me and I have been unable to progress further than that in the game :)


The source is a port of Don Woods' original C version, which in turn is a straight port of his original Fortran -- it is not for the faint of hearth. All I have done is modify it so that instead of relying on files, it uses hardcoded tables. I have also removed the random element from the game, in order to simplify the tests.
By the way, since the program has no access to a file system, you can't save your progress...


The demo runs from flash and uses the SRAM extensively, all while using the cache, so the execution of the program is a good confidence builder. Of course this is not as good as a real test bench, but when you reach the maze of twisty little passages, you know you have a computer :)

Back in the minicomputer days there was a well known computer company that would run Adventure on all new minis as part of its test suite; this project has reached that milestone, at least.
Running Adventure in a computer built by myself is something I've always wanted to do; mission accomplished :)

Hello World!

This is your typical 'Hello World!' program, built to run from internal BRAM and use no board resources external to the FPGA. The project document includes set up instructions for Altera's Quartus-2, easily extrapolable to your synthesis tool of choice -- see section 9.1.


All you need is a DE-1 board and a terminal (19200/8/N/1); and all this demo does is display the compilation date and the "Hello World!" message.

This program runs entirely from internal BRAM, which would be a waste in a real application but makes it easier to port to other hardware platforms.


With the availability of the bootloader demo from revision 250 onwards, the 'Hello World' demo has become somewhat redundant...