Raspberry Pi is a trademark of Raspberry Pi Ltd.

If you read this file in an editor you should switch line wrapping on.

Unitest is a multi-function test program for the Circle bare metal environment for the Raspberry Pi. It can be used as a demo of Circle features too.

Normally you need a Git client to get the Unitest source code. Go to the directory where you want to place Unitest on your hard disk and enter:

git clone https://github.com/rsta2/unitest.git unitest
cd unitest
git submodule update --init

This will place the source code in the subdirectory unitest/ and clones the submodule circle into the unitest/circle/ subdirectory.

Unitest uses the Circle bare metal build environment for the Raspberry Pi. You need an appropriate compiler toolchain for ARM processors to build it. Have a look at the Circle README.md file (in circle/) for further information on this (section Building). The build information herein is for Linux hosts only. For building on other hosts you have to adapt some script files. Unitest does currently not build on Raspbian itself.

When the toolchain is installed on your computer you can build Unitest using the following commands:

./configure 4 arm-none-eabi-
make clean
make -j

The configure command writes a Config.mk file for Circle. "4" is the major revision number of your Raspberry Pi (1, 2, 3, 4 or 5). The second (optional) parameter is the prefix of the commands of your toolchain and can be preceded with a path. Do not forget the dash at the end of the prefix!

An optional third parameter can be appended to specify the bit size of the ARM architecture to be used as build target. It can be "32" (default) or "64" (for Raspberry Pi 3, 4 and 5 only).

If the build was successful, you find the executable image file of Unitest in the src/ subdirectory with the name kernel.img (Raspberry Pi 1), kernel7.img (Raspberry Pi 2), kernel8-32.img (Raspberry Pi 3) or kernel7l.img (Raspberry Pi 4).

You will need a SD card with FAT16 or FAT32 partition to install Unitest. This partition must be the first file system on the SD card. You have to copy the kernel???.img file, built in the previous step, to this FAT partition. All files have to be placed in the root directory of this partition.

Furthermore you need the Raspberry Pi firmware. You can get it as follows:

cd circle/boot
make

You have to copy the three files bootcode.bin, start.elf and fixup.dat from the circle/boot/ subdirectory to the FAT partition on the SD card. The Raspberry Pi 4 and 5 require different firmware files. Please read the file circle/boot/README for details!

Put the SD card into the card reader of your Raspberry Pi.

Before powering on your Raspberry Pi, the following devices have to be attached:

• HDMI display
• USB PC keyboard
• Ethernet connection (for using network functions)

Alternatively you can connect a serial terminal via GPIO14/15. The HDMI display and USB PC keyboard are not needed then.

Now power on your Raspberry Pi and wait for the prompt. You can display a list of the available commands using the "help" command:

Command                 Description                             Alias

runtest TEST            Run the given test                      run
status [cpu|mem|task]   Show CPU (default), memory, task status st
show [devs]             Show devices
setspeed low|max        Set CPU speed low or to maximum
task [susp|res] TASK    Suspend or resume task
ntp HOST [[-]MIN]       Set NTP server and time difference
syslog HOST [PORT]      Set syslog server
sleep SECS              Sleep SECS seconds
clear                   Clear the screen
reboot                  Reboot the system
help [tests]            This help or info about the tests

Numerical parameters can be given decimal or in hex (with "0x" prefix).
Multiple commands can be entered on one line.

Help about the different tests will be displayed with the command "help tests":

Test            Parameters              Description

fractal         [MAXITERATION]          Display Mandelbrot image
files           PARTITION [COUNT]       Write and read files
fatfs           SD:|USB: [COUNT]        Write and read files using FatFs
showmbr         DEVICE                  Show partitions from Master Boot Block
sound           DEVICE [LHZ [RHZ]]      Play tone on sndpwm, sndi2s, sndhdmi, sndusb or sndvchiq
iperf           [HOST]                  Run iperf2 server (default) or client
vchiqecho       [BLKCOUNT [BLKSIZE]]    Send data blocks via VCHIQ with echo
vcgencmd        CMD [ARG...]            Generate VC command

Tests can be aborted by pressing Ctrl-Alt-Del or ^C on serial interface.

Some commands and tests require parameters, which are given in upper case letters in the help screens. Optional parameters are enclosed in []. The following table lists the different parameters: