Subsystems

Storage

The UFS: how the root is read and written, and where the loader and the shim read it.

Hardware

A MediaTek UFS 2.1 host (ufshci@11270000, UFSHCI 3.1) with a 4096-byte block. The user unit is LUN 2 (sdc), holding the GPT; LUNs 0 and 1 are the 4 MiB boot units and have none. LK leaves the host enabled, the link up and a request list running, and Android’s partitions are on LUN 2: boot (32 MiB, one slot), super, userdata and the rest. Our partition (xnusys, or userdata in the single layout) is made from the end of userdata.

Driver

Three readers of the same host, each taking the request list from LK and giving it back:

• mtkloader reads the root partition’s HFS+ headers and the tail area before XNU (mtkroot.h).
• The shim (bootrec.c) reads the boot-args record: polled READ(10) commands only, with no write in the file.
• The kernel’s mtk_ufs.c finds the GPT’s partition (the one mp_ufsroot names, on mp_ufslun or the first LUN that has it) and exposes it as the BSD disk ufsroot0, with 512-byte sectors over the 4 KiB blocks. It is polled, not interrupt driven; all DMA goes through one physically contiguous allocation and a 1 MiB bounce buffer, and the host is not cache coherent. Writes are refused unless mp_ufsrw=1, and each is checked against the partition’s bounds just before it is issued. The root is mounted from it with rd=ufsroot0 (read-write with mp_rootrw=1).

Device tree

/mapple-ufs (mediatek,mt8183-ufshci, 0x11270000, size 0x4000). See Device tree.

Boot-arguments

mp_ufsroot, mp_ufslun, mp_ufsrw, mp_ufscache, mp_ufswait, mp_rootrw, mp_conlog and mp_ufslogsecs in the catalogue. The spaced line has mp_ufslun=2, mp_ufsroot=xnusys (userdata in the single layout), mp_ufsrw=1, mp_rootrw=1 and mp_conlog=0. See Root image and layouts for what lies at the end of the partition.

User space

mapple-install (in the recovery) writes the same partition’s tail area, saved area and, in the split layout, carves it; the root image itself is made on your Mac.

Status

device.conf: partial: the system image in xnusys on the UFS (LUN 2) as the root, read-write (mp_ufsrw=1, mp_rootrw=1), polled.

Seen: the root mounted read-only (smoke run 2) and read-write (run 3), with no UFS errors; a read-write root through two boots (run 4).

Known issues

• The driver polls and does not use the host’s interrupt; mp_ufswait=1 makes it sleep between polls once a command has run a while.
• Persistent logging (mp_conlog=1) would write over the installer’s tail area and the record’s block: leave it at 0.

Source files

bsd/dev/mtk_ufs.c of the kernel at 76b737c; shim/bootrec.c and mtk/loader/mtkroot.h of mapple_loader at 2aa5786; installer/mapple-install.c of mapple_build at f7431bb.