CPSC359 Baremetal Test Program
The test program included by default in the Pi kits is a custom program I have developed, drawing from several freely available resources including the works of Ethan Faust, Zoltan Baldaszti, and Adam Greenwood-Byrne. The program servers as a means for me to learn some baremetal C and also provide a baseline test for the Pi kits.
The program is intended to make sure your Pi kit is working correctly, by displaying output from the buttons and enabling the use of the framebuffer.
You should check your code’s performance against this test program’s.
Controls
Pressing any button will simply return “You pressed: B (1)”, where B and (1) are the literal and integer values of the buttons. If you press a button but get an incorrect result, your controller is physicially damaged and needs repairs!
Holding START while booting the Pi will launch UART mode instead of framebuffer mode, useful if you do not have a monitor attached.
START+RIGHT will initiate the LED traffic light board test. In this test, holding SW2 will return to the SNES controller test in the previous output mode.
START+DOWN while in the framebuffer mode will clear the framebuffer and send output to UART instead.
START+R while in the framebuffer mode will refresh the framebuffer.
START+LEFT while in UART mode will activate the framebuffer and send output to the framebuffer.
Framebuffer Mode
When plugged into HDMI, the framebuffer mode may be used. This mode functions much the same as UART mode, but it shows the output over HDMI instead. Due to limitations in the Pi, the HDMI cable must be plugged in to a display before activating the framebuffer mode, or no output will show at all until the device is power cycled.
Pressing START+DOWN will clear the framebuffer and resume to outputting over UART only.
UART Mode
This is the text-based serial console that is accessible through the debug chip included in the custom HAT. The USB-B cable included with the kit enables access to this. In UART mode, a basic blurb is given and textual output of the buttons pressed on the SNES controller are shown.
Framebuffer mode can be accessed by pressing START+LEFT.
UART can be accessed while any tests are running and will display some debugging output (such as in the case of buffer overflows).
LED Board Test
If your kit includes an LED ’traffic light’ board, you can press START+RIGHT to test it. In the test, you will see all 3 lights flash. Holding SW1 will slow down the flashing, pressing it will pause the flashing. Holding SW2 will exit the test and resume the previous test.
How to test
When writing baremetal code, you can come across weird issues with timings, the crudeness of the SNES’s IC, and random gremlins. This program has been written to iron out as many gremlins as possible and produce a known good baseline for peripheral performance in the Pi.
You will want to compare your code’s performance against that of the test program. When you press a button, does your game behave as if the button is held down? Check to see if you see the same behaviour in the test program. If you do not, you will need to adjust your timings! (Hint: You can look at the RJ45 port on the SNES controller while running the test program - the ACT light turns on when button presses are registered!)
Does the framebuffer activate in the test program but not in your game? Check that your mailbox call is correct! Consider lowering the resolution or adjusting the message size!
Is the LED board too dim to see? Are the buttons not responsive? Check them in the test program. Maybe you are not polling for input often enough or maybe your pins aren’t pulled up or down correctly?
IF your game AND the test program are showing incorrect behaviour, email Joe at joe.davison@ucalgary.ca for support. Your kit may need replacing!
Download
The program is included by default on all CPSC359 Pi kits. The program should be present on your Pi when you boot it up, but if you’d like to download a copy to use on your Pi you can do so below.
BaremetalPiTestProgram.img 64MB, sha256:
e0c058d3bd3c3549e1c17f3bc58479b9f4b1bc0ac1bf6003be02d39ccd8c9abe
Source code cannot be provided (see below).
Write the image to your card using dd or similar:
dd if=BaremetalPiTestProgram.img of=/dev/sdXn status=progress
Known issues
- framebuffer memory may not be cleared correctly, causing weirdness when loading additional programs
- secret code can draw incorrectly in the framebuffer under certain conditions
- there is no way to exit the LED board test mode without a working LED board connected, or power cycling
Source Code
I’m very proud of this program, as I had very little knowledge of programming at all before I started creating it, and it would give me no end of joy to share the code with the entire world! However, as much of the techniques used in the code can be applied to your CPSC359 assignments, providing the code will make it all too easy for students taking 359 to stray into the troubled waters of academic integrity. For this reason, I cannot share the code with you. Besides, sharing the code would reveal any hidden surprises that may or may not be in the code. However, I am more than happy to discuss techniques if you find yourself needing support, but please do remember that I am not a teacher or professor!
The program incorporates MIT-licensed code portions from Ethan Faust and Zoltan Baldaszti, as well as some public domain code written by Adam Greenwood-Byrne. The whole project is licensed under the MIT License in keeping with the spirit of these sources; please note that the MIT License does not obligate providing source code like the GPL does.