olragon

HiMedia Q10 Pro on mainline Linux 6.18

🌿 buddingplanted tended #linux#hardware#tv-box#mainline#hi3798cv200#reference

Written for Anyone holding a HiMedia Q10 Pro (or another Hi3798CV200 box) who is happy to build a kernel.

A reference for anyone holding the same box, or another Hi3798CV200 device. Each result below was measured on the box, and the evidence is given next to it. Where something is only inferred, it says so.

Tiếng Việt: HiMedia Q10 Pro chạy Linux mainline 6.18.

The Q10 Pro mainboard: purple PCB, Hi3798CV200 under a black heatsink, AP6255 WiFi module below it
Board v2.2: Hi3798CV200 (4× Cortex-A53) under the heatsink, 2 GB RAM, AP6255 WiFi/BT. Serial sticker blurred.

This box sat in a drawer for nearly a year before I took it out again. I bought it in 2016, it ran Android 7, and then HiSilicon left the set-top-box market. I left it in there too, felt a small pang every time I saw it, and had no idea where to start.

Then one quiet evening I plugged it in to see whether it was still alive. It was. Five days later it was running Debian.

What ended up working

  • Device: HiMedia Q10 Pro (2016). HiSilicon Hi3798CV200, 2 GB RAM, 3.5" SATA bay, VFD clock, RCA + optical + HDMI audio. Last firmware: Android 7 on a vendor 4.4 kernel.
  • Result: Debian trixie (armhf) on Linux 6.18.55 with a local patch series. It has display, GPU, bit-exact hardware video decode, audio on every port, Ethernet, WiFi, USB 3, the remote and the front clock. A TV menu boots into Desktop, Music, Kodi, Web or Android 13.
  • Source: everything is public — the kernel patch series, the board device tree, the host build and bring-up tools, the session switcher and the research notes: olragon/himedia-q10-pro-linux (GPL-2.0).
  • The box is not bricked. Only the U-Boot environment was changed, and the change can be undone. Without the USB stick the box boots its own Android.
  • Time: about five days, with no serial console.

Where this gets stuck

A working computer should not be thrown away because its vendor stopped caring. This box is from 2016. HiSilicon has left the set-top-box market, the last firmware is Android 7 on a 4.4 kernel, and nothing more is coming. Hardware like that gets left behind: it still boots, it still decodes 4K, and it goes into a drawer anyway and then into a bin — not because it broke, but because the software around it died. Four cores, 2 GB of RAM, gigabit Ethernet, USB 3, a hardware video decoder and an internal 3.5" SATA bay are worth more than that.

The box is not missing a feature. The hardware is still good; only the software around it died. I wanted to know whether it could run a current, maintained OS and keep the hardware video decode. That is the part that makes it worth keeping.

  • A newer Android is a dead end. The video, HDMI and GPU blobs are built against HiSilicon's 4.4 BSP. HiSilicon has left the set-top-box market, so a newer BSP will not come.
  • A vendor kernel with Debian on top is a trap. The blobs speak HiSilicon's private MSP API, not V4L2 or DRM. Kodi, mpv, FFmpeg and Chromium cannot use them, so you keep old drivers and still get no hardware video.
  • There is no serial console, and the stock bootloader has bootdelay=0. A kernel that hangs and one that boots fine look the same: a black screen and no ping.

Which way I went

Run mainline Linux (6.18 longterm) in 32-bit mode, and port or write each media driver.

  • Boot: U-Boot tries a kernel on a USB stick first and falls back to the eMMC Android.
  • Bring-up without a console: use the SoC watchdog as a telemetry channel.
  • Video: port the community V4L2 decoder (VDH) and post-processor (VPSS) from a 6.12 tree.
  • Audio: the audio block (AIAO) had no usable driver, so a small ALSA driver was written from register recipes in the vendor SDK.
  • Userland: Debian, a TV session menu, and a kexec chain so that a bad kernel never makes the box unbootable.

Why 32-bit: the boot firmware and the TEE are 32-bit, so the kernel is AArch32. arm64-only apps will not run.

