# nerves_system_surface_rt A [Nerves](https://nerves-project.org/) system for the original Microsoft Surface RT (2012, NVIDIA Tegra 3). > **Status:** Nerves runs from the internal eMMC and boots through GRUB, > with A/B firmware updates over Wi-Fi (`mix upload`) that fall back if > new firmware doesn't validate. All four CPU cores and the 1 MB L2 cache > are on. The console is on the built-in screen, with the Touch/Type Cover > or a USB keyboard. The touchscreen (multitouch), speakers, battery > status and USB storage work. > As far as we know, nobody has run Nerves on a Surface RT before. ## Hardware | Item | Details | | --------- | -------------------------------------------------------------- | | SoC | NVIDIA Tegra 3 (T30), 4× Cortex-A9 (ARMv7-A, NEON) | | RAM | 2 GB | | Storage | 32/64 GB internal eMMC, microSD slot | | Wi-Fi/BT | Marvell 88W8797 (SDIO, Linux driver `mwifiex_sdio`) | | USB | 1× USB 2.0 Type-A, host only (no gadget/OTG) | | Input | Touchscreen (Atmel maXTouch, HID over I2C), Touch/Type Cover | | Firmware | UEFI with Secure Boot locked on (must be jailbroken, see below) | This targets the **Surface RT** only. The Surface 2 uses a Tegra 4 and boots Linux differently. ## Part 1: Jailbreak the Surface RT The Surface RT only boots Microsoft-signed code. Two exploits get around this. They're steps of the same jailbreak, and they're done in this order: 1. **Golden Keys** (Secure Boot Debug Policy, CVE-2016-3287 / CVE-2016-3320). A leaked Microsoft-signed debug policy that turns on test signing in the Windows boot manager. Windows updates from November 2016 onwards block it (MS16-094, MS16-100, MS16-140). A device with those updates must be reset to an older Windows image first. 2. **Yahallo** (2020, Bingxing Wang, GPLv2). Exploits the Tegra 3/4 UEFI variable services to take over TrustZone, then permanently turns off Secure Boot. It needs Golden Keys installed first. Microsoft and NVIDIA declined to fix it. `YahalloUndo.efi` reverses it. After Yahallo, the UEFI firmware boots any EFI binary, which is what lets Linux boot. ### Before you start - **Back up or give up the data on the device.** Disabling Secure Boot can lock out the firmware TPM, which makes BitLocker-encrypted data unreadable. Either turn off device encryption from Windows (`manage-bde -off C:`) or save the recovery key (`manage-bde -protectors -get C:`, or ). - **Don't install Windows updates** before jailbreaking. Use a local account, stay off Wi-Fi, or apply `WindowsUpdateManualMode.reg` from the jailbreak USB. - **Keep the tablet plugged in.** - **Only flash firmware that matches your device.** The jailbreak USB holds firmware for several models. ### Resetting the device (if needed) If Windows has post-2016 updates, or you can't sign in, reset the tablet with a Windows RT 8.0 recovery image. Microsoft no longer offers one for the Surface RT at . Use the community images listed on the Open Surface RT [Recovery Images](https://open-rt.gitbook.io/open-surfacert/common/windows-rt/recovery-images) page. Some of the links there are dead. These images are unofficial. To make the recovery USB on macOS: ```sh diskutil list external physical # find the USB drive, e.g. /dev/disk4 diskutil eraseDisk FAT32 RECOVERY MBRFormat /dev/diskN unzip -q "Surface RT 8.0 North America.zip" -d /Volumes/RECOVERY ``` `sources/Install.wim` is about 3.6 GB, under FAT32's 4 GB per-file limit. Boot from it with **Volume Down + Power**, then choose **Troubleshoot → Reset your PC**. ### Making the jailbreak USB on macOS The jailbreak USB package (`Tegra_Jailbreak_USB.zip`) comes from the [jwa4 guide](https://jwa4.gitbook.io/). ```sh diskutil list external physical # double-check the disk identifier! diskutil eraseDisk FAT32 SURFACE MBRFormat /dev/diskN mkdir jailbreak_usb && unzip -q Tegra_Jailbreak_USB.zip -d jailbreak_usb COPYFILE_DISABLE=1 cp -R jailbreak_usb/ /Volumes/SURFACE/ dot_clean -m /Volumes/SURFACE # remove macOS ._ metadata files diskutil eject /dev/diskN ``` `eraseDisk` erases the whole disk without asking for confirmation. What's on the USB drive: | Path | Purpose | | -------------------------------------- | ----------------------------------------- | | `efi/boot/bootarm.efi`, `efi/microsoft/boot/bcd` | Windows boot manager the Surface boots from | | `Jailbreak_USB_Menu.cmd` | Menu for running the jailbreak | | `SecureBootDebugPolicy.p7b`, `Jailbreak/SecureBootDebugPolicy/` | Golden Keys | | `Jailbreak/Yahallo/` | `Yahallo.efi`, `YahalloUndo.efi`, README | | `Firmware/` | UEFI firmware for Surface RT, Surface 2, TF600T, SKU1 | Boot from USB with **Volume Down + Power**. Let go of Volume Down when the Surface logo appears. Then follow the [jwa4 guide](https://jwa4.gitbook.io/), which replaced the Open Surface RT jailbreak USB page. ### Jailbreak references - [Open Surface RT guide](https://open-rt.gitbook.io/open-surfacert/) - [Open Surface RT: Jailbreak Exploits](https://open-rt.gitbook.io/open-surfacert/common/windows-rt/jailbreak-exploits) - [Open Surface RT: Yahallo, Disable Secure Boot](https://open-rt.gitbook.io/open-surfacert/common/boot-sequence/uefi/secure-boot/disable-secureboot) - [Open Surface RT: Recovery Images](https://open-rt.gitbook.io/open-surfacert/common/windows-rt/recovery-images) - [jwa4 guide](https://jwa4.gitbook.io/) (current jailbreak USB instructions) - [Ubuntu wiki: ARM/SurfaceRT](https://wiki.ubuntu.com/ARM/SurfaceRT) - Open Surface RT Discord: ## Part 2: Porting Nerves ### What's needed 1. **Nerves system.** Build on [`nerves_system_br`](https://github.com/nerves-project/nerves_system_br), using an existing ARMv7 system as a template. The Cortex-A9 works with the existing `nerves_toolchain_armv7_nerves_linux_gnueabihf` toolchain. 2. **Kernel and device tree.** The Surface RT device tree is **not** in mainline Linux. This system builds Linux 6.18.36 with a patch that adds it, ported from the Open Surface RT community kernel. See [`dts/README.md`](dts/README.md) for the source, the changes and the known limitations (one CPU speed). The battery and audio drivers are backported from later kernels (`linux/0008`-`0010`). The kernel config is `tegra_defconfig` plus [`linux/surface-rt.fragment`](linux/surface-rt.fragment). 3. **Bootloader.** After Yahallo, UEFI boots EFI binaries directly. Use **GRUB (arm-efi)** for A/B switching, following the GRUB + grubenv pattern in [`nerves_system_x86_64`](https://github.com/nerves-project/nerves_system_x86_64). Avoid U-Boot: it supports the Surface RT, but has to be loaded over USB from another computer (APX/RCM mode) on every boot and only uses one core. 4. **`fwup` config.** Partition layout: EFI FAT boot partition, rootfs A, rootfs B, application data. Develop on microSD first, then move to the eMMC. 5. **Development access.** The USB port is host-only, so Nerves' USB gadget networking won't work. Use Wi-Fi (VintageNet) or a USB Ethernet adapter, with `nerves_ssh` and `mix upload`. 6. **Display (optional).** Nerves runs headless by default. Options are a framebuffer console, Scenic on DRM, or a kiosk browser (heavier). ### Using the system Add it to a Nerves project's `mix.exs` with a target named `surface_rt`: ```elixir {:nerves_system_surface_rt, github: "CoderDennis/nerves_system_surface_rt", tag: "v0.2.1", runtime: false, targets: :surface_rt} ``` Releases have a prebuilt system artifact, so `mix firmware` doesn't need to build the system. Without one it's built from source, as below. [nerves_surface_rt_hello](https://github.com/CoderDennis/nerves_surface_rt_hello) is an example app. ### Building The system uses `nerves_system_br` 1.35.2, which builds Erlang/OTP 29.1.2 for the target. The host's OTP major version must match, so this repo pins Erlang 29.1.2 and Elixir 1.20.4-otp-29 in `.tool-versions`. Don't go below OTP 29.1.1 on the target. Its SSH daemon (ssh 6.0.5) rejects subsystem requests that follow an `env` request, and macOS's ssh sends `LANG` and `LC_*` by default, so `mix upload` and `sftp` fail with "subsystem request failed on channel 0". ```sh mix archive.install hex nerves_bootstrap mix deps.get mix compile # on macOS, Buildroot runs in Docker (Docker must be running) ``` If your shell doesn't switch versions automatically, prefix the commands with `mise exec --` (or the `asdf` equivalent). Nerves writes the Buildroot output to `build.log` in this directory. Don't redirect `mix compile` to that same file, or the two outputs overwrite each other. The built system ends up in `~/.nerves/artifacts/nerves_system_surface_rt-portable-/`. ### Plan - [x] Finish the jailbreak (Golden Keys, then Yahallo) - [x] Boot an existing community Surface RT Linux image to confirm the kernel, device tree and boot path work - [x] Nerves system skeleton with `nerves_system_br`, GRUB (arm-efi) and a `fwup` config with A/B updates (fwup configs tested with placeholder files; full build not run yet) - [x] Surface RT device tree ported to Linux 6.18 (compiles with `dtc`) - [x] Full system build (`mix compile`): kernel with EFI stub, Surface RT DTB, GRUB `bootarm.efi`, rootfs and a firmware image all build - [x] Boot Nerves to an IEx prompt (kernel and DTB loaded from the UEFI Shell on a USB stick, root filesystem on microSD) - [x] Boot through GRUB from the eMMC, with A/B updates. The UEFI firmware can't see the microSD slot, so Nerves can't boot from microSD. - [x] Wi-Fi with VintageNet and SSH access - [x] Display output (Tegra DRM console on the built-in screen) - [x] Install to eMMC (see [Installing](#installing)) - [ ] An easier first install (today it needs a second, temporary boot setup, see below). Now that USB flash drives work, Nerves could probably run from a USB stick instead of the microSD card, possibly just `mix burn` to a stick and boot it with Volume Down + Power. The stick has the same partition IDs as the eMMC install, so it would have to come out afterwards. Not tried yet. - [x] Fall back to the previous firmware if new firmware isn't validated - [x] Use all four CPU cores (ACPI parking protocol, see `linux/0005`) - [x] Turn on the L2 cache (through the secure monitor, see `linux/0006`) - [x] USB flash drives (fixes a mainline ChipIdea bug on Tegra, see `linux/0007`) - [x] Battery status and audio (drivers backported from Linux 7.x) - [x] Touch/Type Cover, with hotplug (`linux/0011`, `linux/0012`) - [x] Touchscreen (multitouch, HID over I2C) - [x] Audio playback through the speakers (fixes a mainline WM8962 bug, see `linux/0013`). The speaker volume starts at 0; turn it up with `amixer -c 0 sset Speaker 110`. - [x] Software reboot (restarts through the PMIC, see `linux/0003-mfd-tps65910-Restart-through-the-PMIC.patch`) - [x] Hardware watchdog: the PMIC's watchdog power-cycles the Surface if the system hangs (`linux/0014`). The Tegra watchdog's reset doesn't bring it back. - [ ] Research the front and rear cameras. They don't seem to be USB: probably camera sensors on the Tegra 3's MIPI CSI interface. Start by finding the sensors in the firmware's ACPI tables. The community kernels don't support them either. ### Installing The UEFI firmware can't boot from microSD, so Nerves is installed on the internal eMMC. This erases the eMMC, including Windows. The first install currently needs a second, temporary boot setup: 1. `mix burn` the firmware to a microSD card. 2. On a FAT-formatted USB stick, put a UEFI Shell as `EFI/BOOT/bootarm.efi`, plus the system's `zImage` and `tegra30-microsoft-surface-rt-efi.dtb`, and a `startup.nsh` like: ``` fs0: zImage dtb=tegra30-microsoft-surface-rt-efi.dtb root=PARTUUID=04030201-02 rootwait console=tty1 cpuidle.off=1 clk_ignore_unused pd_ignore_unused reset -s ``` The Open Surface RT Raspberry Pi OS image's boot partition has such a UEFI Shell. 3. Boot the Surface from the stick, with the microSD card in, and connect to Wi-Fi with `VintageNetWiFi.quick_configure/2`. 4. Copy the `.fw` to the Surface (`sftp nerves.local`, `put` it in `/root`), then write it to the eMMC at the IEx prompt: ```elixir System.cmd("fwup", ["-a", "-i", "/root/.fw", "-d", "/dev/mmcblk0", "-t", "complete", "-U"]) ``` This only writes the eMMC's main area. Its boot partitions, which hold the UEFI firmware, are read-only in Linux. 5. Power off, remove the microSD card and the USB stick, and press Power. The microSD card uses the same partition IDs, so leave it out. After that, update with `mix upload`. GRUB switches between partitions A and B on its own, and the Surface restarts into the new firmware by itself. New firmware boots once as a trial. Nerves.Runtime's StartupGuard validates it once all applications have started. If it doesn't, the next boot falls back to the previous firmware: if new firmware hangs, hold Power for 10 seconds and turn the Surface back on. The kernel arguments (`LINUX_ARGS` in `post-build.sh`) are in each root filesystem, so they ship with `mix upload` and are covered by the fallback. `mix upload` doesn't update the boot partition's `grub.cfg`, which only picks the partition and handles the fallback. Only a full install writes it. When it changes, copy it to `/mnt/boot/EFI/BOOT/` on the device (remount `/mnt/boot` read-write first). #### Untested alternative: install from Raspberry Pi OS This would avoid the microSD card and the hand-made UEFI Shell setup. It only needs one USB stick, but it hasn't been tried yet. 1. Write the Open Surface RT Raspberry Pi OS image to a USB stick, boot the Surface from it (Volume Down + Power) and connect to Wi-Fi. Its kernel can use USB storage. 2. On the Mac, turn the `.fw` into a raw disk image: ```sh fwup -a -i .fw -t complete -d surface.img ``` 3. Copy `surface.img` to the Surface (e.g. with `scp`) and write it to the eMMC: `sudo dd if=surface.img of=/dev/mmcblk0 bs=4M conv=fsync`. Check with `lsblk` that `mmcblk0` is the 32/64 GB eMMC first. 4. Power off, remove the USB stick, and press Power. Written as a raw image, the application data partition probably stays at the 256 MiB set in `fwup.conf`. fwup can only grow it to fill the disk when it writes the disk directly. Installing the armhf `fwup` package on Raspberry Pi OS and running `fwup -a -i .fw -t complete -d /dev/mmcblk0` there would avoid that. ### Nerves references - [Nerves docs: Systems](https://hexdocs.pm/nerves/systems.html) - [`nerves_system_br` README](https://github.com/nerves-project/nerves_system_br) (porting guide) - [Porting Nerves to the e-RT3](https://dev.to/pojiro/elixir-on-industrial-hardware-porting-nerves-to-e-rt3-7k1), an example port to new hardware - [U-Boot docs: Surface RT](https://docs.u-boot.org/en/latest/board/microsoft/surface-rt.html) - [Linux Tegra device trees](https://github.com/torvalds/linux/tree/master/arch/arm/boot/dts/nvidia) ## License This project follows the [REUSE](https://reuse.software/) specification. `REUSE.toml` maps each file to its license, and the license texts are in `LICENSES/`. Like the official Nerves systems: | Files | License | |---|---| | `linux/` (kernel config fragment and Surface RT device tree patch) | GPL-2.0-only | | `Config.in`, `nerves_defconfig`, `post-build.sh`, `post-createfs.sh` (Buildroot derived) | GPL-2.0-or-later | | `fwup.conf`, `fwup-ops.conf`, `fwup_include/`, `grub.cfg`, `rootfs_overlay/`, `mix.exs` and other small config files | CC0-1.0 | | `README.md`, `dts/README.md` | CC-BY-4.0 | The device tree comes from the [Open Surface RT](https://open-rt.gitbook.io/open-surfacert/) community kernel and keeps its upstream SPDX headers.