Profpatsch/users/Profpatsch/tolino
- koreader-patches/1-tolino-vision6.lua 3.8 KiB
- os/ 872.9 KiB · 11 dirs, 91 files
- disp-probe.c 3.1 KiB
- fbink-vision6.patch 584 B
- heart.py 813 B
- imgpatch.py 2.8 KiB
- koreader-push.sh 2.1 KiB
- koreader-twrp.sh 3.2 KiB
- packages.nix 626 B
- rotate-test.c 8.4 KiB
- screenshot.sh 874 B
- sdat2img.py 1.2 KiB
- tolino.7 85.9 KiB
tolino(7)
NAME
tolino - the tolino vision 6, what is inside it, how it was rooted and backed up, and why Android could go
DESCRIPTION
A field journal of taking apart — in software — a tolino vision 6 e-reader, with the long-term goal of replacing its Android 8.1 with a single Go process as PID 1 that starts KOReader, and nothing else.
This page records the state of the device, every step taken on it and the insights behind each step, in the order they happened. Read CURRENT STATE and RECOVERY before touching the device again.
The scripts next to this page:
imgpatch.py
applies an Android
IMGDIFF2patch on the host (used to rebuild the stock recovery).
sdat2img.py
rebuilds a raw ext4 image from an OTA *.transfer.list and decompressed *.new.dat.
heart.py
renders a 1264×1680 black-on-white heart PNG, the first thing drawn on the device from the PC.
disp-probe.c
issues exactly one
DISP_EINK_UPDATE2, with buffer size, region, mode and rotation from the command line; used to bisect the full-screen crash.
rotate-test.c
checks that the disp driver rotates updates drawn in another orientation into the panel's layout correctly, pixel by pixel against what the panel shows; see The disp module.
fbink-vision6.patch
the one-line FBInk change that makes it work on this device.
screenshot.sh
reads back what the panel shows, as a portrait PNG.
koreader-push.sh
pushes KOReader's Kobo build and a glibc runtime to TWRP and starts it.
koreader-twrp.sh
the on-device launcher it runs.
koreader-patches/
KOReader userpatches adapting the Kobo Sage profile to this device.
os/
the tolino OS: Nix build, build steps in Go (os/build/), tolino-sys (os/sys/); see THE TOLINO OS.
The backups live in ~/tolino-backup/, deliberately outside this repository: they contain the user data partition (account, books, notes) and device-unique blobs, and this repository is published. Scratch downloads (kernel and U-Boot sources, firmware, TWRP) are in the gitignored ./tmp/tolino/.
CURRENT STATE
As of 2026-11-03 the tolino runs the tolino OS, not Android:
-
boot holds the tolino OS boot image: our 4.9.337 kernel, with squashfs, and tolino-stage1 as the initramfs; see THE TOLINO OS and Building the kernel. current is generation 30, whose disp.ko has patches 0007 to 0027 (The disp module); 15 brought Testing a module, 13 modules for both our kernels, 4.9.56 and 4.9.337. 9 to 29 are the others left. boot holds the kernel with patch 0011 (since 2026-11-05); the one before it is in /data/tolino/boot-gen19.img. The ext4 generations 4–8 were deleted on 2026-11-02. Android does not boot any more; its system, vendor and data are untouched, and the stock boot.img is in the backup.
-
recovery is TWRP 3.7.0 (iscilyas/tolino_b300_twrp release 0.3, twrp-vision6.img, sha1
74c3e63f..., sha256c53d82b6...), the rescue system: reached byadb reboot recovery, by the button combination in RECOVERY, and automatically when stage1 cannot boot a generation. -
/data/tolino/ holds the generations (generations/<N>/system.img), current, KOReader's settings (koreader/) and the last boot's stage1.log.
-
/system/recovery-from-boot.p is renamed to recovery-from-boot.p.disabled, so a booting Android would not overwrite TWRP.
-
The bootloader, env and every other partition are untouched.
THE DEVICE
SoC
Allwinner B300, a.k.a. sun8iw15, board name "virgo"; 4× Cortex-A7, armv7. xfel calls the family "A50" (FEL id
0x00175500). Made by Netronix (all thentx_prefixes).
RAM
850 MB; with Android and KOReader running only ~370 MB were available.
Storage
mmcblk0is an SD card (type SD, name SS16G, 15.5 GB), i.e. the internal microSD the community mentions; it can be pulled and imaged as a last resort.
Kernel
4.9.56 #29, built 2024-09-04, Allwinner BSP. Command line from boot.img:
selinux=1 androidboot.selinux=permissive buildvariant=user. Not mainline (postmarketOS lists B300 as unsupported and all components untested).
Firmware
Tolino 16.2.1 (versionName of
de.telekom.epub), buildRakutenKobo/tolino/tolino:8.1.0/9b6dc8f/20240904-110945:user/release-keys.
Display
ED070KH3 panel, 1680×1264 landscape internally (fb0 stride 6720, 32 bpp, virtual 1680×2528), waveform 400_B044_HH0D01_ED070KH3U3_VD1400-GOB_TC.awf, VCOM -1410 mV. Driven by Allwinner /dev/disp plus an
eink_decengine; the panel-specific waveform code is a binary blob (libeink_ed070kh3.a_shipped) linked into the GPL kernel module.
Input
event0 gpio-keys (page up/down, power, SW_LID cover); event1 Elan touchscreen, multitouch, 0–1679 × 0–1263; event2 kx122 accelerometer; event3 audio jack.
Power
Ricoh619 PMIC,
ariscpower coprocessor, LM3630A frontlight.
Wi-Fi
RTL8723DS on SDIO.
Kernel modules
All in /system/vendor/modules/: disp.ko, ed070kh3.ko, 8723ds.ko, ... — a Go init can insmod(8) them straight from the stock files.
Partition table
**part** **name** **size** **notes**
-- (head) 36 MiB boot0, partition table; sectors 0-73727
p2 bootloader 32 MiB U-Boot; never touch
p3 env 16 MiB U-Boot environment; never touch
p4 boot 32 MiB Android boot image (kernel + ramdisk)
p5 system 1 GiB ext4
p6 vendor 240 MiB ext4
p7 misc 16 MiB bootloader_message
p8 recovery 32 MiB now TWRP
p9 cache 512 MiB ext4
p10 metadata 16 MiB
p11 private 16 MiB vfat, device-unique
p12 frp 512 KiB
p13 empty 15 MiB
p14 dto 16 MiB
p15 media_data 512 MiB
p1 UDISK 12.4 GiB f2fs, /data; at the end of the card
BACKUPS
~/tolino-backup/stock-16.2.1/
boot.img, recovery.img and the full official update-16.2.1.zip, with SHA1SUMS. Obtained without writing to the device; see GETTING THE STOCK RECOVERY WITHOUT ROOT.
~/tolino-backup/2026-10-31-twrp/parts/
Raw images of the head area and of p2–p15, taken from TWRP with all filesystems unmounted. Every image's SHA-1 was compared against sha1sum(1) run on the device's block device: all match. p4-boot-currently-twrp.img holds TWRP (boot was temporarily TWRP at the time); p8-recovery-currently-stock.img holds the stock recovery.
~/tolino-backup/2026-10-31-twrp/userdata.tar
File-level tar of /data (1.5 GB; 2.0 GB used of 12.4). Entry count matches the device except three sockets and one FIFO. Probably lacks SELinux labels: to restore Android fully, factory-reset and copy files back rather than restoring the tar over /data.
Not backed up: a raw image of p1, and the GPT backup header at the end of the
card.
A raw
dd(1)
of p1 through
adb exec-out
piped into zstd ran for 15 minutes and was aborted;
the file tar took 1.5 minutes.
RECOVERY
How to get back from anything short of a broken bootloader.
Buttons
From U-Boot's
_detect_bootmode()
(board/sunxi/common/ntx_comm.c),
for this board (hwconfig customer 32, PCB
0x60).
Start with the device off; holding power alone for 10 s powers it off.
Recovery (TWRP)
USB unplugged; hold lower page key + power, keep power held 4–7 s.
Fastboot
USB plugged in; hold lower page key + power. Power and USB without a page key is fastboot too.
Avoid
upper page key + power with USB: Allwinner efex flashing mode.
Commands
Into TWRP from the tolino OS
adb reboot recovery
Into fastboot from TWRP
adb reboot bootloader
Back to Android
fastboot flash boot ~/tolino-backup/stock-16.2.1/boot.img
Back to the stock kernel
after a boot image with our kernel (Building the kernel) does not come up: fastboot by the buttons, then
nix-build -A users.Profpatsch.tolino.os.bootImage
fastboot flash boot result
Restore stock recovery
fastboot flash recovery ~/tolino-backup/stock-16.2.1/recovery.img
Also rename recovery-from-boot.p.disabled back if Android should maintain it again.
Restore any partition
fastboot flash <name> ~/tolino-backup/2026-10-31-twrp/parts/pN-<name>.img
or dd(1) from TWRP.
Reinstall Android system/vendor
update-16.2.1.zip contains everything except recovery; TWRP can sideload it.
Last resort
Open the case, pull the internal microSD (breaks the IPX8 seal), write the images on the PC.
HOW WE GOT HERE
1. Research
Gemini search (see .claude/CLAUDE-search.md) plus fetching every cited URL, because two of Gemini's links were 404 and a third was an empty template. Facts that survived checking: B300 SoC, Kobo Sage uses the same SoC, FBInk supports "the sunxi one on Kobo", a TWRP port exists, Tolino publishes kernel and U-Boot sources at https://opensource.mytolino.com/portfolio-item/tolino-vision-6/.
2. Discovery over ADB, unrooted
ADB as uid 2000 can read most of /sys, /proc/partitions, getprop(1), getevent(1), and pull everything under /system and /vendor. It cannot read raw block devices, /proc/cmdline, or /proc/modules.
/dev/graphics/fb0
and
/dev/disp
are mode
0666,
but SELinux
(graphics_device)
still denies the shell; the permission bits lie.
The heart was therefore drawn by pushing a PNG and opening it in the installed
KOReader with
am start -a android.intent.action.VIEW -d file:///sdcard/Download/heart.png \
-t image/png -n org.koreader.launcher/.MainActivity
3. The display ABI is the Kobo Sage's
hwcomposer.virgo.so is closed and links bionic, libcutils and HWC2; reusing it verbatim would need libhybris. It does not need to be reused: it is a thin client of the GPL disp driver. Diffing Tolino's include/video/sunxi_display2.h, drivers/video/fbdev/sunxi/disp2/disp/dev_disp.c and de/include.h against FBInk's eink/sunxi-kobo.h:
DISP_EINK_UPDATE2 = 0x406, same seven-ulong argument block, samerotate-as-pointerquirk.enum eink_update_modeidentical, INIT 0x01 through GCC16 0xa0, AUTO, REGAL, NEGATIVE.disp_layer_config2,disp_layer_info2,disp_fb_info2,area_infoand the rect structs identical modulo brace style.- The same
DISP_EINK_SET_NTX_*extensions.
So KOReader's Kobo sunxi backend and FBInk should drive this panel unchanged on the stock kernel. Not yet verified on hardware: it needs root and Android's display stack stopped. The source tarball is dated 2026-10, the running kernel 2024-09; the interface is very likely unchanged, but only a test will tell.
4. FEL is a dead end (for now)
sunxi-fel(1)
does not know B300.
xfel detects it as
"A50"
but implements only read32/write32 — no DRAM init, no storage.
Tolino's U-Boot implements Allwinner's efex protocol, including
FEX_CMD_fes_up
(read flash sectors to host), reachable via
fastboot oem efex
or the recovery menu's
"EFEX"
entry; but no open-source host tool speaks it for this SoC.
Writing one is possible, from
usb_sunxi/usb_efex.c,
but was not needed.
5. Getting the stock recovery without root
- The update server serves every version at https://download.pageplace.de/ereader/<version>/OS81/update.zip (16.0.0–16.2.2 exist; nonexistent versions answer 404).
- The package has boot.img, system.new.dat.br, vendor.new.dat.br, U-Boot and per-board boot packages — but no recovery.
- Android rebuilds recovery from boot at every boot:
/system/bin/install-recovery.sh
(service
flash_recovery) applies /system/recovery-from-boot.p (an IMGDIFF2 patch) with bonus file /system/etc/recovery-resource.dat to the boot partition. Its arguments contain the expected hashes: bootdd2c4b73..., recovery 26116096 bytes,30e18b2d.... - The device's
applypatch
refuses non-EMMC targets, so
imgpatch.py
reimplements IMGDIFF2 + bsdiff on the host.
Output hash matches exactly.
Pitfall: the DEFLATE chunk's
src_expanded_lenmay or may not already include the bonus data.
6. The recovery saga
TWRP flashed to recovery with
fastboot flash recovery
succeeds, and is then
overwritten on the next Android boot
by
flash_recovery
(log:
"Installing new recovery image: succeeded").
The TWRP README's
"fastboot reboot, then adb reboot recovery"
cannot work as long as that service is enabled.
Things that did
not
get us into TWRP:
-
Writing
recoveryinto thebootloader_messagein misc. Generic sunxi code reads it ( set_bootcmd_from_misc() in board/sunxi/common/board_common.c), but on this board the Netronix code (_detect_bootmode(), ntx_comm.c) decides the boot mode from GPIO keys and USB, and the request was ignored. -
Holding power + page-down with USB connected: power + USB means fastboot on this board; the device ended up in fastboot, then Android, which restored stock recovery. Per the source, the recovery combination is power + page key without USB; untested.
-
fastboot boot: broken on this bootloader (README), andfastboot reboot recoverydoes not exist — the bootloader only knowsrebootandreboot-bootloader(usb_fastboot.c:1828).
What worked: flash TWRP into
boot,
fastboot reboot.
TWRP starts as the normal system; Android never runs.
From there: full backup, rename
recovery-from-boot.p,
dd(1)
TWRP into p8 (verified by hash), reboot to fastboot, flash stock
boot.img
back.
Android boots; its recovery restore fails; TWRP stays.
Fastboot notes:
getvar all
is unsupported;
secure: yes
is reported unconditionally, yet flashing works.
Flashing a file shorter than the partition writes only those sectors
(__flash_to_part()).
Max download size is 64 MiB.
THE BOOT CHAIN AND THE GO PLAN
U-Boot is the piece that cannot reasonably be replaced: it reads the Netronix
hardware config, loads the e-ink waveform into hidden memory and appends its
address to the kernel command line
(NtxHiddenMem_append_kcmdline()),
then boots an Android boot image
(magic
ANDROID!
header).
Fastboot lives inside it, so a damaged
boot
or
recovery
is always recoverable.
The plan, therefore:
-
Keep bootloader and env untouched, forever.
-
Reuse boot with the stock kernel and our own initramfs whose /init is a Go binary (gokrazy-style).
-
Develop in recovery: flash the experimental image there,
adb reboot recovery(or misc from the Go side) to try it; Android stays bootable in boot. Swap them once it works; put TWRP or stock recovery back. -
The Go init loads the stock modules from vendor/system, mounts UDISK (f2fs) for books, runs wpa_supplicant for Wi-Fi, handles suspend by writing
memto /sys/power/state, and supervises KOReader's Kobo (Linux, armv7) build, which already speaks this display ABI. system (1 GiB) can later become the root filesystem, since KOReader does not fit into a 32 MiB boot image.
What Android actually provides on this device, and what replaces it:
e-ink refresh
the HWC HAL; replaced by KOReader/FBInk speaking
DISP_EINK_UPDATE2directly.
suspend policy
wakelocks; replaced by KOReader deciding, kernel doing.
Wi-Fi
module load + wpa_supplicant.
USB file access
MTP; replaced by mass storage gadget or SSH.
ADB
replaced by SSH (KOReader ships dropbear).
updates, store
dropped deliberately.
What it costs: most of the 850 MB RAM, tens of seconds of boot, background
wakeups
(tolino.crashreporter, de.telekom.epub, com.ntx.msg).
DRAWING WITHOUT ANDROID
Verified 2026-10-31: FBInk draws on the panel from TWRP, with Android not
running, through
DISP_EINK_UPDATE2
on
/dev/disp
— the same path KOReader's Kobo build uses.
A full-screen GC16 clear, a full-screen image and text all work.
Building FBInk
Static armv7 musl, from FBInk master (886f25f) plus fbink-vision6.patch:
TC=$(nix-build '<nixpkgs>' --no-out-link \
-A pkgsCross.armv7l-hf-multiplatform.pkgsStatic.stdenv.cc)/bin
PATH=$TC:$PATH make static KOBO=true MINIMAL=true \
BITMAP=true IMAGE=true DRAW=true \
CROSS_TC=armv7l-unknown-linux-musleabihf \
AR=armv7l-unknown-linux-musleabihf-ar \
RANLIB=armv7l-unknown-linux-musleabihf-ranlib
armv7l-unknown-linux-musleabihf-gcc -static -LRelease \
-o fbink Release/fbink_cmd.o -l:libfbink.a -lm
The Makefile's own link is dynamic against a Nix store loader, hence the
manual static relink.
fbink_device_id.c
is
#included
into
fbink.c,
so make does not notice changes to it:
make clean
after editing it.
Running it
adb push fbink /tmp/fbink
adb shell 'stop recovery; ln -sf /dev/graphics/fb0 /dev/fb0'
adb shell '/tmp/fbink -c -f -W GC16'
adb shell '/tmp/fbink -g file=/tmp/heart.png -W GC16'
adb shell '/tmp/fbink -y -4 -m -S 3 "hello from FBInk"'
stop recovery
keeps TWRP's own UI from drawing over us.
The Kobo build hardcodes
/dev/fb0
(FRAMEBUFFER is honoured only by the generic Linux build);
Android puts it at
/dev/graphics/fb0.
Device identification
FBInk reads the Netronix hwconfig at sector 1024 of
/dev/mmcblk0
("HW CONFIG v3.5").
The Vision 6 has PCB id
0x60,
which is not in FBInk's
kobo_ids
table (the Epos 3 is
0x62,
mapping to the Sage).
It therefore falls through to
DEVICE_MAINLINE_GENERIC_SUNXI_B300
— correct SoC quirks, but
ntxBootRota
= FB_ROTATE_UR,
which is wrong for this panel.
The crash, and the fix
The panel is natively landscape (1680×1264); FBInk works in a portrait
1264×1680 buffer and passes the rotation to the kernel in
DISP_EINK_UPDATE2's
rotate
argument, computed as
((ntxBootRota - rotate) & 3) * 90.
With
ntxBootRota
= UR
it passed 0, i.e. claimed the portrait buffer was already in panel layout.
Bisected with
disp-probe.c,
a one-ioctl probe with no FBInk around it:
**buffer** **region** **result**
portrait, rot 0 1264x1265 and smaller ok
portrait, rot 0 1264x1600 and larger full reset
landscape, rot 0 1680x1264 (full) ok
portrait, rot 90 1264x1680 (full) ok
A "full reset" is a hard reboot of the SoC (USB drops, Android boots back in ~40 s, uptime 0, nothing in /sys/fs/pstore); presumably the driver walks past the end of its 1680×1264 working buffer. Partial updates that stay within 1264 rows never trigger it, which is why text worked and full-screen clears did not.
The fix
(fbink-vision6.patch)
sets
ntxBootRota
= FB_ROTATE_CW
for the generic B300 entry, as for the Sage and Epos 3, so FBInk passes
rotate=90.
The proper upstream fix is a
DEVICE_TOLINO_VISION_6
entry for PCB
0x60.
Orientation, as observed: in panel (landscape) coordinates, (0,0) is the
bottom-left corner of the device held in portrait;
rotate=90
with a portrait buffer puts (0,0) at the top-left, as expected.
Reading the screen back
The disp driver has an undocumented debug hook: reading
/sys/devices/virtual/disp/disp/waveform/get_working_buffer
writes the e-ink working buffer — what the panel actually shows — to
/mnt/flash/workingbuffer.bmp
(1680×1264, 8-bit; the directory must exist).
screenshot.sh
pulls it and turns it into a portrait PNG
(magick -flip -rotate -90):
BMP rows are bottom-up.
Verified pixel-identical against the physical screen.
Kernel command line
As passed by U-Boot (read from TWRP), abridged:
console=ttyS0,115200 root=/dev/mmcblk0p5 init=/init
partitions=UDISK@mmcblk0p1:bootloader@mmcblk0p2:...
cma=128M mem=1018M vmalloc=320M
hwcfg_p=0x7ffffe00 hwcfg_sz=110
waveform_p=0x7fabaa00 waveform_sz=5526360
ntxfw_p=0x7fab8400 ntxfw_sz=9474
androidboot.hardware=sun8iw15p1 androidboot.Wifi=RTL8723DS gpt=1
waveform_p/waveform_sz
is the 5.3 MB waveform U-Boot loaded into hidden RAM; the kernel picks it up
from there.
A replacement userland inherits all of this for free, since it is U-Boot
that assembles it.
KOREADER WITHOUT ANDROID
Verified 2026-10-31: the unmodified Kobo release of KOReader (v2026.07.1) runs on the device from TWRP, Android not running: it draws, reacts to touch and the page-turn and power buttons, follows auto-rotation, reads the battery, drives the frontlight, sleeps and wakes up, and opens the books.
./users/Profpatsch/tolino/koreader-push.sh
does all of the below; everything lands in RAM, nothing on the flash is written (the Android data partition is mounted, books read-only).
C library
The Kobo build is linked against glibc (needs
GLIBC_2.12,
libgcc_s, libstdc++ is bundled); TWRP is bionic and has no
/lib.
ld-linux-armhf.so.3,
libc, libm, libdl, libpthread, librt, libresolv, the two libnss and
libgcc_s come from
pkgsCross.armv7l-hf-multiplatform.stdenv.cc
and are unpacked into
/lib
(TWRP's rootfs is a writable ramfs), 2.9 MB.
The loader is invoked explicitly with
LD_LIBRARY_PATH,
because without an
ld.so.cache
its default search path is the Nix store it was built for.
adb exec-out
does not forward stdin; pushing a tarball through it hangs forever.
Use
adb push,
then unpack on the device.
Pretending to be a Kobo Sage
KOReader's Kobo device code is selected by the
existence
of
/bin/kobo_config.sh;
the codename comes from
PRODUCT.
cadmus
(Kobo Sage) fits best: same SoC, same disp ABI,
boot_rota
CW, and the same input layout
(event0
gpio-keys,
event1
touch)
.
The launcher also provides what Nickel would have:
- /mnt/onboard as a RAM directory with a stub .kobo/Kobo/Kobo eReader.conf (KOReader asserts on it while syncing the frontlight) and .kobo/version, so settings and caches never touch the real data partition;
- /data/media/0/Books bind-mounted read-only at /mnt/onboard/Books;
- the
/dev/fb0symlink andstop recovery, as for FBInk.
The launcher must not be started with /system/bin/sh (absent in TWRP); TWRP's shell is /sbin/sh.
Touch
The Elan panel's raw coordinates, measured by tapping the four corners in portrait:
**corner** **raw (x, y)**
top-left (1600, 51)
top-right (1618, 1162)
bottom-right (41, 1201)
bottom-left (65, 84)
So raw x runs along the long edge from bottom to top, raw y along the short
edge from left to right, and portrait
(x, y) = (raw_y, 1679 - raw_x):
swap axes, mirror the new Y.
That is KOReader's
touch_mirrored_y
mode; the Sage profile has
touch_mirrored_x
instead, so taps landed mirrored.
koreader-patches/1-tolino-vision6.lua
flips the two flags, maps the page-turn keys
(see Buttons),
and disables the Sage's PowerCover battery and NaturalLight.
It must patch the class returned by
require("device/kobo/device")
—
require("device")
already runs
init(),
which builds the touch transform.
Under TWRP a second touch driver appears,
gt82x
on
event4;
the hardware is the Elan.
Raw events can be recorded with
cat /dev/input/event1 > file
(TWRP has no
getevent(1)).
Buttons
Power (sleep) and the accelerometer-driven rotation work as on a Sage.
The page-turn keys do not out of the box: the tolino's gpio-keys report
KEY_UP
(103) and
KEY_DOWN
(108), a Kobo's report 193/194, and the Kobo
event_map
knows only those.
The userpatch wraps
Kobo:init()
(where the map is built) and maps 103 to
RPgBack,
108 to
RPgFwd.
Upper key goes back, lower forward, as on the stock firmware.
The cover's magnet is a hall sensor on
event0.
Tolino's gpio-keys driver reports it as the key
KEY_H,
except when the hwconfig says Android UI (as here): then it becomes the switch
SW_LID
(EV_SW, value 1 when closed)
(drivers/input/keyboard/gpio_keys.c).
KOReader's Kobo code knows the sleep cover only as a key (35 or 59) and drops
EV_SW
events, so the cover did nothing.
The userpatch rewrites
SW_LID
into key 59, value kept, which makes it KOReader's SleepCover: closing
suspends, opening wakes, and the
"Ignore sleepcover"
settings apply.
The update nag
Started without its own koreader.sh, KOReader shows "startup script has been updated" on every start: Kobo:isStartupScriptUpToDate() compares /tmp/koreader.sh, which koreader.sh leaves behind as the active copy, against the shipped one. The launcher copies the shipped one there.
Frontlight and sleep
Both work unchanged with the Sage profile. The frontlight goes through /sys/class/backlight/mxc_msp430.0/brightness, which the tolino has too (next to the LM3630A nodes). Power button suspend and wake-up from it work.
Wi-Fi (plan, not yet tried)
Everything needed is on the device, in vendor:
driver
/vendor/modules/8723ds.ko (3 MB, the Realtek out-of-tree driver)
firmware
/vendor/firmware/rtl8723ds_fw, rtl8723ds_config
supplicant
/vendor/bin/hw/wpa_supplicant (bionic; on a glibc/Go userland use our own build instead)
Android loads it with one line (/vendor/etc/init/hw/init.RTL8723DS.rc):
insmod /vendor/modules/8723ds.ko ifname=wlan0 if2name=p2p0
and runs
wpa_supplicant -Dnl80211 -iwlan0.
That is not all, though.
Tried 2026-11-02 under the tolino OS (generation 12, with our module and
with the stock one alike): the module loads
("RTW: module init ret=0"),
but no SDIO card appears on the bus and no
wlan0
is created.
Something Android does before the insmod powers the chip and rescans the
SDIO host; the kernel logged
"sunxi-wlan wlan: get gpio chip_en failed"
at boot, so it is not the
wlan
platform device on its own.
Unlike Kobo there is no
sdio_wifi_pwr.ko
or
ntx_io
208 to call.
rfkill0
is Bluetooth, not Wi-Fi.
The kernel must find the firmware: either
/vendor
mounted at its usual path, or
/lib/firmware
populated.
KOReader's Kobo
enable-wifi.sh
expects
/drivers/$PLATFORM/$WIFI_MODULE.ko,
wpa_supplicant -D wext,
and
dhcpcd
or
udhcpc
— none of which TWRP or the Go init provides.
The Go init should own all of it instead, and give KOReader two tiny
scripts that ask it: load the module and start a statically linked
wpa_supplicant(8)
(-D nl80211),
control socket in
/var/run/wpa_supplicant/wlan0,
which KOReader's network menu talks to directly to scan and pick networks;
then a DHCP client — written in Go, or busybox
udhcpc.
Networks are stored in a
wpa_supplicant.conf
on the data partition, never in this repository.
Off means off: on disable,
rmmod 8723ds,
which also cuts the chip's power.
That matters for battery and for
SECURITY.
Not yet tested
Wi-Fi, USB mass storage. Under the tolino OS, KOReader's USB mass storage mode would need the gadget to switch functions; untried.
THE TOLINO OS
Since 2026-10-31 the tolino boots its own system from the boot slot: s6-linux-init as PID 1, s6-rc for services, KOReader, and one Go binary, tolino-sys, for everything that would otherwise be a shell script. Built by Nix in os/; working notes in os/DESIGN.md.
Boot chain
- U-Boot loads boot: our 4.9.337 kernel (or our 4.9.56 build, or the stock one; see Building the kernel) and an initramfs that holds only tolino-stage1 (os/stage1/) as /init, and /dev/console.
- stage1 mounts proc, sys, devtmpfs and the data partition (/dev/mmcblk0p1, f2fs), picks a generation, loop-mounts its system.img read-only, moves /data, /dev, /proc, /sys below it, and switches root to its /sbin/init.
- s6-linux-init starts s6-svscan;
rc.init
(
tolino-sys rc-init) brings s6-rc'sdefaultbundle up.
The boot image changes only when stage1 or the kernel does. Everything else is a generation. That is why tolino-stage1 is a program of its own and not an applet of tolino-sys: as an applet, every change to adbd or the KOReader setup changed the initramfs too, and with it the one image that, when broken, needs fastboot instead of falling back to current. Being apart also keeps /init small: 1.8 MB instead of 2.5 MB (750 KB instead of 1.1 MB in the gzipped initramfs), since adbd's RSA and crypto stay out of it.
Generations
/data/tolino/generations/<N>/system.img
one per build, a read-only squashfs image (ext4 up to generation 8)
/data/tolino/current
symlink to the generation to boot
/data/tolino/try
optional symlink: boot this one once. stage1 deletes it before switching, so a generation that hangs falls back to current on the next reboot.
tolino.generation=<N>
on the kernel command line, overrides both
Installing a generation, from the running system or TWRP:
nix-build -A users.Profpatsch.tolino.os.image
adb shell mkdir -p /data/tolino/generations/5
adb push result /data/tolino/generations/5/system.img.new
adb shell sha256sum /data/tolino/generations/5/system.img.new
adb shell 'cd /data/tolino &&
mv generations/5/system.img.new generations/5/system.img &&
ln -sfn generations/5 try && sync'
adb reboot
# booted fine:
adb shell 'cd /data/tolino && ln -sfn generations/5 current'
Check the checksum on the device against the host's before the
mv:
a push interrupted by a USB drop leaves a partial
*.adbtmp
behind, and an image that only half arrived would boot into the recovery
fallback.
If stage1 cannot boot anything it logs, waits 10 s and reboots
into recovery:
reboot()
with
LINUX_REBOOT_CMD_RESTART2
and
"recovery",
which the PMIC driver
(drivers/mfd/ricoh619.c)
turns into U-Boot's recovery flag
0x5C.
A plain reboot would loop into the same failure.
stage1 writes its log to /data/tolino/stage1.log, read from TWRP or the running system. Nothing else from a boot survives it: the kernel log, and the s6 log in /run/uncaught-logs, are in RAM, and the serial console needs soldering. See Where the logs go.
The system image
No /nix/store: every file is copied into a flat tree, and the builder fails if any store path remains.
/bin
skarnet (static musl, prefix /), tolino-sys, the fake kobo_config.sh
/sbin
links into /etc/s6-linux-init/current/bin: poweroff(8), reboot(8), halt(8), shutdown(8)
/opt/busybox/bin
busybox and its applets, for
adb shellonly; see Shutting down
/etc/s6-rc/compiled
the service database, compiled at build time
/etc/adb_keys
the host keys adbd accepts
/lib
armhf glibc and libgcc_s for KOReader
/lib/modules
the modules from our kernel builds, one directory per release (Building the kernel)
/lib/firmware
Wi-Fi firmware, extracted from the public OTA at build time
/opt/koreader
the unmodified Kobo release, plus tolino-patches/
The image is made from a tar stream, so everything is owned by root and the two FIFOs s6-linux-init-maker creates exist; the store can hold neither. The tar has no entry for / itself, so its owner and mode are set explicitly; left alone, sqfstar(1) makes it the build user's and 0777.
It is squashfs, lz4-compressed, with every timestamp 0, so it is reproducible: 71 MB where the same tree as ext4 took 164 MB. lz4 because it decompresses fastest on the Cortex-A7 and KOReader reads many files at startup; gzip would give 53 MB, xz 44 MB. Squashfs needs our kernel (Building the kernel), built in rather than as a module, since stage1 mounts the image before any module is loaded.
Generations up to 8 are ext4, and stage1 mounts either kind, telling them
apart by their magic number
(hsqs
for squashfs,
0xEF53
at offset 1080 for ext4)
,
so generations 4–8 stayed bootable as fallbacks; they are deleted, but
stage1 still mounts either kind.
Those ext4 images used only the features of Tolino's own partitions: the
stock kernel refuses a current mke2fs's defaults
(metadata_csum, 64bit)
with
EINVAL,
while TWRP's kernel accepts them.
Services
mount-tmp
tmpfs on /tmp and /mnt/flash, devpts on /dev/pts, debugfs on /sys/kernel/debug, for the disp driver's dispdbg and other debug nodes; see E-ink power
pstore
copies the previous kernel's pstore records to /data/tolino/pstore/<time>/, see Where the logs go
sysctl
/proc/sys/kernel/sysrq to 0, see SECURITY
modules
loads /lib/modules/load-order, from /lib/modules/<release>/ of the running kernel, or once from /data/tolino/test-modules/<release>/, see Testing a module
display
checks /dev/fb0, /dev/disp, /dev/ion
koreader
longrun: the KOREADER WITHOUT ANDROID setup, settings in /data/tolino/koreader
usb-gadget
configfs gadget with one functionfs function
adbd
longrun, see below; independent of KOReader
Every
up
and
run
is one command line,
/bin/tolino-sys <applet>.
Logs go to s6-linux-init's catch-all logger,
/run/uncaught-logs/current.
PID 1, and so every service, has
PATH=/sbin:/bin.
Testing a module
A module can be tried without building a generation: put it into
/data/tolino/test-modules/<release>/
and reboot.
tolino-sys modules
loads every module the load order names from there if it is there, and
from the generation otherwise, logging
"TEST OVERRIDE, this boot only".
It cannot add modules or change their order.
Like try, the directory is used once: it is renamed to <release>.used, and the rename synced, before the first module loads. That matters for disp.ko above all: stuck in its init, it also blocks every reboot, so a broken one must not come back; after a forced reboot the generation's modules load again. To repeat a test, rename .used back. Where the test directory cannot be read or renamed, the boot ignores it.
disp.ko
for it comes from an incremental kbuild of the same source as
os.kernel,
see
The disp module;
verified 2026-11-03, generation 15.
Where the logs go
Into RAM, nearly all of it; the internal microSD sees only stage1.log, about 1 KB per boot, and KOReader's settings.
kernel
the 512 KB ring buffer (dmesg(1)) and the serial console
ttyS0, atloglevel=7, both from the boot image's command line. Most of a boot's 1600 lines are vendor drivers: the probe failures of sensors, PMICs and touch controllers that this board does not have (gsensor, jd9930, sy7636, NAND, GT9xx), and debug lines per touch (elants) and per refresh (papyrus). The stock kernel under Android logs the same; Android's saved kernel logs on the cache partition have them too.
s6 services
s6-linux-init's catch-all logger, /run/uncaught-logs/current, on tmpfs.
stage1
/data/tolino/stage1.log, replaced at every boot.
What survives a reboot is pstore: the device tree reserves 384 KB at
0x48106000
for ramoops
(ramoops: attached 0x60000@0x48106000),
and since generation 31 the
pstore
service copies whatever the previous kernel left there to
/data/tolino/pstore/<time>/,
keeping the newest 20, so nothing has to be read by hand before the next
reboot overwrites it.
Whether there is anything depends on how the board was reset.
In a test on 2026-11-02 (generation 9) pstore stayed empty after
adb reboot
and after a panic; on 2026-11-06 (generation 31) ordinary reboots did
leave the previous console, so the PMIC reboot below evidently does not
always lose RAM.
Do not rely on it; rely on the watchdog.
A reboot here is not a warm reset: the PMIC driver's
ricoh619_restart()
(drivers/mfd/ricoh619.c)
ends in a loop that powers the board off and lets the Ricoh619 power it
on again 1 s later
(RICOH61x_PWR_REP_CNT),
and the reboot after a panic
(kernel.panic=5)
takes the same path, since that function is
arm_pm_restart.
DRAM can lose its contents, and ramoops with it.
The B300's internal reset, which would keep it, exists in that function
only under
SUNXI_BOOTFLAG_BY_RICOH==2;
the source sets 1.
The SoC's own watchdog does keep it.
Opening
/dev/watchdog
(sunxi-wdt, 16 s, nowayout)
and not feeding it resets the SoC without the PMIC cutting power, and the
next boot finds the previous kernel's console in
/sys/fs/pstore/console-ramoops-0,
messages written to
/dev/kmsg
just before included, and
/dev/pmsg0
in
pmsg-ramoops-0
(tried 2026-11-06).
That is the debug channel for kernels started by kexec
(Towards mainline):
arm the watchdog, kexec a kernel with
panic=0,
and whatever it printed before it hung or panicked is in pstore on the next
boot.
The watchdog stays armed across kexec since patch 0028
(the vendor driver stopped it at shutdown).
It does not stay armed into a 4.9.337 test kernel: that kernel's sunxi-wdt
probe stops it again, unless it boots with
initcall_blacklist=sunxi_wdt_driver_init.
pstore's compressed panic record (dmesg-ramoops-0.enc.z) does not decompress here ("decompression failed"), neither the previous 4.9.337's nor a mainline kernel's (raw deflate, where 4.9 expects zlib with a 4 KB window); the console record is plain text.
E-ink power
The panel's drive voltages come from an SY7636 PMIC (drivers/hwmon/sy7636.c), which the disp driver switches per update: before one, EINK_power_on() (disp/lcd/default_eink.c) cancels a pending power-off and powers the PMIC up unless it is still on; after one, EINK_power_off() schedules the power-off powerdown_delay later, 500 ms by default (/sys/class/disp/disp/waveform/powerdown_delay), in ms despite printing "us". Android leaves it at that. Within that window, the next update reuses the running rails. The SY7636 driver then keeps XON, which holds the panel's gate lines, on for another 2.45 s (dmesg: "daymode XON OFF after 2450000 us").
KOReader's Kobo sunxi backend additionally writes
lcd0, enable, 1
to
/sys/kernel/debug/dispdbg/{name,command,start}
before every refresh, which ends in
EINK_pmic_force_onoff():
a second, asynchronous power-on next to the driver's, with a second
power-off timer.
KOReader's own comment calls it a
"vague hope"
against missed refreshes after standby.
Up to generation 9 debugfs was not mounted and every one of those writes
failed into the log; since generation 11 the userpatch sets
mech_poweron
to nil, and power is the driver's alone, as under Android.
Shutting down
There is no
/bin/sh.
Busybox lives in
/opt/busybox/bin,
and only adbd puts it on
PATH,
after
/sbin
and
/bin.
That is deliberate.
When busybox was in
/bin,
its
poweroff(8)
was the system's.
Busybox built with its own init signals PID 1 by busybox init's numbering
(halt
SIGUSR1,
poweroff
SIGUSR2,
reboot
SIGTERM);
s6-linux-init's is different (poweroff
SIGUSR1,
halt
SIGUSR2,
reboot
SIGINT,
SIGTERM
ignored).
So KOReader's
"Power off"
halted the CPU without telling the PMIC: the frontlight stayed on under the
"Powered off"
screen.
Its
"Reboot"
did nothing.
In both cases s6 then restarted KOReader.
Without a /bin/sh, KOReader's os.execute() and io.popen() fail, and they fail silently. The userpatch replaces the calls that matter:
- Kobo:powerOff()
and
Kobo:reboot()
write
powerofforrebootto /run/koreader-halt; KOReader then quits with itsKO_RC_HALT, 88. Thekoreaderservice's finish,tolino-sys koreader-finish, sees 88, runss6-linux-init-hpr -por -r, and exits 125, so s6-supervise does not restart KOReader over its "Powered off" screen. s6-linux-init then stops the services, kills everything, unmounts and calls reboot(2); for power off the kernel hands that to the Ricoh619 PMIC. Verified 2026-10-31 (generation 5): the frontlight goes out, also with USB plugged in, and the power button cold-boots the device; reboot comes back in about 40 s. - the
syncbefore every suspend calls sync(2) through ffi.
Still broken for the same reason: setting the date and time
(date, hwclock),
the Wi-Fi scripts, and the
ping
connectivity check.
These belong in
tolino-sys
once Wi-Fi exists.
adbd
tolino-sys adbd
implements the device side of adb in Go; Android's adbd would mean building
a slice of AOSP.
Supported:
shell
(v2, with a pty when interactive, running busybox
/opt/busybox/bin/sh
with
PATH=/sbin:/bin:/opt/busybox/bin),
exec,
sync
(push, pull, stat, list, including the v2 variants) and
reboot,
reboot:recovery.
Authentication is RSA against
/etc/adb_keys
(os/adb_keys, the host's ~/.android/adbkey.pub);
unknown keys are rejected, there is no on-screen confirmation.
The USB IDs are those Android used,
4173:8000,
with the serial number from the kernel command line.
The functionfs instance stays open for the daemon's whole life: closing
ep0
removes the USB function and the device re-enumerates.
The host resets the bus once right after enumeration and on
adb kill-server;
the bulk endpoints then fail with
ECONNRESET
or
ESHUTDOWN,
and adbd re-opens only those, after the next ENABLE event.
Even so the device is listed briefly, then reappears with a new transport
id: use
adb wait-for-device
after a reboot.
Shell sessions
The shell service follows AOSP's
daemon/shell_service.cpp;
each place ours used to differ from it was a bug.
A session runs on a pty (interactive
adb shell,
or forced with
-t)
or on pipes (a command), always in a session of its own.
The pty gets the client's window size and follows it on resize.
TERM
is the client's, or
dumb
if it sends none.
Exit codes are the shell's, or 128 plus the signal that killed it.
The session ends when its output does, not when the shell exits.
On pipes that is end of file.
On a pty it is
EIO
on the master, which comes once
every
process holding the terminal has closed it.
So
adb shell -t 'job &'
lasts as long as the job does, as it does against Android.
Before this, adbd sent the exit code 50 ms after the shell exited and
dropped whatever came later.
With a pty, the client's
"stdin closed"
message is ignored, as upstream does: a pty cannot close only its input, and
closing the master hangs up the shell.
That message comes right away whenever the client's own stdin is not a
terminal, so
adb shell -tt cmd
used to lose all output after the first moment, and the exit code with it.
When the host goes away (the adb client is killed, or the cable is pulled),
the session's process group gets
SIGHUP
and its pipes are closed, so a child that ignores the signal cannot block
writing to a full pipe.
With shell protocol v2 that is the stream ending, since v2 has a separate
message for end of input.
Without the protocol
(exec:, that is adb exec-out and exec-in)
the two cannot be told apart.
adbd treats the end of the stream as end of input first, so
exec-in 'cat > file'
gets everything, and hangs up whatever is still running 10 s later.
A child that writes is hung up sooner, when its write to the host fails.
Before this, an
adb shell top -b
interrupted on the host kept running on the device for good.
Building
depot.users.Profpatsch.tolino.os.image
the generation image
depot.users.Profpatsch.tolino.os.bootImage
the boot image, stock kernel
depot.users.Profpatsch.tolino.os.bootImageOwnKernel
the same with our 4.9.337 kernel; what the device boots
depot.users.Profpatsch.tolino.os.kernel
our 4.9.337 kernel: Image, Module.symvers, config, kernel.release, System.map, lib/modules/
depot.users.Profpatsch.tolino.os.kernelCheck
the checks on it, as a report
depot.users.Profpatsch.tolino.os.kernel4956, kernelCheck4956, bootImageOwnKernel4956
the same for Tolino's tree as published, 4.9.56; the fallback
depot.users.Profpatsch.tolino.sys
tolino-sys alone
depot.users.Profpatsch.tolino.stage1
tolino-stage1, the initramfs /init, alone
Every build step is a Go program in
os/build/
run by
runGoCommand(7).
C (skarnet, busybox) is compiled with
zig cc:
the pinned nixpkgs has no cached cross gcc for static armv7 musl, and zig
ships musl for every target.
tolino-sys
and
tolino-stage1
are cross-compiled with
buildGo.forSystem,
see
buildGo(7).
Build-time workarounds, each commented where it is made:
s6-linux-init-maker's setgid directory (the sandbox forbids setgid);
skarnet's
*.a.xyzzy
libraries, which zig's linker refuses by extension; busybox's GNU-ld-only
link flags; glibc's compiled-in store prefixes, overwritten with as many
slashes.
Busybox is built with
-DBB_GLOBAL_CONST=
(empty).
It declares the pointers to its per-applet globals
const,
which lets gcc keep them in a register, and assigns them once at applet start.
zig cc is clang, and clang reuses a load of such a pointer from before that
assignment.
Every applet with its own globals struct then dereferenced NULL:
top,
awk,
diff,
less,
vi,
netstat,
wget,
hush
and others crashed at once.
The busybox ash, which is
adb shell,
was not affected.
Busybox's own clang workaround in
include/libbb.h
does not catch this case.
Building the kernel
There are two kernels, built the same way from different sources:
os.kernel
4.9.337: Tolino's vendor tree merged onto Google's last 4.9 branch, see The 4.9.337 merge. What the device runs since 2026-11-03.
os.kernel4956
4.9.56: Tolino's published source (linux-4.9.tbz, fetched by hash) as it is, plus three build fixes (os/kernel/patches/). Bit-identical to the kernel the device ran from 2026-11-02 to 11-03, and the fallback.
The tarball is 186 MB of bzip2 and unpacked with
lbzip2(1):
plain bzip2, as
tar -j
runs it, is single-threaded and took 33 s, the longest serial step of
the build; lbzip2 takes 3.7 s on 16 threads, for the same bytes (both
kernels came out bit-identical after the switch).
Both use the stock configuration plus ours.
No full configuration is committed: a generated
.config
says
"DO NOT EDIT",
and a hand-edited copy would hide which of its 4300 lines are ours.
The base is the configuration the stock kernel carries in itself
(CONFIG_IKCONFIG),
extracted at build time from the kernel in the OTA, so it is by
construction what the device ran (and what
/proc/config.gz
showed under Android).
On top goes
os/kernel/config.fragment,
one commented line per change, merged as
scripts/kconfig/merge_config.sh
does and resolved by
make olddefconfig.
The build fails if a fragment line does not survive that with its value
(a missing dependency drops it silently) or restates the stock value.
With an empty fragment the 4.9.56 kernel is bit-identical to the one built
from the full stock configuration.
os/kernel/4.9.337/config.fragment
holds what only 4.9.337 changes, on top of the shared fragment, with the
same checks; a symbol set in both fails the build.
The 4.9.56 fallback has to keep loading the stock modules
(kernelCheck4956),
and the stock
disp.ko
imports vendor ION, so ION can go only from 4.9.337; see
/dev/ion without ION.
The compiler is Bootlin's prebuilt armv7 glibc toolchain, GCC 9.3 (os/kernel/toolchain.nix). Tolino used Linaro GCC 5.3, whose downloads are gone; the pinned nixpkgs has no GCC below 13, and 4.9 with a current GCC needs workarounds in vendor code that only the device would show to be wrong. GCC 9.3 builds the tree with three build-system patches: /bin/pwd and /bin/false, which NixOS lacks, and the NAND Makefile, which breaks out-of-tree builds.
The boot image gets the uncompressed
Image,
as the stock one does (16 MB, plain ARM code at offset 0, no zImage magic);
a zImage is not what this U-Boot is known to boot.
Compressing in a later step would not be cheaper: a zImage is a decompressor
linked around the kernel by kbuild, not
gzip Image.
Two more fixes are made by os/build/kernel.go rather than as patches. Tolino built in the source tree and published it that way: its generated headers are deleted, or kbuild refuses to build next to them. And the disp module links a closed e-ink library, de/libeink.a, which the tarball ships only in per-board variants; the build uses libeink-E60P74.a_shipped, the only variant whose functions all match the stock disp.ko by name and size. The source is unpacked to lichee/linux-4.9, where the tarball has it: the path ends up in the kernel (the file names in WARN() and BUG()).
The release string is the plain version, the build user, host and date are
fixed, and
SOURCE_DATE_EPOCH
covers the Realtek drivers'
__DATE__:
two builds are bit-identical
(nix-build --check).
os.kernelCheck
judges the result without rebuilding it, so a new check costs a second, not a
kernel build.
It fails unless the release is the expected one and every symbol CRC our
modules import
(__versions)
equals the kernel's
(Module.symvers).
The kernel is built with
CONFIG_MODVERSIONS,
so these CRCs are what
insmod(8)
compares; a mismatch shows up here, not on the device.
kernelCheck4956
also checks the stock modules from the OTA, so that kernel stays
interchangeable with the stock one: as of 2026-11-03
disp.ko
216,
ed070kh3.ko
4,
sunxi-keyboard.ko
33,
8723ds.ko
225 imports, none differing.
The stock modules cannot load into 4.9.337 at all (vermagic).
Each boot image depends on its kernel's check, so a kernel that fails is
never packaged.
The report also lists every configuration symbol that differs from stock:
the fragment's lines and what
olddefconfig
changed because of them.
Generations ship our modules, built with the kernels, one set per release
in
/lib/modules/<release>/;
tolino-sys modules
loads the running kernel's set.
So one generation boots on either boot image, and flashing the other boot
image is a complete fallback.
Our modules are built from the same sources as Tolino's: on 4.9.56 the same
modinfo
except
srcversion,
the same imports, and the same RTL8723DS driver release
(v5.13.5-29-g0dbf6713f.20210604);
the defined symbols differ only in what GCC 9.3 inlines where Linaro
GCC 5.3 did not.
Its
"EInk_Init failed, the regal will be invalid, ret=1"
is not ours: the stock kernel logs it too, at every boot (14 times in
Android's saved kernel logs on the cache partition, backup
p9-cache.img).
It is the E60P74 library linked into
disp.ko
refusing this panel's waveform, and it does not matter:
ed070kh3.ko,
loaded next, registers the panel's own library
(libeink_ed070kh3.a),
whose init succeeds
("ed070kh3 panel match eink library version = 0x134659e")
and sets up the GLR16 and GLD16 waveforms.
That library is the REGAL processing KOReader asks for with every page turn
(GLR16 plus EINK_REGAL_MODE);
it is closed, but plain ARMv7/NEON computation, about 10 KB, with no kernel
imports.
Do not drop
ed070kh3.ko
on the theory that REGAL never initialises; that was tried and undone on
2026-11-03.
The disp module
The tolino OS needs only the e-ink path of Allwinner's disp2 driver:
os/kernel/4.9.337/patches/0007
removes the twelve LCD and MIPI-DSI panel drivers for other boards
(the device tree's lcd_driver_name is default_eink);
the module shrinks by 60 KB.
0008 replaces
do_gettimeofday()
and
struct timeval,
gone since Linux 5.0, by
ktime_get()
and
ktime_t:
the driver only ever measures intervals, now on the monotonic clock, so
the ones that steer it (the wait for VEE before powering off, the time
since the last update) no longer jump with the wall clock.
0009 drops the panel GPIOs
(lcd_gpio_N,
lcd_bl_en,
edp_bl_en)
:
Allwinner reads them with
of_get_named_gpio_flags()
and a six-cell specifier whose flags its pinctrl driver fills with mux,
pull, drive strength and level, then configures them by pin name with
pin_config_set();
current kernels have none of it.
No tolino device tree has these properties; the lookups ran and failed at
every boot, and the panel's power is the SY7636's.
A device tree that has one now gets a warning.
The two output GPIOs without a label in
/sys/kernel/debug/gpio
(38, 354) are not disp's: they stay claimed with
disp.ko
unloaded.
0010 replaces ION, which current kernels dropped: the e-ink buffers
(images, index, working, mode and wave data buffers, the waveform) came
from its carveout heap, cached, and were synced by
dmac_flush_range().
dma_alloc_coherent()
looks like the replacement but is uncached on ARM, and the CPU computes on
these buffers: the index step of a page turn went from about 30 ms to
400–700 ms.
So the pages and their IOMMU mapping come from
dma_alloc_attrs()
with
DMA_ATTR_NO_KERNEL_MAPPING,
the kernel maps them cached with
vmap(),
and a sync is
dma_sync_sg_for_device()
with
DMA_BIDIRECTIONAL
over the pages in range, one clean+invalidate pass as before.
The e-ink interrupt syncs too, so the buffer list is under a spinlock.
Measured over 32 injected page turns: 24–35 ms with ION,
27–39 ms now; a full refresh of the same page is pixel-identical.
0011 and 0012 are about the buffers KOReader and FBInk hand the driver,
and about the cache.
Current kernels have no
dma_buf_kmap();
disp maps them with
dma_buf_vmap()
now, which ION here did not offer: 0011 adds it to ION, on top of the
same refcounted kernel mapping.
That is a change to the kernel, not the module, so
Image
changes with it
(Module.symvers
does not)
.
The driver also flushed the whole CPU cache, outer cache included, in
eight places; 0012 replaces each by the maintenance it was for:
dma_buf_begin_cpu_access()
on the userspace buffer the CPU is about to copy,
disp_eink_cache_sync()
on the rows dithering or gamma correction wrote, and nothing where the
buffer was already synced or the hardware reads through
dma_buf_map_attachment().
They are the start of the work towards a newer kernel
(NEXT STEPS):
0013 removes three more: the LCD backlight PWM, requested by number with
pwm_request()
but never configured or enabled here (the frontlight is the LM3630A);
vfs_write()
under
set_fs()
in the debug dumps, now
__kernel_write()
(on 4.14 and later
kernel_write());
and
__clk_get_enable_count(),
which the driver used both to ask whether a clock runs, now
__clk_is_enabled(),
and to pair its own enable and disable of the LCD clock, now a flag:
U-Boot leaves that clock prepared but with no enable count.
0014 to 0017 are small: the hrtimers go through one helper that is
hrtimer_setup()
from 6.15 on, and
class_create()
loses its owner argument from 6.4 on, both chosen by kernel version; the
check that the SoC's efuse chip ID is one of two values
(sunxi_efuse_readn()),
a guard against other SoCs, is gone; and
disp_suspend()
no longer reads the vendor's
gSleep_Mode_Suspend,
set through
/sys/power/state-extended.
KOReader writes 1 there before every suspend, so the branch it selected
— refuse to suspend while VEE has not settled since the panel's last
power-off — is the one that ran on every suspend, and now runs
unconditionally.
0018 drops disp's fallback to a second e-ink PMIC, the JD9930, which it
called wherever the SY7636 driver had not registered or answered with an
error; the tolino has no JD9930.
The fallback is behind
DISP_JD9930,
undefined, rather than gone with
CONFIG_JD9930_VCOM:
the kernel keeps the JD9930 driver, because the stock
disp.ko
imports it, and
kernelCheck4956
requires the stock modules to load into the 4.9.56 kernel.
0019 makes Allwinner's NEON helpers (waveform lookup, index bit
reduction, mask combine, ARGB to gray), until then the exports of a
separate driver,
drivers/video/fbdev/encode,
part of
disp.ko
as
de/eink_neon.c,
built with what current kernels call
CC_FLAGS_FPU.
The kernel keeps building that driver, for the stock
disp.ko
again.
The compiler's own
<arm_neon.h>
lives under the toolchain's store path, which then ended up in the debug
information: the generation builder, which refuses any store path in the
system image, caught it; the Makefile maps it to
/cc/include.
0020 replaces
gptHWCFG,
the vendor kernel's exported pointer to the Netronix hardware config:
disp makes its own read-only copy at probe from the same
hwcfg_p=/hwcfg_sz=
on the command line, with
memremap().
0021 puts the two remaining calls into Allwinner's kernel behind
disp_soc.h:
the IOMMU's per-master bypass
(sunxi_enable_device_iommu())
and the pin banks' 1.8 V/3.3 V power mode
(sunxi_sel_pio_mode()),
3.3 V here; on 4.9 they call the same, a port changes that file only.
0022 does the same for the e-ink PMIC: power, VCOM and temperature go
through
disp_epd_power.h,
which on 4.9 calls the vendor's SY7636 driver
(register_ebc_pwr_ops(), the tps65185_*())
functions);
on mainline it would sit on the sy7636a regulator and hwmon drivers.
0023 adds rotation on the CPU next to g2d.
Every update KOReader draws in portrait
(rotate=90)
is rotated into the panel's landscape layout before anything else; the
vendor does that with g2d, Allwinner's 2D blitter, whose driver current
kernels lack.
waveform/rotate_method
chose:
0
g2d
1
the whole image on the CPU, NEON 8×8 transposes in 64×64 tiles
2
the previous image copied into the ring slot, only the update area rotated
3
the last rotated image kept, and a spare buffer prepared from it in the background after each update; the next partial update swaps the spare into its slot and rotates only its own area; 4 MB more
10 to 13 select the same and record each rotation's time, read from
waveform/rotate_times
(printing them would time the serial console at
loglevel=7)
.
Per update, at rotation 90, measured 2026-11-05:
**full screen** **small area**
g2d 2.6ms 2.6ms
method 1 12.3ms 12.3ms
method 2 25.6ms 2.6-3.4ms
method 3 14.1ms 0.6-1.9ms
Of method 3's full update, 11.5 ms is the transpose writing scattered cache lines, 0.7 ms the cache write-back. A page turn is a full update.
0024 makes method 3 the only rotation and removes g2d: no g2d_module_*() imports, no linux/g2d_driver.h; the rotation flags disp passes around keep their values in de/eink_rotate.h. A page turn's rotation costs 14 ms instead of 2.6, not visible when reading (tested on the device, with night mode, rotation and a real suspend); partial updates got faster, and a full refresh of the same page is pixel-identical to g2d's. waveform/rotate_method became waveform/rotate_log: 1 records each rotation's time ("full" or "partial", area, μs) for waveform/rotate_times. Colour (CFA) panels rotated their 32-bit images with g2d; that now warns once and leaves them unrotated. The tolino has none: its hwconfig's EPD flags are 0x10, CFA is 0x08.
rotate-test.c
checks the methods on the panel: with KOReader stopped
(s6-rc -l /run/s6-rc -d change koreader),
it draws a full-screen pattern and eight partial updates (corners, centre,
an odd 13×7 rectangle, a full-width and a full-height band) in rotations
90, 180 and 270, and after each compares the panel's working buffer with
the expected image pixel by pixel.
All four methods passed, and the remaining one does.
The driver writes that buffer into the BMP in memory row order, while BMP
rows are bottom-up; the test reads it that way.
At rotation 0 (KOReader in landscape) partial updates failed with the
vendor driver as well: it copied them straight into a ring slot holding an
older image, so the rest of the screen showed stale content; opening
KOReader's bottom menu in landscape brought back an old portrait page, or a
white one, around it.
0025 sends rotation 0 through the same path as the others: into
process_img,
then onto the prepared previous image (a copy instead of a rotation).
The test now covers rotation 0 by default, and passes.
A full landscape update costs the copy, about 10 ms.
The scratch script
tmp/tolino/rotate-bench.sh
runs it a given number of times and tabulates the times.
As of 2026-11-05,
disp.ko
imports 20 symbols that Linux 7.4 no longer has, of which about a dozen
(__kmalloc, hrtimer_init, __class_create and the like)
are only what 4.9's headers inline, and go away against newer ones.
Of every test, a real suspend matters most for changes like these: the driver's suspend and resume paths switch the clocks and power the panel down and up again, and nothing else exercises them.
Page turns draw grainy for about half a second, then sharpen. That is not ours: generation 14 (the vendor driver) and Android with the stock kernel and the Tolino app do the same, and so does GL16 instead of GLR16 (REAGL off), checked 2026-11-05. It is how this panel's waveforms look, or a bug the stock firmware has as well.
Page turns can be driven without a person: writing a
KEY_DOWN
press and release as raw
struct input_events
into
/dev/input/event0
turns a page in KOReader, and
KEY_UP
one back, unless a dialog is open
(KOReader shows one at the end of a book).
The scratch script
tmp/tolino/pageturn.sh
does that N times; with KOReader set to open the last book on start
(start_with = "last"),
a timing probe in the driver then gives comparable numbers across builds.
Each was tested on the device before it became a patch: page turns, a full
refresh, fast scrolling, rotation, and a real suspend.
A real suspend means waiting until the device is asleep: KOReader waits
15 s after the power button before it writes
mem
to
/sys/power/state,
so a wake-up within that window never reaches the kernel.
/sys/kernel/debug/suspend_stats
counts the ones that did; USB, and with it
adb,
drops while the device is suspended.
To work on it without a kernel build per try, the source tree is assembled
by hand exactly as
os/build/kernel.go
does and built incrementally with the same toolchain and flags, on the build
host, under the same absolute path (kbuild's
.*.cmd
files record it).
Two details make its
disp.ko
bit-identical to the Nix build's:
-fdebug-prefix-map
from that path to
/build/lichee/linux-4.9,
and building it as its in-tree target
(make drivers/.../disp.ko)
rather than with
M=,
which makes an external module: no
intree
flag, and a tainted kernel on load.
Image
differs only in the vDSO's build ID, so flash only Nix-built ones.
A module from it goes onto the device by
Testing a module.
The scripts are scratch, in
./tmp/tolino/
(assemble-337.sh, april-kbuild.sh).
Towards mainline
A mainline kernel has no support for this SoC yet, and U-Boot's
boota
hands every kernel its own, vendor-format device tree, which mainline cannot
use.
So test kernels are started from the running 4.9.337 with
kexec(8),
which passes them a device tree of their own and needs nothing flashed:
a kernel that hangs costs a power cycle, after which the boot partition's
4.9.337 comes back.
4.9.337 has
CONFIG_KEXEC
since generation 30
(os/kernel/4.9.337/config.fragment),
the generation ships a static
/bin/kexec
(kexec-tools),
and
os.kernel
builds a
zImage
next to the
Image,
since kexec on ARM loads a zImage.
tolino-sys kexec [-dtb FILE] [-initrd FILE] [-cmdline ARGS | -append ARGS] [-wdt N] [-load-only] ZIMAGE
loads it with the running kernel's device tree
(/sys/firmware/fdt)
unless given another, and its command line plus
-append,
or exactly
-cmdline
(for a mainline kernel, which has no use for the vendor's),
then jumps two seconds later, detached, so that
adb shell
returns first.
Pass the boot image's initramfs: a kernel without one takes the stock
system partition as root and panics looking for
/init.
Kexec'ing 4.9.337 into itself this way, with
tolino.kexec=1
appended to tell the boots apart, comes up completely: stage1, all modules,
/dev/ion,
KOReader (2026-11-06).
What a kexec'd kernel logs before it dies survives in pstore
(Where the logs go).
os.mainlineKernel
is the mainline test kernel: Linux 6.18.60 from kernel.org, built for
ARMv7 from
sunxi_defconfig
plus
os/kernel/mainline/config.fragment,
with the same Bootlin GCC 9.3, and our device trees in
os/kernel/mainline/dts/.
Mainline has no support for this SoC.
Its patch 0002 adds a clock driver
(ccu-sun8i-b300.c),
derived from the A100's, which has the same register layout, and pin
controller drivers for the main and the always-on bank
(pinctrl-sun8i-b300.c, pinctrl-sun8i-b300-r.c)
for it; patches 0003 to 0006 adjust the SD, PMIC, frontlight and e-ink
PMIC drivers to the board, and 0007 puts the IOMMU into bypass (their
README says what each does).
sun8i-b300.dtsi
describes the SoC as far as those reach: four Cortex-A7 started through
the vendor's secure monitor by PSCI 0.2, the GIC, the arch timer, the
oscillators, the clock and pin controllers, the watchdog, the SD
controller, the USB OTG controller and its PHY, the crypto engine, the
three I2C controllers and the IOMMU.
The board's
sun8i-b300-tolino-vision6.dts
adds memory with the vendor's reservations, ramoops, the internal microSD
card, the PMIC, touch, frontlight, buttons and LED, and the e-ink PMIC.
The display will run without address translation.
The B300's IOMMU has the H6's registers but not its page-table
permissions, master count or reset, so mainline's driver does not fit;
patch 0007 instead sets every master to bypass and switches the unit
off.
That is also what a kexec needs: 4.9.337 leaves the IOMMU on, pointing
at its page table in RAM the new kernel reuses.
The display's buffers, some 100 MB, must then be physically contiguous:
the board's default CMA pool is 128 MB at
0x50000000,
where the vendor kept its ION carveout, which nothing uses any more.
It is disp's alone
(memory-region):
in the shared pool, loaded late, the 16 MB framebuffer found no free run.
The display driver itself is the vendor's disp, as 4.9.337 runs it,
ported by patch 0008.
Its sources are not copied into the repository: the build takes them from
Tolino's tarball, applies the 4.9.337 disp patches, then 0008
(os/kernel/mainline/vendor-files, vendor-patches).
It needs U-Boot's
hwcfg_p=, waveform_p=
and their sizes on the command line, which a kexec with
-cmdline
has to carry over
(kexec-test.sh does).
Its power for the panel is not connected yet
(disp_epd_power.h):
it loads and allocates, but draws nothing.
Kexec'd with the boot image's initramfs, it boots on all four cores, finds
the card, and tolino-stage1 mounts
/data
and switches to the current generation (2026-11-07: generation 36).
What does not work yet, the display above all, and the order to do it in,
are in
os/MAINLINE.md.
Its services come up as far as they can without the vendor's modules
(the modules service fails on disp.ko),
and the display with it), and adbd works over the micro-USB port: mainline's
MUSB in peripheral mode, with the A100's USB PHY, and the generation's own
adbd, which binds whichever USB device controller the kernel has:
5100000.udc-controller
on 4.9.337,
musb-hdrc.1.auto
here.
The touch screen is HID over I2C
(hid-multitouch),
x mirrored as the vendor kernel had it.
The frontlight has the vendor's interface
(mxc_msp430.0
in percent,
lm3630a_led/color),
with the per-device calibration table the bootloader keeps in its ntxfw
area (patch 0005); over all its settings the chip is programmed exactly as
4.9.337 does.
The buttons and the cover report
the codes KOReader's userpatch maps
(KEY_POWER, KEY_UP, KEY_DOWN, SW_LID),
the battery and charger read through the PMIC, and the LED by the power
button blinks a heartbeat: the one sign, without a display, that a
mainline kernel is up.
The crypto engine's TRNG
(sun8i-ce, the H6's variant)
seeds the kernel's random generator at probe: without it the generator
was ready only 9 s into boot, and adbd's AUTH token waited for it.
The e-ink PMIC
(E-ink power)
is mainline's
silergy,sy7636a:
its panel rails as the
"vcom"
regulator, its temperature sensor as hwmon.
That driver held the rails on from probe on, for the temperature sensor,
which reads out only while they are on; an e-ink panel's drive voltages
are meant to be on only around an update.
Its patch 0006 switches them on around each temperature read instead,
waits for power good when they are switched on, and takes the panel's
power-on delays from the device tree
(0xaa as the vendor's, where mainline wrote 0).
The chip's supply pins are held high as the vendor kernel leaves them;
VCOM and the panel's XON are left to the display driver, which does not
exist yet.
Three things nothing says, each of which cost runs:
-
After a kexec from 4.9.337,
pll-periph1, which feeds the SD controller, is switched off, with its output gate still open. The clock driver therefore switches both peripheral PLLs on at probe and waits for them to lock, as the A100's does. -
The SD controller is not the A100's: its DMA takes plain byte addresses, the A100's addresses shifted right by two. With the A100's compatible every command works until the first with data, whose DMA never completes; the A64's (
allwinner,sun50i-a64-mmc) fits. Its patch 0003 addsallwinner,sun8i-b300-mmc: the A64's, plus the drive and sample phases the vendor's driver sets per card clock, which mainline leaves at their reset values. With those, a rare command went unanswered (five times in some 40 boots of stress: CMD32, the start of an erase, under write load); whether the vendor's phases cure that is not shown, it being too rare to reproduce. No data was ever lost: files on /data and raw blocks on the unused partition 13, written, dropped from the cache and read back under discard and write load, always matched. -
Mainline's MUSB drops what arrives on an OUT endpoint while no read is queued: it flushes the FIFO when the next read is queued. adbd read with plain read(2), which FunctionFS serves one at a time, so after each read the endpoint had none for a moment; the host sends every adb message as header and payload back to back, and the payload of its very first CONNECT was lost — the device stayed "offline". adbd now keeps eight reads of 16 KB queued through Linux AIO, as Android's adbd does (sys/aio.go); the vendor's UDC on 4.9.337 never needed it, and does not mind.
Its log is complete from the first instruction: its patch 0001 adds
DEBUG_LL_RAMOOPS,
low-level debug output written straight into ramoops' console zone in the
format both kernels share, and with
earlyprintk
on the command line printk goes there before any driver exists.
Its own compressed pstore records are off, being unreadable to 4.9.337.
It reboots through the SoC watchdog, which keeps RAM, so a reboot keeps
the log as well.
A test kernel runs with
panic=0
and lives only as long as the watchdog lets it: 4.9.337 arms it just
before the jump, mainline's driver takes it over and feeds it until
watchdog.open_timeout
seconds after boot (nothing opens
/dev/watchdog),
and then the board resets.
The console after
switch_root,
what s6 and the services print, only reaches ramoops with
console=ttyprintk:
there is no UART node yet, and the early console is gone by then.
Long-running services such as adbd log to s6's catch-all logger on tmpfs
instead, and their output is lost at the reset.
The PMIC has a watchdog of its own, which U-Boot arms at 32 s and
nothing feeds: 4.9.337 only clears its interrupt every time it fires.
When it runs out it cuts power, which loses RAM and with it the test
kernel's log.
Mainline drives the PMIC
(rn5t618 on i2c2, with all its regulators as the firmware left them)
and keeps that watchdog fed (its patch 0004: the driver takes over a
watchdog it finds running).
Until it has probed, about 0.1 s in, the PMIC's count runs from whenever
4.9.337 last cleared it, so
tolino-sys kexec -wdt N
sets it to 128 s (its longest) and restarts it right before the jump, and
arms the SoC watchdog at N seconds; U-Boot sets the PMIC's back at the next
boot.
Restart goes through the SoC watchdog, which keeps RAM; power off through
the PMIC: PSCI's SYSTEM_OFF, which mainline would use by default, hangs in
the vendor's secure monitor with the screen lit (a long press of the power
button gets out of it).
Patch 0004's
ricoh,restart-fallback
does both.
To try one by hand:
nix-build -A users.Profpatsch.tolino.os.mainlineKernel # on april
adb push result/zImage result/sun8i-b300-tolino-vision6.dtb /data/tolino/
adb push <os.initramfs> /data/tolino/initrd.cpio.gz
adb shell tolino-sys kexec -wdt 3 \
-dtb /data/tolino/sun8i-b300-tolino-vision6.dtb \
-initrd /data/tolino/initrd.cpio.gz \
-cmdline "'earlyprintk panic=0 ignore_loglevel \
console=ttyprintk watchdog.open_timeout=6'" /data/tolino/zImage
and read the newest
/data/tolino/pstore/*/console-ramoops-0
after the reset.
os/kernel/mainline/test/kexec-test.sh
does all of that, with an incremental kernel build on april, and fetches
the log; the other scripts there and how to use them are described in
os/MAINLINE.md.
With
watchdog.open_timeout=45
there is time for
adb shell
into the running mainline kernel.
The plan for the rest is in
os/MAINLINE.md.
/dev/ion without ION
KOReader and FBInk allocate their screen buffer from
/dev/ion
(ION_IOC_ALLOC from the carveout heap, then ION_IOC_MAP)
and pass its dma-buf fd to
/dev/disp;
neither has code for anything else, also upstream (FBInk master and
KOReader v2026.07.1, checked 2026-11-05), since every device they know with
this display driver runs Allwinner's 4.9 kernel.
ION left the kernel in 5.11.
0026 adds
ion_compat,
a module that implements just
ION_IOC_ALLOC,
ION_IOC_MAP
(and ION_IOC_SHARE),
and
ION_IOC_FREE,
with buffers of individually allocated pages exported as dma-bufs: mmap for
userspace, vmap and CPU-access syncs for disp, attachments for the display
engine.
Heap masks are ignored.
Mappings are write-combined, as the vendor's carveout heap gives KOReader
and FBInk, or cached with
ION_FLAG_CACHED.
It builds against 4.9 and, by version checks, the current dma-buf API; it
is what a mainline kernel will load.
4.9.337 has no vendor ION since generation 29
(# CONFIG_ION is not set),
and with it
CONFIG_IOMMU_DEBUG,
a test driver that needs ION;
0027 makes disp independent of whether ION is configured.
ion_compat
loads first
(?ion_compat.ko
in the load order: only where the running kernel has it, not on 4.9.56,
whose vendor ION provides
/dev/ion)
.
On a kernel with ION it can be loaded next to it as
devname=ion_compat;
ROTATE_TEST_ION
points
rotate-test.c
at such a node.
CPU access to a 2 MB screen buffer, measured 2026-11-05, vendor ION and
ion_compat
alike:
**fill** **write** **read back** **invert in place**
write-combined 0.7ms 2.1ms 45ms 460ms
cached 0.5ms 2.8ms 3.3ms 5.9ms
Write-combined is right for a framebuffer that is only written; reading it
back is slow, which costs disp about 3 ms per full update and KOReader its
whole-screen reads (a software night-mode switch, screenshots, saving the
screen under a dialog).
Cached would need
DMA_BUF_IOCTL_SYNC
around writes, which neither KOReader nor FBInk issues.
The 4.9.337 merge
Tolino's tree is Google's
android-4.9-o-mr1
at 4.9.56, plus Allwinner's and Netronix's board support.
Of every commit on that branch from 2017-09 to its end in 2021-09, the tree
is closest to
27e78dc28
(2018-08-07,
"f2fs: catch up to v4.14-rc1");
so is the Kobo Sage's
(https://github.com/kobolabs/b300-sage),
the same SoC: Kobo ships 4.9.56 too, still in its October 2026 update.
Against that commit, the vendor added 6900 files (4.4 million lines, most
of them Wi-Fi drivers for other chips) and changed 600 upstream ones (32000
lines, whitespace aside).
No Allwinner SDK for this SoC with a newer kernel is known.
os.kernel
is that delta moved onto
android-4.9-q
(f9b8314c6),
Google's last 4.9 branch: 4.9.337 with Android's fixes until 2023-01.
The build assembles the source from three parts:
-
android-4.9-q, fetched by commit withfetchgit(a shallow clone of one commit). -
Every file of the tarball that q does not have, as it is: the vendor's drivers.
-
The tarball's version of each file in os/kernel/4.9.337/vendor-files, about 290 files where q has its own and the merge kept the vendor's as it is.
-
os/kernel/4.9.337/patches/: the files where both were merged, about 140, in two patches (core and generic code; sunxi and Netronix board support), then the vendor's top-level Makefile, the three build fixes, and our changes on top (The disp module).
Both lists cover only files the build reads: what the kernel's dependency files (.*.cmd) name, and every Kconfig, Makefile and script. Elsewhere the tree stays q's, even where the vendor changed or deleted a file (tests, other architectures, other chips' drivers): as a source tree it is not the whole merge, but it builds the same kernel, bit for bit, as the whole merge did (2 MB of patches, compared 2026-11-03). A file that starts to be built after a configuration change may need an entry; the merge in full is in the history of the commit that introduced 4.9.337.
The merge took q's version wherever q is newer and the vendor's change adds
nothing: f2fs (the vendor's only change to it, no highmem pages for
directory entries, is in q), fscrypt, ext4, binder, printk, the scheduler,
the Bluetooth core, HID and the generic USB and serial drivers.
It took the vendor's where the vendor rewrote a driver: the Elan
touchscreen, the sunxi clocks, the Realtek Bluetooth UART.
By hand: the vendor's policy of serving movable allocations from CMA first
(it keeps the 128 MB CMA area in use without starving
alloc_contig_range()),
ION mapping every allocation into the kernel, the sunxi UDC's DMA flag in
MTP, and the
ntx_init()
hook in
init/main.c.
Two changes were needed for q itself: q made
ion_handle_get_by_id()
internal, so sunxi ION has its own locked lookup; and q refuses the
SYSTEM_CONTIG
ION heap, which the vendor's ION driver took as the end of its heap list,
leaving the carveout heap unset and
disp.ko
stuck in its init (it then also blocked every reboot).
The commit messages in the patches list each of these; the two changes for
q also have a comment in the code.
f2fs moved from the vendor's (Android's "updates on v4.16-rc1", 2018-02) to q's: Android's backport of 5.0 with fixes until 2022, 554 commits, 94 of them about corruption, recovery or sanity checks by subject. The data partition uses none of the newer on-disk features (feature word 0, written by 4.9.56). A /data backup taken from the running system before the first boot is in ~/tolino-backup/2026-11-03-data/, the 4.9.56 boot partition in ~/tolino-backup/2026-11-03-boot/.
Booted 2026-11-03, generation 13: all three modules load, every service
comes up, KOReader draws and reacts to touch, the frontlight works,
/data
mounts and writes, and
adb reboot
comes back.
Buttons, suspend and power off still need a person with the device in hand.
Back to 4.9.56: flash
os.bootImageOwnKernel4956,
with fastboot or from the running system:
nix-build -A users.Profpatsch.tolino.os.bootImageOwnKernel4956
adb push result /tmp/boot.img
adb shell 'dd if=/tmp/boot.img of=/dev/mmcblk0p4 bs=1M conv=fsync'
SECURITY
Rooting did not add remote attack surface. TWRP and fastboot are USB-only, and physical access already meant full control before: the bootloader flashes without an unlock, and UDISK (/data) is not encrypted. Anyone holding the device can read every book and the Tolino account token.
The stock firmware is the larger risk: Android 8.1 with security patch
level
2018-07-05,
kernel 4.9.56, WebView, and a cloud app that talks to the network on every
Wi-Fi session.
Removing Android removes most of that.
What remains, ordered by how seriously to take it:
The kernel and the Wi-Fi driver
Reachable by anyone in radio range or on the same network, with no vendor updates coming. We build the kernel from the GPL source (Building the kernel); backporting fixes is still real work. Mitigation: Wi-Fi off by default and unloaded (
rmmod) when off; on only for an actual sync or download, on trusted networks.
Listening services
In the Go design nothing listens unless deliberately started. The Go init installs a default-deny inbound firewall before bringing up
wlan0; the kernel hasCONFIG_NETFILTER,CONFIG_IP_NF_IPTABLES,CONFIG_IP_NF_FILTERbuilt in. KOReader's SSH plugin (dropbear, port 2222) is off by default; if enabled, key-only (-s), never "allow no password" (-n). No adbd(8) over TCP; ideally no adbd at all outside development.
Untrusted content
KOReader runs as root (as on Kobo) and parses EPUB/FB2/HTML (crengine), PDF (MuPDF), images, OPDS feeds and news. A malicious book is a more realistic attack than a network one. Its TLS library is LibreSSL 4.3.2, current. Mitigation: books from trusted sources; later, run KOReader as an unprivileged user under the Go init (needs /dev/disp, /dev/ion, /dev/input/* and the frontlight sysfs nodes made accessible to it).
Magic SysRq
The stock configuration enables every SysRq function (
CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE=0x1), so a USB keyboard on the OTG port, or a break on the serial console, could reboot, crash the kernel or kill every process without logging in. Thesysctlservice setskernel.sysrqto 0 at boot. /proc/sysrq-trigger does not consult that setting and stays usable for root, e.g. fromadb shell.
Requirements carried into the Go init: firewall before network, Wi-Fi unloaded when off, no network adbd, no listening service enabled by default.
NEXT STEPS
-
Upstream a
DEVICE_TOLINO_VISION_6(PCB0x60) to FBInk, and atolinodevice profile to KOReader. -
Wi-Fi under the tolino OS: firewall, iwd or wpa_supplicant, as planned in Wi-Fi (plan, not yet tried) and SECURITY.
-
Promote try to current automatically once a generation has booted well.
-
Finish testing the 4.9.337 kernel by hand: buttons, suspend and power off (it boots, draws, takes touch and reboots, see The 4.9.337 merge).
-
Run a read-only fsck.f2fs(8) on /data from TWRP now and then; nothing checks it otherwise.
-
4.9.337 is the end of 4.9. Mainline: see os/MAINLINE.md and Towards mainline. A later LTS (CIP's 4.19, 5.10 or 6.1) means porting the board support, not merging it: about 600 changed upstream files and the sunxi drivers, against ten or more versions of kernel API. Mainline (7.4) has no support for this SoC at all, but its clock register layout matches the A100's (ccu-sun50i-a100.c), and drivers exist for most of the board: RTL8723DS (
rtw88_8723ds), Ricoh619 (rn5t618), SY7636, the Elan touchscreen and the LM3630A. Not for the e-ink display: that stays Allwinner's disp driver, ported. meta-sunxi, checked 2026-11-03, is a thin Yocto layer over mainline and adds nothing for it. -
Make disp.ko build against a newer kernel API while still on 4.9.337, one replacement at a time, each tested by Testing a module (timestamps, panel GPIOs, ION, kmap, the whole-cache flushes, PWM, hrtimers, the chip-ID check, the state-extended flag, the JD9930 fallback, the NEON helpers and the hardware config are done; the SY7636, the sunxi IOMMU and the pin power mode are behind disp_epd_power.h and disp_soc.h, to be implemented with mainline drivers and the device tree at SoC bring-up; g2d is replaced by rotation on the CPU; see The disp module). KOReader and FBInk allocate their buffers through /dev/ion themselves; on 4.9.337 that is
ion_compatsince 0026, so a mainline kernel needs nothing else for them (/dev/ion without ION).
SEE ALSO
adb(1), fastboot(1), tolino-archive(1)
- https://github.com/iscilyas/tolino_b300_twrp
- https://github.com/NiLuJe/FBInk (eink/sunxi-kobo.h)
- https://github.com/koreader/koreader
- https://opensource.mytolino.com/portfolio-item/tolino-vision-6/
- https://gokrazy.org
CAVEATS
-
TWRP's kernel is a January 2024 build of the same 4.9.56 tree (142 bytes differ from stock); fine for backups, but test display code under the stock kernel, since that is what will ship.
-
USB sometimes fails to enumerate after a reboot into TWRP (the host sees "new high-speed USB device" and nothing more). Rebooting into recovery again from the TWRP menu fixes it.
-
A firmware OTA will likely restore recovery-from-boot.p and therefore stock recovery. Keep Wi-Fi off or let it happen and re-do the TWRP step.
-
Gemini's answers about this device were partly invented (URLs, a postmarketOS page with "hardware details" that was empty, an AllesEBook guide that does not exist). Verify before trusting.