What order to do it in

The order matters: each step gives you the tool you need for the next one.

1. Root and back up before you change anything

The stock build is eng with ro.debuggable=1, so adb root gives root and writes nothing to the box. Use it to dump all 19 eMMC partitions and check every dump against a sha256 taken on the device. Archive the matching stock firmware too. On this unit it is HMD-2.1.7, and its fingerprint must equal the box's ro.build.fingerprint.

2. Make U-Boot boot from USB first

The stock loader already has USB host and FAT support (usb start, fatload); it just isn't configured to use them. Rewrite the environment's bootcmd so that it:

  1. loads trustedcore (the TEE) first, as the stock command does;
  2. tries fatload + bootm of uImage from the stick;
  3. falls through to the original eMMC commands, copied verbatim.

No stick, or a kernel that bootm refuses, means the box simply boots Android. Keep the original environment dump so it can be written back.

⚠️ The stock environment has verify=n: bootm does not check the uImage CRC. A corrupt image is executed, not rejected, and hangs. Validate both CRCs and the arch field before you copy an image to the stick.

3. Build the kernel and device tree

  • Linux 6.18, ARCH=arm. Port the device tree from the upstream arm64 hi3798cv200.dtsi; the Poplar board is the nearest relative.
  • Every driver needed to boot must be =y. The Ethernet PHY's reset controller (RESET_TI_SYSCON) was =m in an initramfs that loads no modules, so the PHY was never reset.
  • The Ethernet MAC scans direct children for its MDIO bus, so the PHY node must sit straight under the MAC, not inside an mdio {} wrapper. Add hisilicon,phy-reset-delays-us together with the reset.
  • WiFi (AP6255) needs GPIO4_6 (WL_REG_ON) and 1.8 V SDIO pads.
  • Test kernel + initramfs + PID 1 in QEMU (-M virt) first. Boot the bare zImage, not the uImage: with an appended DTB the decompressor ignores the device tree QEMU passes.
  • The patch series (0002–0020 against 6.18.55), the board DTS and the host build scripts are in scripts/himedia/kernel/arm32/ of the source repo, next to the vendor GPL defconfig and DTS kept for reference.

4. How to debug with no console

Each early-boot checkpoint re-arms the SP805 watchdog with a different timeout. The time until the box resets then names the last checkpoint it reached. Seven flashes, 18 checkpoints:

reset afterlast checkpointproves
~19 sstextthe kernel proper was entered
134 s__create_page_tablesthe pre-MMU path is done
194 s__mmap_switchedthe MMU is on
216 skernel_init_freeableevery initcall ran; about to exec /init

Rules that make the readings trustworthy:

  • Space the timeouts more than 10 s apart. Loading the kernel adds 11–14 s, and that time grows with kernel size.
  • Give the deepest checkpoint the longest timeout. Nothing pets the dog after it, so "booted fine" and "died right after" reset the same way.
  • Every probe has to actually trigger. A "PID 1 ran" checkpoint that opens /dev/mem needs a /dev/mem node in the initramfs.
  • In init.sh, mount /dev first and without 2>/dev/null. /dev/null does not exist yet, and under POSIX a failed redirection skips the command while the script carries on. That one line silently disabled a whole boot stage.
  • Keep the timeout within 1–178 s. 300 s × 24 MHz overflows the 32-bit register.

