‘Bare-metal’ is programming without an operating system – running the code directly on the hardware, without the usual device drivers.
I’ve been developing a bare-metal driver for the WiFi chip on the Raspberry Pi ZeroW, and needed a method of downloading & debugging the code. Alpha by Farjump seemed ideal for the purpose; it is a small remote GDB server, that can be controlled by a Windows or Linux PC, using a simple 2-wire serial link.
In this blog I’ll describe how to set up Alpha, and give some tips to maximise the functionality of this excellent application. I’ve been using Windows as a development platform, so this text is biased in that direction, but much of the information is applicable to Linux as well.
Limitations
So far, I have only had success running Alpha on the original Pi version 1, and the ZeroW; for example, it didn’t work on version 3 hardware. This may be due to errors on my part; I’m not sure which board versions are actually supported by the current release.
Hardware connection
You need a 3-wire serial connection (ground, transmit & receive) at 3.3-volt logic levels. Any USB-to-serial adaptor should work, so long as it has a 3.3V output, not 5 volt or RS-232.
I use an FTDI cable for the purpose, the TTL-232R-RPi, which has just black, yellow and red wires connected as follows:
These are labelled from the perspective of the Raspberry Pi, so the Txd line will go to Rxd on your serial adaptor, and vice-versa. Take care when connecting, due to the closeness of the 5 volt power pins; they could cause serious damage.
Installation
Clone or download Alpha from https://github.com/farjump/raspberry-pi
You just need 4 files in the root directory of the SDHC card that is plugged into the Raspberry Pi:
An install script for Linux is provided (scripts/install-rpi-boot.sh) but I had no luck with this, so had to do a manual install. Alpha.bin and config.txt come from the Alpha distribution ‘boot’ directory, bootcode.bin and start.elf are copied from the root directory of a Raspbian distribution.
The Raspberry Pi boot directory is FAT32 formatted, so you don’t have to run Linux; you can plug the SDHC card into a USB adaptor on a Windows PC, and copy the required files across.
When you boot the system, nothing seems to happen; you need to use the serial link to check alpha is working.
Compiler
The compiler I’ve been using is gcc-arm-none-eabi, version 7-2018-q2-update. Installation on Raspbian Buster just requires:
sudo apt install gcc-arm-none-eabi
On Windows, download from here; this places the tools in the directory
C:\Program Files (x86)\GNU Tools Arm Embedded\7 2018-q2-update\bin
Check that this directory in included in your search path by opening a command window, and typing
arm-none-eabi-gcc -v arm-none-eabi-gdb -v
If not found, close the window, add to the PATH environment variable, and retry.
For more complicated projects, you’ll probably be using Makefiles, and on Windows, will need to install ‘make’ from here. As with GCC, check that it is included in your executable path by opening a new command window, and typing
make -v
Building a project
The SDK files are in the sdk sub-directory of the Alpha distribution; for simplicity, you can just copy it to create an identical sdk sub-directory in your project directory.
We need something to compile, so here is a simple program alpha_test.c to flash the LED on a Pi ZeroW at 1 Hz.
// Simple test of Raspberry Pi bare-metal I/O using Alpha
// From iosoft.blog, copyright (c) Jeremy P Bentham 2020
#include <stdint.h>
#include <stdio.h>
#define REG_BASE 0x20000000 // Pi Zero
#define GPIO_BASE (REG_BASE + 0x200000)
#define GPIO_MODE0 (uint32_t *)GPIO_BASE
#define GPIO_SET0 (uint32_t *)(GPIO_BASE + 0x1c)
#define GPIO_CLR0 (uint32_t *)(GPIO_BASE + 0x28)
#define GPIO_LEV0 (uint32_t *)(GPIO_BASE + 0x34)
#define GPIO_REG(a) ((uint32_t *)a)
#define USEC_BASE (REG_BASE + 0x3000)
#define USEC_REG() ((uint32_t *)(USEC_BASE+4))
#define GPIO_IN 0
#define GPIO_OUT 1
#define LED_PIN 47
void gpio_mode(int pin, int mode);
void gpio_out(int pin, int val);
uint8_t gpio_in(int pin);
int ustimeout(int *tickp, int usec);
int main(int argc, char *argv[])
{
int ticks=0;
gpio_mode(LED_PIN, GPIO_OUT);
ustimeout(&ticks, 0);
printf("\nAlpha test");
while (1)
{
if (ustimeout(&ticks, 500000))
{
gpio_out(LED_PIN, !gpio_in(LED_PIN));
putchar('.');
fflush(stdout);
}
}
}
// Set input or output
void gpio_mode(int pin, int mode)
{
uint32_t *reg = GPIO_REG(GPIO_MODE0) + pin / 10, shift = (pin % 10) * 3;
*reg = (*reg & ~(7 << shift)) | (mode << shift);
}
// Set an O/P pin
void gpio_out(int pin, int val)
{
uint32_t *reg = (val ? GPIO_REG(GPIO_SET0) : GPIO_REG(GPIO_CLR0)) + pin/32;
*reg = 1 << (pin % 32);
}
// Get an I/P pin value
uint8_t gpio_in(int pin)
{
uint32_t *reg = GPIO_REG(GPIO_LEV0) + pin/32;
return (((*reg) >> (pin % 32)) & 1);
}
// Return non-zero if timeout
int ustimeout(int *tickp, int usec)
{
int t = *USEC_REG();
if (usec == 0 || t - *tickp >= usec)
{
*tickp = t;
return (1);
}
return (0);
}
// EOF
For details of the built-in peripherals, see the ‘BCM2835 ARM Peripherals’ document, available here.
My code polls a microsecond time register, toggling the LED when it reaches a certain value. This allows the CPU to do other things while waiting for a timeout, for example, polling other peripherals. It uses a really handy 32-bit counter that is clocked at 1 MHz; surprisingly, the same counter can be used on Linux, though in that case, you have to ask for permission from the OS to use it (e.g. using mmap).
To build the program, a makefile isn’t essential, it can be done with a single command line:
arm-none-eabi-gcc -specs=sdk/Alpha.specs -mfloat-abi=hard -mfpu=vfp -march=armv6zk -mtune=arm1176jzf-s -g3 -ggdb -Wall -Wl,-Tsdk/link.ld -Lsdk -Wl,-umalloc -o alpha_test.elf alpha_test.c
This produces the executable file alpha_test.elf. If your project involves other source files, they can be appended to the command line.
Running the program
Alpha provides the functionality of a remote gdb server, so we need to run a local instance of arm-none-eabi-gdb in remote mode. It is convenient to group all the gdb settings in a single file, named run.gdb:
source sdk/alpha.gdb
set serial baud 115200
target remote COM7
load
continue
On Linux, the serial port will be something like /dev/ttyUSB0 and you may need to set specific permissions for a user-mode program to access it.
We can now execute the code by running gdb with the settings, and executable filename:
arm-none-eabi-gdb -x run.gdb alpha_test.elf
If all is well, the code should load and run, flashing the ZeroW on-board LED at 1 Hz:
Loading section .entry, size 0x14f lma 0x8000
Loading section .text, size 0xaf00 lma 0x8150
Loading section .init, size 0x18 lma 0x13050
Loading section .fini, size 0x18 lma 0x13068
Loading section .rodata, size 0x310 lma 0x13080
Loading section .ARM.exidx, size 0x8 lma 0x13390
Loading section .eh_frame, size 0x4 lma 0x13398
Loading section .init_array, size 0x8 lma 0x2339c
Loading section .fini_array, size 0x4 lma 0x233a4
Loading section .data, size 0x9b0 lma 0x233a8
Start address 0x81c0, load size 48471
Transfer rate: 9 KB/sec, 850 bytes/write.
Alpha test............
Hit ctrl-C to halt the program, then ‘q’ to quit from GDB.
Unfortunately, if all is not well, there are no helpful error messages. If the target system is completely unresponsive, gdb will stall after the ‘reading symbols’ message; if it sees incorrect characters on the serial link it might report ‘a problem internal to GDB has been detected’; either way, the only option is to re-check the files on the SDHC card, and the serial connections.
Speedup
The upload is quite slow, so I wanted to speed it up. The limiting factor is the 115 kbaud serial speed, which is hard-coded into Alpha. However, gdb does have full access to all the on-chip registers, so it is possible to change the baud rate using GDB remote commands before downloading.
The commands have to be sent at 115 kbit/s to change the rate, and GDB must be reconfigured to use the serial link at the high speed. There are various ways this can be done; I decided to write a small program, alpha_speedup.py, that is compatible with Python 2.7 and 3.x:
# Utility for RPi Alpha to increase remote GDB baud rate
# From iosoft.blog, copyright (c) Jeremy P bentham 2020
# Requires pyserial package
import sys, serial, time
# Defaults
serport = "COM7"
verbose = False
# Settings
OLD_BAUD = 115200
NEW_BAUD = 921600
TIMEOUT = 0.2
SYS_CLOCK = 250e6
# BCM2835 UART baud rate divisor
uart_div = int(round((SYS_CLOCK / (8 * NEW_BAUD)) - 1))
# GDB remote commands
high_speed = "mw32 0x20215068 %u" % uart_div
qsupported = "qSupported"
# Send command, return response
def cmd_resp(ser, cmd):
txd = frame(cmd)
if verbose:
print("Tx: %s" % txd)
ser.write(txd.encode('latin'))
rxd = str(ser.read(1468))
if verbose:
print("Rx: %s" % rxd)
resp = rxd.partition('$')
return resp[2].partition('#')[0]
# Acknowledge a response
def ack_resp(ser):
ser.write('+'.encode('latin'))
if verbose:
print("Tx: +")
# Return string, given hex values
def hex_str(hex):
return bytearray.fromhex(hex).decode()
# Return remote hex command string
def cmd_hex(cmd):
return "qRcmd,%s" % "".join([("%02x" % ord(c)) for c in cmd])
# Return framed data
def frame(data):
return "$%s#%02x" % ("".join([escape(c) for c in data]), csum(data))
# Escape a character in the message
def escape(c):
return c if c not in "#$}" else '}'+chr(ord(c)^0x20)
# GDB checksum calculation
def csum(data):
return 0xff & sum([ord(c) for c in data])
# Open serial port
def ser_open(port, baud):
try:
ser = serial.Serial(port, baud, timeout=TIMEOUT)
except:
print("Can't open serial port %s" % port)
sys.exit(1)
return ser
# Close serial port
def ser_close(ser):
if ser:
ser.close()
if __name__ == "__main__":
opt = None
for arg in sys.argv[1:]:
if len(arg)==2 and arg[0]=="-":
opt = arg.lower()
if opt == "-v":
verbose = True
opt = None
elif opt == '-c':
serport = arg
opt = None
print("Opening serial port %s at %u baud" % (serport, OLD_BAUD))
ser = ser_open(serport, OLD_BAUD);
cmd_resp(ser, "")
ack_resp(ser)
if cmd_resp(ser, qsupported):
ack_resp(ser)
print("Setting %u baud" % NEW_BAUD)
cmd_resp(ser, cmd_hex(high_speed))
time.sleep(0.01)
print("Reopening at %u baud" % NEW_BAUD)
ser_close(ser)
ser = ser_open(serport, NEW_BAUD);
ack_resp(ser)
if cmd_resp(ser, qsupported):
ack_resp(ser)
print("Target system responding OK")
time.sleep(0.01)
else:
print("No response from target system")
#EOF
For details of the commands, see the GDB remote specification. One unusual feature is that all responses from the target system have to be acknowledged with a ‘+’ character, otherwise they are re-sent 14 times. This is a bit awkward since the baud-rate change command acts immediately, so although it is sent at 115 kbit/s, the response is at 921600; we need to quickly close & reopen the port at the higher speed to send the acknowledgement.
I’ve hard-coded a Windows port (COM7) which will need to be changed for your setup, or use the command-line -c option to set something else (e.g. /dev/ttyUSB0). The -v option enables a verbose mode, that shows the commands and responses.
The second line of the GDB configuration file run.gdb needs to be changed to reflect the increased speed:
set serial baud 921600
The speedup program must always be run before gdb:
python alpha_speedup.py
arm-none-eabi-gdb -x run.gdb alpha_test.elf
Other features
Here are some things I’ve discovered about Alpha that might be useful:
ctrl-C: in my experimentation, you can only use ctrl-C to interrupt the program if it is printing to the console. There is presumably a way round this (apart from adding unnecessary print statements) but I don’t know what that is.
Console output: this works well, any print statements are echoed to the GDB console, but it does slow down the code a lot; if you need high speed, it is best to buffer the serial output in your program, then print it at the end.
GDB break: if you just want to quickly run a program, see the result, and exit GDB, this can be done by setting a breakpoint on a specific function, and setting an action when that is triggered, e.g. add the following lines to the end of run.gdb:
break gdb_break
commands 1
kill
quit
end
Now when the function ‘gdb_break’ is executed, GDB will exit back to the command-line. I add a matching dummy function to the C code:
// Dummy function to trigger gdb breakpoint
void gdb_break(void)
{
} // Trigger GDB break
..and just call this function if I want to halt the program and exit.
Copyright (c) Jeremy P Bentham 2020. Please credit this blog if you use the information or software in it.
Lean2 