FreeBSD on the PinePhone Pro

Porting FreeBSD to run on the PinePhone Pro. This repo tracks files added to or modified from the FreeBSD source. The intention is to merge these into upstream once ready. The priority is currently on phone bringup, i.e. writing or porting drivers to enable the hardware. Contributions and collaborations are welcome.

Progress

What works:

• Boot up via serial console (headphone jack UART)
• Toggling of red/green/blue front LED
• Realtime clock (RTC)
• Battery charging via USB
• Battery status via sysctl hw.acpi.battery
• LCD display via EFI framebuffer and backlight control with backlight (requires Megi's U-boot)
• Touchscreen (currently only single-touch)

Known issues:

• None of the phone's hardware currently works (other than listed above): Modem, Wifi, USB, sensors, etc.
• Battery percentage is a crude estimate based on voltage (may fluctuate)

Usage

Requirements:

• Install Megi's rk2aw and U-boot onto your phone if you haven't already (needed for EFI framebuffer display):
  • Under Linux on your phone (e.g. using Mobian or postmarketOS), download the ppp.tar.gz file
  • Uncompress it with tar -xvf ppp.tar.gz
  • Run cd ppp && sudo ./spinor-flash-initial-setup.sh
• Optional: For development (e.g. of kernel modules), you can use serial over the headphone jack to interact with the OS (see https://pine64.org/documentation/PinePhone/Accessory/#serial-console )

Releases

A developer build of FreeBSD including a minimal desktop and virtual keyboard is available for testing and development:

• Ensure you have the right bootloader (see requirements)
• Download a flashable image from https://pppfreebsd.honeyguide.net/
• Flash it to an SD card (e.g. xzcat freebsd-pinephonepro-yymmdd.img.xz | sudo dd of=/dev/XXX bs=4m status=progress)
• Optional: You can resize the root partition to use up the free space on your disk.
• Optional: To get the latest desktop changes (committed after the latest bootable image was created), copy the files from img/fs in this repo, to / on the SD card's second partition (e.g. /media/da0p2), overwriting files as necessary.
• Insert the SD card into the phone and power it on. If it flashes red, power it on again.
• Select to boot "EFI OS on SD/1"

The desktop is based on IceWM and can be easily customized. It is started by /etc/rc.local in combination with /root/.xinitrc. The on-screen keyboard is DeforaOS keyboard.

Building and development setup

To build your own bootable image:

• Clone this repo to your FreeBSD PC
• ./setup.sh to setup the project (will download FreeBSD source)
• ./dtb-build.sh to build the DTB
• ./cross-build.sh to compile the custom kernel (may take a few minutes)
• Optional: create img/distro folder if you would like to have 3rd party software in your image (e.g. copy in /usr/local from a Raspberry Pi SD card running the latest FreeBSD image)
• cd img && ./create_img.sh to create a flashable image (will download about 85Mb FreeBSD current image)
• Flash the freebsd-ppp.img file to SD card with sudo dd if=freebsd-ppp.img of=/dev/XXX bs=4m status=progress replacing /dev/XXX with the SD card device (be careful, use the correct device!)
• Insert the SD card into the phone and power it on. If it flashes red, power it on again.
• Select to boot "EFI OS on SD/1"

Development workflow

To make changes to the kernel and test:

1. You can make changes in the src sub-tree, copying in files from freebsd-src as needed.
2. Insert the SD card into the PC and wait for it to auto-mount (or mount it manually to /media/...).
3. Run ./patch.sh && ./cross-build.sh && ./install.sh /media/[drive] to patch the freebsd-src sub-tree with the changes, build the kernel, copy it to the SD card, and then unmount it. Replace ./cross-build.sh with ./dtb-build.sh if you are testing changes to the device tree.
4. Put the SD card into the phone and boot it.

Serial console for on-device development

You can also build and test on-device, which is especially useful for kernel modules:

1. Disable the headphone hardware switch to enable the serial console.
2. Download and boot the development release (see above).
3. Use the headphone jack to USB serial adapter to connect to your device from your PC: sudo cu -s 1500000 -l /dev/ttyU0
4. Login as root (no password).
5. The kernel source as well as an example driver are in the /root home folder. You can compile a module and then kldload it to test on device. Vim editor is included.

Network access via headphone jack

As we currently don't have working WiFi, Bluetooth, USB, or 4G drivers, the next best way to get network access on your device is to use the serial console that runs over the headphone jack. Here are the steps to get this working:

1. On your PC, add the following to your /etc/pf.conf to enable NAT (replace re0 with your external interface):

ext_if="re0"
int_if="tun0"
localnet=$int_if:network

set skip on lo0
nat on $ext_if inet from !($ext_if) -> ($ext_if:0)

3. On your PC, enable packet forwarding: sysctl net.inet.ip.forwarding=1
4. On your PC, start the packet filter: sudo service pf start
5. On your PC, copy the img/fs/etc/ppp/ppp.conf file from this repo, to /etc/ppp/ppp.conf (adjust any settings like IP addresses as necessary).
6. On your PC, open the serial console to your phone (as described above)
7. In the serial console, login as root, then run ./ppp.sh. This will reset the baud rate of the console to 115200 (the highest speed at which this currently works), so you can immediately close the console (press Enter then ~. to exit cu).
8. On your PC, quickly run sudo ppp -foreground server and in a separate terminal, you can sudo tail -f /var/log/ppp.log to see what is happening. It should connect and stay connected until you press Ctrl-C to exit. If it fails, perhaps the client timed out, so reconnect the serial console (which should have reverted back to 1500000 baud rate) and try again.

You should now have internet access on your phone via your PC. Since you've lost access to the serial console, you can install dropbear SSH server on your phone (using xterm and on-screen keyboard), add a user and set password, then ssh from your PC into your phone using it's IP address.

Sponsor

Thanks to Honeyguide for sponsoring development.

Contact

Please contact me me if you would like to contribute, collaborate, or have questions.

Disclaimer

The developers and sponsors of this project are not liable for any damages or losses that may occur from the use of, or misuse of this software. Use this software at your own risk.