Skip to content

feat: automatic USB sessions (enable once) - #3

Open
pdev-labs wants to merge 16 commits into
feat/usb-real-portfrom
feat/usb-auto
Open

pdev-labs wants to merge 16 commits into
feat/usb-real-portfrom
feat/usb-auto

Conversation

@pdev-labs

Copy link
Copy Markdown
Owner

What this adds

lfa usb enable -i NAME becomes the only USB command a user needs. It now also turns on automatic mode: every later session LFA starts comes up with the plugged-in device already inside.

lfa usb enable -i ubuntu-5623     # once
lfa desktop -i ubuntu-5623        # lsusb, PyUSB, esptool: already there
lfa shell   -i ubuntu-5623        # same

No lfa usb attach, no lfa usb scan, no DISPLAY juggling for GUI apps.

How

  • terminal-linux and start-linux call lfa-usb-auto first. It takes the real descriptor from Termux:API, prepares the synthetic sysfs tree once per device (later sessions reuse it), and re-runs the launcher with --bind flags and the guest preload exported.
  • start-linux routes its proot launches through pd_login and prefixes each guest command with ${USB_WRAP}, so the desktop session and everything it spawns inherit LD_PRELOAD and LFA_USB_MAP.
  • Sessions start normally when nothing is plugged in, when the preload cannot be built, or when the instance is not the enabled one.
  • lfa usb disable turns the mode off and removes lfa-usb-auto.
  • The attach descriptor prep is extracted into lfa_usb_prep_sysfs, shared by attach and auto.

Limits (documented)

  • Android still asks for permission per device/connection; no way around it without root.
  • Only sessions started through LFA get the view; a bare proot-distro login is untouched.
  • One device per session; automatic mode follows the instance you enabled.
  • Mounting USB storage stays impossible (block device), unchanged.

Testing

  • Full suite: PASS=826 FAIL=0, shellcheck clean, bash -n clean.
  • New checks: enable writes USB_AUTO=1 and lfa-usb-auto, auto hands binds/map/preload to the command, launcher hooks and pd_login/USB_WRAP injection, disable turns it off.

Stacked on #2; base retargets automatically once #2 merges.

`lfa usb enable -i NAME` now also turns on automatic mode. The launchers
(`lfa shell` via terminal-linux and `lfa desktop` via start-linux) call
lfa-usb-auto before doing anything: it takes the real descriptor from
Termux:API, prepares the synthetic sysfs tree once per device (later
sessions reuse it), and re-runs the launcher with the proot binds and the
guest preload exported. No attach, no manual scp, no DISPLAY juggling:
GUI programs started from the desktop inherit the same device view.

Sessions still start normally when nothing is plugged in, when the preload
cannot be built, or when the instance is not the one enabled.
`lfa usb disable` turns the mode off and removes lfa-usb-auto.

Also extracts the attach descriptor prep into lfa_usb_prep_sysfs so the
attach and automatic paths share one implementation.
`lfa usb storage` lists the volumes Android mounts for apps under
/storage/<VOLUME-ID> (the FUSE view), with filesystem, size, free space
and a real read/write probe. Sessions started by LFA bind the first card at
/mnt/sdcard, further cards at /mnt/<VOLUME-ID>, and internal storage at
/sdcard, with mount points created inside the rootfs.

The binds are exported before every auto-mode exit path, so a card is
available even when no USB device (or no preload) is present. The block
device itself stays out of reach: Android's usb-storage owns the reader's
interface and proot has no block layer, which the docs now state plainly
along with the termux-storage-get fallback.

Also pins LFA_USB_SYSFS in the suite so a real device on the build host
cannot shadow the fake scan cache.
proot-distro v5 already binds /storage and internal storage at /sdcard and
/mnt/sdcard, so our /sdcard bind was a duplicate and /mnt/sdcard collided
with its destination - proot printed two overlap warnings per session.

Cards now go to /media/<VOLUME-ID>, with /mnt/card following the largest
volume. That also keeps a Ventoy card's 32 MB VTOYEFI partition out of the
alias, so /mnt/card is the exFAT data partition where ISOs are copied.
Internal storage is left entirely to proot-distro.
`lfa usb block` shows the card's real backing device
(/dev/block/vold/public:X,Y) and why an app cannot open it: /dev/block is
not searchable, the node is 0660 root:media_rw outside the app namespace,
and untrusted_app may not open block devices.

`lfa usb block write IMAGE` plans a raw write and, with root and --yes,
unmounts via sm, dd's the image with conv=fsync, reads the same byte range
back and compares SHA-256 before remounting. Without root it exits 3 and
explains itself.

Deliberately not implemented: a simulated /dev/sdb1. dd and Ventoy would
report success while writing to a regular file, leaving the card untouched,
which is the worst outcome for a flashing tool. Files stay available through
Android's own mount (lfa usb storage).

