What is it?

piface is a very simple but hopefully useful boot monitor for the Raspberry Pi. Unlike most other Raspberry Pi software, it runs directly on the Videocore CPU rather than on the ARM coprocessor. This means you can use it to run Videocore programs directly on the bare metal without having to use the ARM-Videocore APIs.

piface uses the mini-UART as a serial terminal.

Right now piface's feature set is fairly thin as the capabilities of the Videocore side of the Pi are still being investigated, but it supports:

  • uploads and downloads via XMODEM
  • read/write support for SD cards
  • executing code
  • modifying and dumping memory
  • lots of plumbing for more interesting stuff later

Regarding that last, if anyone knows how the MMC interface works, please get in touch...

What's new?

2013-06-21: Version 0.3 released! Added basic read-write SD card support.

2013-06-18: Version 0.2.1 released! Fixed a very embarrassing bug in the compiler startup code which was putting the stack in the wrong place.

2013-06-13: Version 0.2 released! Now with (barely tested) XMODEM receive, so you can send data from the PC to the Pi.

2013-06-07: Version 0.1 released! The first actually useful version. For certain values of useful, of course.

Where can I get it?

Most likely what you want is the precompiled binary:

PiFace's latest release

You can get the most recent version of PiFace from the project download page.

The source code is available here:

PiFace's github repository

Send me pull requests!

piface builds with a special development version of The Amsterdam Compiler Kit, modified to generate (rather crude) Videocore IV machine code. This is easy but not trivial; if you're interested, email me and ask.

How do I use it?

Copy your chosen piface.bin file to bootcode.bin on a FAT formatted SD card. Insert card into Raspberry Pi and apply power. piface runs!

To actually interact with it, you'll need to connect the mini UART on the Pi to a PC. You can find information here. Important note! The mini UART on the Pi is a 3.3V device. If you wire it directly to a PC serial port, you are very likely to explode your Pi. You will need an adapter. I recommend USB serial adapters for this.

Once set up, connect your serial terminal at 115200 baud 8N1, and when you start the Pi you should see:

        PiFace v0.3 (c) 2013 David Given

You can now type commands. Here are some useful ones:

  • To dump memory to the console: dump mem:80000000+200
  • To change memory: poke byte 8000000 1 2 3 4
  • To download some data via XMODEM: send mem:80000000+10000
  • To upload some data via XMODEM: recv mem:60008000
  • To copy data to a file: cp mem:80000000+10000 sd:data.img
  • To copy data from a file: cp sd:data.img mem:60008000
  • To look at the contents of the SD card: ls sd:
  • To start execution at a particular address: go 0
  • To get generic help: help

piface uses an internal VFS; mem: and sd: are supported.

mem: files refer to an arbitrary block of memory, using a filename of the form mem:address+length. You may also use mem:address for unbounded memory regions, but be careful of this (because they're 4GB long and will take a while to dump to the console).

sd: files refer to files on a FAT filesystem on the SD card. (The ls command is useful here.) Most FAT filesystems on LBA partitions should work. Cards are hot-swappable while piface is showing the command line prompt; both SDHC and ordinary SD cards are supported (but probably not MMC cards). The filesystem is writeable --- it hasn't corrupted my cards yet, but you have been warned. Performance is currently pretty lousy and it hasn't had much testing.

If you try to do something to an unmapped memory region, or if you corrupt piface's workspace, piface will let you know by crashing. Power cycle the Pi to reset.


You can use XMODEM to transfer data to/from piface. The details will depend on which terminal emulator you're using. Normally, after issuing the piface send or recv command, you'll then issue the appropriate local command and the transfer will proceed.

If you're using GNU screen, which is my preferred least bad terminal emulator, you can do this by installing the venerable lrzsz package. Then, to send a file, do:

^A :!!! sx -bk file.img

...and to receive a file, do:

^A :!!! rx -bc file.img

(^A means to type a CTRL+A to get the screen's command line.) The parameters are important. -b sets binary mode, which prevents mangled transfers; -k sets 1kB blocks; -c uses 16-bit CRCs (which also prevents mangled transfers).

Technical details

When the Raspberry Pi starts, there's 128kB of RAM at 80000000, which is where piface is loaded. piface then initialises the mini UART but does not attempt to change the PLLs or set up the SDRAM.

The internal boot ROM is mapped at 60000000. There's 0x800 bytes of RAM at 60008000, which is useful for playing with. However, be wary of the area at about 60008000 to 60008048, as this is where the second core's stack lives. While the second core should be idling and unresponsive, I can't guarantee it...

Peripherals are mapped at 7e000000. You can manipulate them with poke if you're really careful. Note that dump always reads bytes.

Why shouldn't I use it?

You cannot do anything useful with piface yet. You cannot do anything useful with the Videocore side of the Raspberry Pi yet. The only purpose that piface has is to make it easier to poke the Videocore to find out how it works. If this is the sort of thing that interests you, then piface is for you. If not, stay well clear (and use the ARM instead).

In addition, piface is very new and is probably riddled with bugs. Find any? Let me know by filing a bug on the GitHub page.

Who wrote it?

I, David Given, wrote it. Got any comments, criticism, cake? Send it to dg@cowlark.com. If there's interest, I'll set up a mailing list.

What's the license?

Calculon is distributable under the terms of the Simplified BSD License.