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...
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:
The source code is available here:
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:
- To change memory:
poke byte 8000000 1 2 3 4
- To download some data via XMODEM:
- To upload some data via XMODEM:
- 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:
- To start execution at a particular address:
- To get generic help:
piface uses an internal VFS;
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
sd: files refer to files on a FAT filesystem on the SD
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
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
recv command, you'll then
issue the appropriate local command and the transfer will proceed.
^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
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?
What's the license?
Calculon is distributable under the terms of the Simplified BSD License.