Docs cover the three barriers, the root path (including binding the node
into a guest, since proot's /dev is synthetic) and the Ventoy-without-raw-
writes workflow. Nine new Y11 checks pin the report, the JSON and the
refusal; suite count 848.
The block layer is not the only way to the sectors; it is only the way the
kernel offers. Android's USB host API can detach the usb-storage driver
from the descriptor termux-usb grants, after which the app can speak USB
Mass Storage Bulk-Only Transport itself. That is how EtchDroid flashes
drives unrooted, and it is what this command does.

`lfa usb bot --probe` is read-only: INQUIRY, READ CAPACITY(10) and sector 0
are decoded into a device line, size, MBR/GPT table and partitions, with
--json for scripts. `--write IMAGE --yes` sends WRITE(10) in 1 MiB chunks,
SYNCHRONIZE CACHE(10), then reads the same range back and compares it, so a
refused or truncated transfer cannot be mistaken for a good flash.

The driver detach means the card leaves /storage until the reader is
replugged; the command says so before doing anything. A ROM that refuses
the detach surfaces the real errno instead of a simulated success. The
script has a --selftest covering CBW/CSW layout, descriptor parsing and MBR
decoding so CI exercises the protocol without a device.
The driver detach removes the card from /storage, and releasing the
interface does not make Android rebind usb-storage; the reader has to be
replugged. Say that after the probe too, not only after a write.
The README summary line still said 848 while the suite now runs 853
checks, which the Z section reports as a stale count.
A block device cannot exist inside proot, but a file can, and the real
tools accept files. `lfa usb bot --export FILE` streams the card into a
sparse image (1 MiB all-zero chunks become holes); `--import FILE --yes`
compares each chunk with the card, writes only the differences and reads
those back to verify.

That makes fdisk, sfdisk, parted, mkfs.*, dd and fsck usable on the card
from a desktop session, which is as close to "a real disk in Linux" as the
container allows. losetup, mount -o loop and installers that demand
S_ISBLK (Ventoy2Disk) remain impossible, and the docs say so.
The kernel header defines it with _IOC_READ, and usbfs compares the whole
32-bit command, so the wrong direction bit never reaches the permission or
driver checks: every attempt came back ENOTTY ("inappropriate ioctl"), which
reads like a ROM restriction but is not.

The --selftest now pins every ioctl encoding this script uses against the
numbers from <linux/usbdevice_fs.h>, so a mismatch fails in CI instead of on
a phone, and an ENOTTY at runtime says plainly that it is an LFA bug.
bulk_transfer() returned the transfer buffer for both directions, so the
first CBW comparison did `bytes != int` and raised TypeError before any SCSI
command ran.

Split transfers into MAX_BULK slices: usbfs refuses a single BULK request
larger than 16 KiB, which would have broken every 1 MiB read and write as
soon as the probe got past TEST UNIT READY. A bulk pipe is a stream, so the
device sees the same bytes.

Also issue the Bulk-Only reset right after claiming: usb-storage may have
been interrupted mid-command when the driver was detached. Unexpected
exceptions at the CLI boundary now print one line instead of a traceback.
…vice

The probe now reads each partition's boot sector and prints its filesystem
and volume label, so an existing Ventoy card is obvious: the 32 MB
type-0xef partition carries the VTOYEFI label, and the report says to put
ISOs on the data partition instead of flashing. The labels are in --json
too.

A detach makes Android re-enumerate the reader (001/002 became 001/003 for
the next command), so `lfa usb bot` refreshes the cached device list before
choosing the only visible device.
Unbinding usb-storage is one-way from userspace: releasing the interface does
not make the driver core probe again, so after a probe the card stayed gone
from /storage until the reader was physically replugged.

After a command, check /proc/mounts for a removable volume; if there is none,
issue USBDEVFS_RESET and look again, reporting which of the two happened.
A refused reset falls back to telling the user to replug, instead of claiming
the card is back.

The probe also prints the filesystem and label of each partition now, which
is how an existing Ventoy card is recognised (FAT16 "VTOYEFI"), and the docs
warn that a FAT32 data partition cannot hold an ISO over 4 GiB.
USBDEVFS_CONNECT makes the driver core attach an unclaimed interface again,
which is what Android's vold needs to see the card and mount it. It is the
first thing tried after a session now; USBDEVFS_RESET (re-enumeration) is the
fallback, and the mount table is polled for a few seconds between them. If
neither brings the volume back, the message says to replug instead of
assuming it worked.

Progress lines no longer use carriage returns when stderr is a pipe: a
redirected run prints one line per 10% instead of a single mangled line.
`--import` sent SYNCHRONIZE CACHE(10) even when every chunk matched and
nothing had been written. This 14cd:1212 bridge answers that command with a
15 s stall, so a successful comparison ended in ETIMEDOUT right after 100%.

The flush now runs only when something was actually written, a refused flush
is a warning (the read-back is the real check), and read/write failures carry
the byte offset they stopped at. The "Android refused the detach" hint is
only printed for claim errors; mid-transfer failures suggest a replug.
A 15 s timeout per attempt is far too long for a command this bridge simply
does not implement; the flush now fails after 4 s with no retry, and the
transport is reset before verification so a wedged bridge does not make the
read-back look like a bad write.

Verification reads retry once after a reset, changed chunk offsets are
printed (the FAT32 boot sector of partition 1 is byte 1048576, so a diff
there is Android's own mount metadata, not corruption), and a mismatch now
distinguishes "could not read" from "read different bytes".
This 14cd:1212 bridge occasionally drops the USB link under sustained load
(EPROTO partway through a 7.4 GB read), so every chunk read now gets up to
three attempts with a Bulk-Only reset and CLEAR_HALT between them, and
ENODEV/ESHUTDOWN stop immediately instead of retrying a dead descriptor.

--export writes its offset to FILE.lfa-progress every 32 MiB and removes it
on success, so a dropped link costs a re-run rather than the whole read.
--import is already restartable by nature: chunks that reached the card match
the image next time and are skipped.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant