The libretouch Bootloader

libretouch builds its own U-Boot, but does not install it. Every documented procedure boots through the stock bootloader instead. This page says what our U-Boot is, what has actually been run, and — briefly — how to put it on a device if you want to.

What it is

One U-Boot serves everything: a single target and defconfig (am335x_libretouch_config) covering both processor modules, every product, and both ways of starting a board. It is a ten-patch series on top of u-boot-ti-staging 2025.01 — seven generic fixes and a TSCADC driver, then the board itself, the USB-RNDIS handoff, and dual-bank NAND boot.

Nothing about the product is a build-time choice. The board is identified at run time: the processor module from an eFuse strap in the control module — read in the SPL, before the console exists, because the two modules route UART3 to different balls — and the product from the manufacturing-data record, plus a variant resistor on ADC input AIN0 on SCM. From those it derives ${fdtfile} as <variant>_<module_type>.dtb, retries with the module's common_*.dtb when that tree is not on the medium, and leaves alone any value the environment already carries.

It also understands the dual-bank NAND layout the stock system uses: slotselect applies the Ping/Pong signature rules and leaves the answer in ${nandbank}; fixsig restores the Linux name in the uImage header in RAM so bootm accepts a slot whose stored signature says otherwise.

Which binary a machine deploys is only a matter of packaging — a CH-headered MLO for the BootROM's NAND loader, a raw u-boot-spl-rndis.bin for its USB loader. The U-Boot in both is the same build.

Telling the two apart at the console

The prompts differ, which is the quickest way to know which bootloader you are talking to:

	Stock U-Boot 2014.07	libretouch U-Boot 2025.01
Prompt	U-Boot#	=>
Stops autoboot	only the U key — Autoboot in 5 seconds ('U' to stop):	any key — Hit any key to stop autoboot:

Documentation that shows a => prompt — Unbrick a device, for instance — is talking to ours over RNDIS. A U-Boot# prompt is the bootloader in the device's flash.

What has been run

Path	State
From NAND, on spotty_sm2	Works, including the full Ping/Pong slot selection
Over USB RNDIS	Works. This is what libretouch-net builds, and what Unbrick a device drives — every recovery exercises it
Anything on SCM	Not tested

Booting, in other words, is done. The gap is everything the stock bootloader does besides booting.

What it does not do

No sweup. The stock bootloader's software-update command is absent, and with it the installation and update routes that run inside the bootloader: Install or recover from USB and the whole U-Boot update mechanism. Those exist precisely for the case where Linux will not start, so this is not a small thing to give up.

No keypress-triggered functions. Stock samples the keypad during autoboot and maps key combinations to emergency commands. Ours does not look at the keypad. That also takes out Restore stock firmware, whose whole procedure is holding two buttons while applying power — with our bootloader installed, there is nothing listening for them.

Neither is a bug to be fixed in passing: they are the stock update machinery, and libretouch installs its own images by other means (network installation, USB boot, RNDIS).

Why it is not installed

Nothing needs it. The stock bootloader boots libretouch from NAND, from a USB drive, and over RNDIS, and it can do that because libretouch's images are built to satisfy it — the uImages are named Linux-… so the slot check passes, and the device tree is loaded by the stock nand_boot command.

Installing ours therefore buys nothing today and costs the two mechanisms above. On a device that still has to be reinstalled, updated or recovered by someone who is not you, that is a bad trade. It becomes a good one when libretouch grows its own update path and no longer needs the stock one.

Installing it

SM2 only. On SCM there is no practical recovery from a bad bootloader; see the warning at the top of Unbrick a device. Do not do this on an SCM board.

Build it — any machine produces the NAND pair:

MACHINE=libretouch-usb bitbake u-boot-ti-staging

MLO and u-boot.img land in build/deploy-ti/images/libretouch-usb/.

Then, in order:

1. Run it over RNDIS first. Build libretouch-net, boot the device from it per USB RNDIS network boot, and confirm it reaches a prompt, identifies the board (printenv variant module_type fdtfile) and sees the flash (nand info). Nothing is written. Worth doing on any board that is not a spotty_sm2, since that is the only one this has run on.
2. Keep that host set up while you write. The BootROM tries the Micro-USB port before NAND, so with a host on the port the device boots what the host offers regardless of what is in flash. That is what makes the write recoverable.
3. Write the two partitions exactly as in Unbrick a device, substituting your own MLO and u-boot.img for the stock ones, and verify them with the CRC check in the step that follows.
4. Erase the environment. The stock environment will otherwise survive and be interpreted by a bootloader that does not share its defaults — see step 6.

Going back to stock is the same procedure with the stock MLO and u-boot.img, which is the ordinary unbrick case. Keep a copy of both before you start — with ours installed there is no sweup to fetch them for you.