Introduction

Hachi (八, Japanese for the number 8) is a serial bootloader for the Raspberry Pi BuildHAT.

Hachi has nothing to do with the original BuildHAT bootloader (aka BHBL), especially since it does not load the BuildHAT firmware (which is also not its intention). Once flashed onto a BuildHAT board, Hachi will replace BHBL and you will lose it forever, until you restore it somehow, as described later.

BuildHAT has a total of 2 MB of flash memory, of which Hachi uses a little over 64 KB:

• The first page at the beginning (256 bytes, address range 0x10000000-0x10000100), where the second stage boot binary (boot_stage2) is located
• The last 64 KB sector (0x101f0000-0x10200000) is occupied by the Hachi executable.

The remaining space is free for custom programs to use.

At startup, Hachi will wait approximately 0.1 seconds to accept a custom program file transfer from the serial interface (uart0) before attempting to start any previously saved program. The serial transfer parameters are as follows

• Baud rate: 115200
• Frame format: 8 data bits, no parity, 1 stop bit (8N1)
• Transfer protocol: XModem with CRC
• File format: UF2

The program will be flashed/programmed to flash memory at the address specified in the UF2 metadata. During the flashing process, the red LED blinks rapidly.

After successful programming, the custom program will start immediately and from then on, Hachi will cease to exist (until the next power-up).

Build & Install

Build against the Raspberry Pi Pico SDK.

Unfortunately, the first step is always the hardest. The original BHBL did not load third-party but officially signed firmware. This closed the door for us to install Hachi (or any other unofficial program) through the serial port. However, we could access the SWD interface:

The marked solder points, from left to right, lead to the swdio and swdclk pins, respectively. Connect them to the debugger adapter and start OpenOCD:

openocd ... -f target/rp2040.cfg -c "program hachi.elf verify reset exit"

Connect a serial terminal to the BuildHAT (see the official documentation for the Raspberry Pi 40-pin header for the location of the serial pins). If Hachi has been successfully installed and running, it will spit out a capital "C" every few seconds.

Since Hachi can load custom programs, it is possible to update Hachi itself or restore the BHBL simply through the serial port.

Restore BHBL with OpenOCD

We must provide the target address with the .bin firmware.

openocd ... -f target/rp2040.cfg -c "program bhbl_ver.1631704133.bin verify reset exit 0x10000000"

For convenience here is a copy of it.

Requirements for Custom Programs

Hachi locates the vector table of the custom program at offset 256 from the starting address, which can be any 256-byte flash page boundary, and does not have to be 0x10000000 (XIP_BASE, the starting address of the flash memory).

Flash binaries generated by the Pico SDK conform to the start address requirement.

Custom programs can overlap with Hachi boot_stage2, but these 256 bytes will be skipped and not actually written to flash.

Custom programs may not overlap with Hachi executable, or the last sector of the flash memory.