5. Waking the four cores, and making it reboot

  • Secondary cores come up through the TEE (SC_GEN1). The vendor's SRAM path cannot be written from the non-secure world.
  • Reboot hangs on mainline: the SoC has no restart handler. Arm the SP805 with LOAD 0x100 (HiSilicon's clone never fires from 0) in a systemd shutdown hook. The box is back in about 65 s.
  • DVFS: CPU 396–1596 MHz at 840–1150 mV; GPU devfreq 200–400 MHz.

6. Getting a picture on the TV, then the GPU

  • A VDP DRM driver takes over the bootloader's 1080p60 mode, with a G0 graphics plane and a V0 NV12 video plane. Switching between 1080p 60/59.94/50 and 720p works in the driver, but I haven't checked it on the TV yet.
  • Panfrost drives the Mali-T720: kmscube at 59.9 fps, glmark2 score 90, 0 GPU faults.

7. Decoding video in hardware

Port VDH + VPSS from HiSilicon-Development/linux-6.12.y to 6.18 on 32-bit. Use FFmpeg with the v4l2-request patches (Kwiboo). The first decode "succeeded" with every frame solid green. Two bugs were stacked:

  1. The VDH failed on exactly the pictures that contain emulation-prevention bytes. Fix: let the driver strip them.
  2. VPSS failed with state=0x8d. Fix: non-secure writes, and a real write-back buffer instead of physical address 0.
A solid green frame
Before: the IRQ fired, the buffer stayed all-zero NV12.
ffmpeg testsrc2 frame 150 with burned-in timecode 00:00:05.000
After: frame 150 of the test pattern, exact.

Two settings decide the speed:

  • Make capture buffers cacheable. 1080p is coded 1088 lines high, so every frame is crop-copied. From uncached memory that cost 28.7 s of CPU per 300 frames. Cached: 94 fps at 3.6 s, with identical md5.
  • Display zero-copy. A CPU-copied framebuffer gave 11.7 fps at 34 s of CPU. Importing the decoded dmabuf into the VDP video plane gave 48.5 fps at 3.8 s.

8. Getting sound out of all three outputs

A small ALSA driver: one ring buffer read by all three ports, and the read pointer polled from an hrtimer, so it needs no interrupt and no device-tree node. HDMI audio needs N=6144 for 48 kHz (measured CTS 148,351).

The Music session is driven by audiod, a small Rust daemon with a REST/WebSocket API and a CLI. It picks the output, writes MPD's output stanza and the ALSA chain under it, and proves bit-perfect playback by reading the hardware instead of trusting the config. It replaced the Python router.

9. Debian, and the session menu on the TV

  • Debian trixie armhf, built with debootstrap. The root filesystem is an image on the stick, loop-mounted by the initramfs.
  • kexec chain: the stick keeps a fixed, known-good kernel. It kexecs into the newest kernel under an armed watchdog with a failure counter, so a bad kernel costs one reset.
  • Session menu on its own VT, driven by the remote or the front touch keys. The front touch board sends NEC codes into the IR receiver, so one keymap covers both.
  • The session switcher, the bring-up tools and the on-box utilities are in the source repo (Bun, on the host side). The Music session's audiod is not part of it.
TV session menu: Desktop, Music (default, running), Kodi, Web, Android 13, Original Android 7 (unavailable), Audio settings
The session menu as the box draws it today. Music is the default; Original Android 7 is opt-in and not installed on this stick.

What works

partstatusevidence
4 CPU cores, DVFSworks396–1596 MHz, 840–1150 mV
RebootworksSP805 restart, back in 65 s
Ethernet, WiFiworksAP6255 after GPIO + 1.8 V pad fixes
USB 3 (side port)works91.7 MB/s measured
Remote + front touch keysworksone NEC keymap for both
Front VFD clock (TM1629A)works16-segment font calibrated from photos
Display, GPUworksVDP DRM, Panfrost, kmscube 59.9 fps
Hardware video decodeworkssee the table below
Audio: RCA, optical, HDMIworkstone heard on each port
Audio: USB DACworksPCM to 32/768, native DSD512, bit-perfect — see below
HDMI-CECsend onlyreceive untested: no CEC TV here
SATAworksroot filesystem on the 3.5" disk (kernel k26)

Video decode, checked by md5 of every decoded byte against FFmpeg software decode:

clipframesvs softwarefps
H.264 1080p602400/2400md5 identical75
HEVC 1080p 8-bit300/300md5 identical51
HEVC Main10 1080p300/300md5 identical (P010)31
HEVC 2160p150/150md5 identical15
VP9 1080p300/300md5 identical52
MPEG-2 1080p / 576i300 / 250min PSNR 68.4 / 66.1 dB41 / 68

Is the music really bit-perfect

Every number below comes from a script that can fail, and each gate was made to fail on purpose before its pass was believed. "Bit-perfect" is read at the hardware, not from a config file: ALSA's hw_params — the format and rate actually opened — and the DAC's own USB feedback clock, its momentary frequency, within 0.1 %. The DAC is a Nowna Audio USB DAC, UAC2 asynchronous: PCM 16/24/32-bit from 44.1 to 768 kHz, and native DSD (DSD_U32_BE) up to DSD512.

gateresult
PCM matrix30/30 bit-perfect: 16, 24 and 32 bit × 44.1, 48, 88.2, 96, 176.4, 192, 352.8, 384, 705.6, 768 kHz
Native DSD4/4: DSD64, 128, 256 and 512 opened as DSD_U32_BE at 88.2 / 176.4 / 352.8 / 705.6 kHz
Gaplesstwo tracks in the same format: the PCM never closes and the hardware pointer never stops; a rate change reopens at the new rate, with no resampling
Under load5 minutes of 32/768 with a busy CPU core and 7.8 GB arriving over the network: 0 xruns, 0 stalls. MPD's output thread runs real-time (SCHED_FIFO 40). Peak temperatures: SoC 67 °C, disk 43 °C
Signal path14/14: the raw hw device — no mixer, no ReplayGain, no crossfade, no resampler between MPD and the DAC
Honest proofthe daemon's own bit-perfect verdict was tested to be unable to lie: 2,208 golden cases, 3/3 deliberate bugs caught

The proof gate earned its place straight away. Both the old Python checker and the new daemon called any native-DSD stream bit-perfect, whatever rate the DAC was actually running at — a DSD128 file on a DAC clocked for DSD64 would have passed. Both were fixed before the gates were run.

Two other things came out of the same pass. The UPnP/OpenHome renderer (upmpdcli) was invisible to UPnP apps and crashed on every queue change, because its data files had never been installed: a packaging step picked files by modification time, and the build system keeps the source archive's old timestamps on data files. It is visible now, and took 50 queue changes without a restart. And the tests stay away from the music: every test file is generated on a RAM disk, never written to the music disk, and the tones play at −30 dBFS. The load test carries its own thermal guard — stop at disk 48 °C or SoC 80 °C — because this SoC has no passive thermal trip, only a critical one at 110 °C, so nothing throttles it and four busy cores reach 80 °C in about three and a half minutes.

What runs on it:

Music mode idle screen: Ready, play from AirPlay, Spotify Connect or a UPnP app, or browse the library in a browser; output Onboard (HDMI / RCA / optical); volume 8
Music: MPD, AirPlay 2, Spotify Connect, UPnP/OpenHome and a web library. Output select, per-port switches and L/R trim from the remote, the CLI or a phone. LAN address pixelated.
Now playing screen: 01 Tone 96k, FLAC 24/96 to onboard, resampled to 48 kHz
The onboard path only does 48 kHz, so the screen says when it resamples.
LXQt desktop with a start menu listing Chromium, Kodi, Android 13
Desktop: LXQt, GPU-accelerated through glamor, 293 MB in use.
Kodi 21.2 Omega splash
Kodi 21.2 on GBM + GLES with the V4L2-request decoder.
Android 13 home screen
Android 13 (LineageOS 20 in Waydroid): launcher in 100 s from SATA, 724 MB used.
kmscube's coloured cube rendered by the Mali-T720
Panfrost on the Mali-T720 through the VDP.

Android 13 in Waydroid needed three things:

  • EXT4_FS_POSIX_ACL in the kernel. Without it, vold cannot set a default ACL and system_server loops into "rebooting into recovery".
  • The GPU only does GLES 2.0. Set Mesa's version override in the environment (an init .rc in the vendor overlay; a property does not work) and turn off boot-time shader priming.
  • Waydroid's networking assumes legacy iptables. Its nftables path works.

What does not work yet

  • SATA: the kernel was wrong, not the hardware. The first release blamed the cable. The cable was innocent. Two new ones (83,200 ₫ — 2 × 52,000 ₫ less a 20,800 ₫ voucher) changed nothing: a 2 GB raw read still gave 6 CRC errors, 6 hard resets and a drop to UDMA/100 at 1.5 Gbps, the same numbers as before the swap. The 1.5 Gbps is not a fault either — this Seagate advertises only 1.5 Gb/s itself (hdparm -I), and every clean SATA boot in the old logs was a different disk, a WD at 3.0 Gbps. The cause is in mainline's combo-PHY driver: it writes one tuning value, nano[0x1] = 0x8, in every mode — a value carried over from another board's PCIe setup. The vendor's SATA driver writes 0x4. Finding it needed zero disk reads: an idle SATA link still carries filler symbols, so the controller's error register (PxSERR) counts 8b10b decode errors with no sector touched — 4–33 error-seconds per minute on the mainline value, 0 in five one-minute runs on the vendor one. Sweeping all 16 values: 2, 4 and 6 are clean, anything with bit 3 set errs, odd values are erratic or never link. With the vendor tuning under the real driver: 2 GB read twice and a 1 GB in-place rewrite (the same bytes written back, checksums compared) — CRC +0, 0 exceptions, 0 resets, UDMA/133, 75 MB/s.
  • The root took one wrong turn first. Before the kernel fix, the disk was wiped and made the root with the value written from userspace — after the driver had already trained the link, which blips the PHY. With root I/O in flight, one boot's link-reset loop ended with the disk disabled and the ext4 journal aborting; the filesystem checked clean afterwards and the box went back to the USB-stick root for the day. Kernel k26 sets the value before the first link training (SATA mode: nano[0x1] = 0x4 in dmesg), and the box now boots from the disk: three reboots in a row with 0 exceptions, 0 hard resets and the disk's CRC counter unchanged, about two minutes from power to ssh. The music library and the Android data live on the 229 GB disk now, instead of 4 GB image files on the USB stick.
  • The disk runs hot. With the lid's thermal pad, an idle disk climbs from 35 °C to 47 °C in half an hour and is still rising slowly. The SMART limit is 55 °C.
  • The DAC dropped off the USB bus once. Mid-test, on a 192 → 352.8 kHz switch: a USB protocol error, then the hub disabled the port, and it took a physical replug to come back. The same switch had passed twice earlier that day and passed again afterwards, so the cause is unknown — the DAC's USB controller, the cable or heat. The router did the right thing and fell back to the onboard outputs within a second. The test runner now refuses to carry on when the DAC it started with has gone, instead of "passing" on the onboard card.
  • Android has no internet. The kernel lacks IP_ADVANCED_ROUTER / IP_MULTIPLE_TABLES, which netd needs for policy routing.
  • Android from a USB 2 stick is slow: about 50 min on the first boot, 7 min after that, against 100 s from SATA.
  • No Netflix-class DRM. The stock firmware has Widevine L3 only. It is an eng build, not a certified device.
  • 32-bit only, as explained above.
  • Stock Android 7 via kexec boots but shows stripe noise on the TV. It is opt-in.
  • Not investigated: software-decoded frames through mpv's GL renderer raise Panfrost INSTR_INVALID_PC faults (356 per 720p clip). Hardware-decoded frames give 0.

Still unfinished

  • Measure the disk temperature under load (Kodi, Android), and decide what the closed box needs beyond the lid's thermal pad.
  • Kernel build with policy routing, so Android gets a network.
  • Test the remote in every session, and do a cold-boot test of the whole chain.
  • HDMI-CEC receive, 4K/HDR output, AC3 passthrough: they need a TV that supports them.
  • Stock Android 7 picture after kexec.
  • Clean up the patch series and send the generic parts upstream.

What carries over to another board

  • A ping reply proves that something answered. Early on, "the kernel is up" was in fact an IP camera on the address I had picked, and five build rounds rested on it. Check the MAC with arp.
  • Exit code 0 does not mean it worked. Read the artifact: size, hash, the confirming log line.
  • A verifier that knows only one instruction encoding reports code as missing. Check rotated immediates, movw/movt and literal pools, in both ARM and Thumb-2.
  • When a reboot "never comes back", check that something will actually reset the board before you blame the image.
  • A new cable is a test, not a fix. Measure the same numbers before and after it: here they did not move, and that is what pointed away from the hardware.
  • You can measure a link without wearing the disk: an idle link still carries traffic, so count the errors in the controller's own error register.
  • Do not retune a link under a mounted filesystem. The value that was safe on an idle disk wedged the same disk while it was busy being the root.
  • A setting that has to be in place before a link trains belongs in the kernel. Userspace can only change it afterwards, under live I/O — which is exactly when it is unsafe.
  • Prove that a test can fail before you believe it passed. Three of the six audio gates caught the tester's own mistakes first: a network load that sent 0 bytes (macOS head -c will not take 100G), a gapless judge that missed a real reopen, and a mixer check that failed a correct box. Each gate now runs a control that has to come out flagged.
  • A verdict has to check the thing that can change. "Native DSD" is not bit-perfect by itself — the rate the device is running at is part of the claim.

Where to read more

Day by day

  • 2026-10-09. Started: five research angles on whether a Hi3798CV200 box can run mainline at all. Verdict: viable, because the SoC is the 96Boards Poplar reference part — bring-up of a known upstream platform, not reverse engineering.
  • 2026-10-10. Full eMMC backup first, then the first boots. The SoC watchdog became an 18-checkpoint telemetry channel; the ladder reached the exec of /init, which retired the earlier verdict that no mainline kernel boots on this box.
  • 2026-10-11. ssh into Debian trixie (armhf) on 6.18.55, booted from the USB stick. GPU (Panfrost), WiFi, USB and the front panel brought up; the VDEC/VPSS port written against a community 6.12 tree.
  • 2026-10-12. The TV session menu runs on the box (k18): live switches, the cold-boot path measured, Android 13 under Waydroid. The same day the SATA link went down after stock Android booted once, and the hunt began.
  • 2026-10-13. Kodi, Web and Android 13 all boot from the stick alone (k25) while the SATA link was out.
  • 2026-10-14. First release of this note: the field notes and the evidence photos.
  • 2026-10-14. SATA root cause found: the mainline kernel's PHY tuning, not the cable and not the board. Two new SATA cables were bought first (83,200 ₫); neither fixed anything.
  • 2026-10-14. Tried the SATA disk as the root filesystem, and reverted it the same day.
  • 2026-10-14. Kernel k26: the SATA PHY value is set before the first link training, and the box now runs from the 3.5" disk. Three reboots in a row: 0 SATA errors, 0 link resets.
  • 2026-10-16. Audio: audiophile class on a hi-res USB DAC (PCM to 32/768, native DSD512, gapless, no xrun under load); audiod v0.1.0.
  • 2026-10-16. Source published: github.com/olragon/himedia-q10-pro-linux (GPL-2.0).
  • 2026-10-17. Backfilled the changelog with the days before the first release (2026-10-09 to 10-13), and said plainly why the box was worth saving at all.

A few things I still do not understand. Twice macOS unmounted the volume mid-benchmark with nothing in any log, and I have never reproduced it on purpose. The DAC dropped off the USB bus once and never again, and I cannot say whether that was the DAC, the cable or heat. And I know which PHY tuning value works without knowing why it has to be that one. If you understand these blocks better than I do, I would like to hear it.

Tended by papa dragon & AI.

Write papa dragon a letter

If this note stirred something, write to me here. A letter reaches only me and never shows up on the page by itself. If one is lovely and you allow it, I may quote it under the note, without your name.

What the garden keeps from a letter

Works from a terminal too: curl -d 'msg=…' olragon.com/garden/himedia-q10-pro-en/letter