OP-TEE in Raspberry Pi 3: Build with WSL2 + Docker and Pass xtest (Full Guide)

Important Warning

The Raspberry Pi 3 OP-TEE port is NOT secure.

RPi3 has ARM TrustZone exception levels, but lacks hardware mechanisms required for real secure boot / secure memory / secure peripheral isolation.

This is for education + prototyping only.

Requirements

Hardware You Need

• Raspberry Pi 3 Model B / B+
• microSD card (8GB+ recommended)
• USB microSD card reader
• USB-UART serial adapter (3.3V TTL, Not RS232)
• Jumper wires

Software You Need

• Windows 10/11
• WSL2 enabled
• Docker Desktop installed
• Visual Studio Code installed
• Raspberry Pi Imager installed
• Tera Term (UART terminal) installed

Following Steps

1) Enable WSL2

Open PowerShell (Admin)

wsl --install

Reboot if asked.

Then install Ubuntu from the Microsoft Store (or WSL command).

Check:

wsl -l -v

You should see something like:

Ubuntu   Running   2

2) Install Docker Desktop

Download and install Docker Desktop.

Make sure:

• “Use WSL 2 based engine” enabled
• Docker is running (system tray)

Confirm in Windows PowerShell:

docker --version
docker ps

3) VSCode Setup (WSL + Docker workflow)

Install VSCode extensions

In VSCode:

• Remote Development
• WSL
• Dev Containers (optional, but useful)

Open WSL home folder in VSCode

From WSL terminal:

cd ~
code .

If code command is missing, in VSCode do: Ctrl+Shift+P → “Shell Command: Install 'code' command in PATH”

Then reopen WSL and retry.

4) Start an Ubuntu 22.04 Docker container

We’ll build inside a fresh Ubuntu 22.04 container to avoid dependency hell. (Using Ubuntu 22.04 or 20.04 is recommended)

From Windows PowerShell or WSL:

docker pull ubuntu:22.04

Run container:

docker run -it --name optee2204 ubuntu:22.04 bash

Now you’re inside the container as:

root@xxxxxxxx:/#

In Docker container: NO sudo needed (you are already root).

5) Install OP-TEE build prerequisites (inside container)

Run:

apt update && apt upgrade -y

Install required packages:

apt install -y \
  adb acpica-tools autoconf automake bc bison build-essential ccache cpio cscope \
  curl device-tree-compiler e2tools expect fastboot flex ftp-upload gdisk git \
  libgnutls28-dev libattr1-dev libcap-ng-dev libfdt-dev libftdi-dev libglib2.0-dev \
  libgmp3-dev libhidapi-dev libmpc-dev libncurses5-dev libpixman-1-dev libslirp-dev \
  libssl-dev libtool libusb-1.0-0-dev make mtools netcat ninja-build \
  python3-cryptography python3-pip python3-pyelftools python3-serial python3-tomli \
  python-is-python3 rsync swig unzip uuid-dev wget xdg-utils xsltproc xterm xz-utils \
  zlib1g-dev

6) Install repo tool (inside container)

curl -o /usr/local/bin/repo https://storage.googleapis.com/git-repo-downloads/repo
chmod a+x /usr/local/bin/repo
repo --version

Expected output includes versions and Python info.

7) Create project directory and fetch sources (RPi3 manifest)

We’ll build OP-TEE developer build using official manifests.

mkdir -p /work/rpi3
cd /work/rpi3
repo init -u https://github.com/OP-TEE/manifest.git -m rpi3.xml
repo sync -j4 --no-clone-bundle

This will take time (kernel trees are large).

8) Download toolchains

cd /work/rpi3/build
make -j2 toolchains

9) Build OP-TEE (full stack for RPi3)

Pain point we hit: Buildroot refuses running as root for some host builds.

You may see:

configure: error: you should not run configure as root
(set FORCE_UNSAFE_CONFIGURE=1 in environment to bypass this check)

Fix (the quick bypass)

export FORCE_UNSAFE_CONFIGURE=1

Now build:

make -j$(nproc)

10) Generate SD card image (rpi3-sdcard.img)

During SD image generation, you may hit missing system tools like parted and fdisk.

Pain point we hit:

parted: command not found
fdisk: command not found

Install:

apt install -y parted fdisk

Now generate the SD image:

cd /work/rpi3/build
make sdcard-image

If successful, you should get:

ls -lh /work/rpi3/out/rpi3-sdcard.img

Example expected:

-rw-rw-r-- 1 optee optee 321M ... rpi3-sdcard.img

Copy the image from the Docker container → host

From your Windows/WSL terminal (NOT inside a container):

mkdir -p ~/optee-export
docker cp optee2204:/work/rpi3/out/rpi3-sdcard.img ~/optee-export/
ls -lh ~/optee-export/rpi3-sdcard.img

You should see:

321M rpi3-sdcard.img

11) Flash the image to microSD (Windows)

Recommended tool: balenaEtcher

1. Open balenaEtcher
2. Select image: rpi3-sdcard.img
3. Select SD card
4. Flash

This is much easier than trying raw dd through WSL + USB passthrough.

12) UART Wiring (RPi3)

RPi3 UART pins (40-pin header):

• GND (Black Wire): Pin 6
• TXD (Blue Wire): Pin 8 (GPIO14)
• RXD (Green Wire): Pin 10 (GPIO15)

Warning: Don’t put the Red Wire into the board.

Wiring rule (critical)

UART must be crossed:

• USB-UART TX → RPi3 RX (Pin 10)
• USB-UART RX → RPi3 TX (Pin 8)
• USB-UART GND → RPi3 GND (Pin 6)

Functions:

• TX
• RX
• GND

Color mapping (Color could change, so please check the function and Google it.)

• Black
• Green
• Blue

Most common:

• Black = GND
• Green/Blue = TX/RX (depends on manufacturer)

So you do:

Black → RPi Pin 6 Green → Pin 8 or Pin 10 Blue → the other one

If no output appears on boot → swap green and blue.

13) Windows Serial Console Setup

Execute Device Manager.

You can find out which COM port is connected to your UART cable.

You have to find: Port (COM & LPT)

and find your COM port (For my case, mine is COM3)

You can see “Silicon Labs CP210x USB to UART Bridge(COM3)

We need to know which COM port your board uses.

Then, use Tera Term.

Install Tera Term

PowerShell:

winget install --id TeraTermProject.teraterm -e

Configure

Open Tera Term:

• Select Serial
• Choose the COM port you just figured out here

Then: Setup → Serial port

Set:

• Baud rate: 115200
• Data: 8 bit
• Parity: none
• Stop: 1 bit
• Flow control: none

14) Login and run xtest

When Linux boots fully, you should get:

buildroot login:

Login:

root

Then run:

xtest

It takes time (normal)

On RPi3, xtest can take several minutes. It prints a LOT of output (normal).

15) Expected PASS output (final)

Successful run ends with:

+-----------------------------------------------------
35590 subtests of which 0 failed
112 test cases of which 0 failed
0 test cases were skipped
TEE test application done!

If you get 0 failed, your OP-TEE stack is fully functional.

Common Failure Checklist

1. Docker “sudo not found”

That’s normal. You are root already.

2. Buildroot refuses root build

Fix:

export FORCE_UNSAFE_CONFIGURE=1

3. Missing tools (parted, fdisk)

Fix:

apt install -y parted fdisk

4. No UART logs

• Wrong COM port
• Wrong baud rate (must be 115200)
• TX/RX not crossed
• Swap the two data wires

5. xtest spams output and looks “crazy”

That’s correct. Wait for the final summary.

Thanks for reading! I hope this guide helps you save time when setting up OP-TEE on Raspberry Pi 3 using WSL2, Docker, and UART.

If you run into issues or have suggestions to improve the workflow, feel free to leave a comment — I’ll be happy to update this post.

Last Update: 2026.1.24