[Feature Request] 비루팅 Android/Termux 환경을 위한 proroot 전용 USB Compatibility Layer 제안

[hansm629]

@coderredlab
안녕하세요. 선생님!
불철주야 개발에 기여해주셔서 정말 감사드립니다.

오늘은 proroot 관련 기능 제안 하나 드리고자 이슈를 리포팅하였습니다!

해당 기능은 proroot 본질적인 목적인
오버헤드 개선과는 거리가 있지만 그동안 proot에서 지적 받던 오버헤드와 더불어
많은 유저들이 필요로 하는 기능이고 프로덕트 완성도를 크게 높여줄 수 있는 기능이라 생각합니다.

현재 비루팅 Android/Termux 환경에서 MANAGE_EXTERNAL_STORAGE권한이 부여된 Termux App을 사용 했을 시,
USB 스토리지는 Android가 /storage/XXXX-XXXX 형태로 마운트 가능하고 이를 proot 내부에 bind해서 읽기/쓰기가 가능합니다.

하지만 스토리지를 제외한 일반 USB 장치들은 여전히 사용이 어렵습니다.

예를 들면 다음과 같은 장치들입니다.

- USB serial adapter
- HID/custom USB device
- gamepad/input device
- UVC camera
- USB DAC/audio device
- RTL-SDR류 장치
- MCU flashing/debugging device

Termux에는 termux-usb를 통해 Android USB Host 권한을 요청하고, 열린 USB device FD를 프로세스에 전달하는 기능이 있습니다.

이 FD를 proroot guest 내부의 Linux/glibc 프로그램이 사용할 수 있도록 연결해주는 USB compatibility layer 또는 FD bridge 기능이 있으면,
비루팅 Android 환경에서도 일부 USB 장치를 Linux 프로그램에서 사용할 가능성이 생길 것 같아 제안드립니다.

목표

비루팅 Android + Termux + proroot 환경에서 일반 USB 장치를 Linux 프로그램이 사용할 수 있도록 하는 compatibility layer를 제공하는 것입니다.

단, 초기 목표는 완전한 chroot 수준의 USB/udev/kernel device 에뮬레이션이 아니라, termux-usb가 제공하는 USB FD를 proroot 내부 프로그램까지 전달하고, 이를 libusb 기반 프로그램에서 사용할 수 있게 하는 것이 어떨까 생각합니다.

1차 구현 제안: libusb/USB serial 중심

최소 MVP이자 가장 먼저 구현해볼 수 있는 최소 기능으로 여겨지는건 다음과 같습니다.

• termux-usb로 얻은 USB device FD를 proroot guest 프로세스까지 전달
• guest 내부에서 해당 FD 번호를 안정적으로 유지
• libusb_wrap_sys_device() 기반으로 열린 FD를 libusb handle로 변환
• 특정 libusb 기반 프로그램 1~2개에서 동작 검증

예상 구조는 다음과 같습니다.

Android UsbManager
→ termux-usb
→ USB 권한 승인
→ opened USB device FD 확보
→ proroot guest process로 FD 전달
→ libusb_wrap_sys_device()
→ libusb 기반 프로그램에서 USB 장치 사용

1-1. libusb shim 확장

MVP가 가능하다면 다음 단계로 libusb shim을 고려할 수 있을 것 같습니다.

예상 기능은 다음과 같습니다.

• proroot 내부 프로그램의 libusb 접근을 shim에서 중개
• libusb_get_device_list()에 대해 Android/Termux 쪽 USB 장치 목록을 반영
• libusb_open() 시 termux-usb/USB broker를 통해 FD 확보
• 확보한 FD를 libusb_wrap_sys_device()로 변환
• 필요 시 최소한의 /dev/bus/usb 호환 계층 제공

이 단계가 구현되면, 개별 프로그램마다 --usb-fd 옵션을 패치하지 않아도 일부 libusb 기반 프로그램을
더 자연스럽게 사용할 수 있을 가능성이 있습니다.

1-2. USB serial → PTY bridge

USB serial 장치는 별도 실용 확장으로 가치가 높을 것 같습니다.

예상 구조는 다음과 같습니다.

USB serial adapter
→ termux-usb / Android USB Host API
→ userspace USB serial driver
→ PTY 생성
→ proroot 내부에 /dev/ttyUSB0 비슷한 경로로 bind

이렇게 되면 proroot 내부에서 다음과 같은 형태의 사용이 가능해질 수 있습니다.

screen /dev/ttyUSB0 115200
minicom -D /dev/ttyUSB0

단, 이건 실제 커널 ttyUSB0이 아니라 PTY 기반 bridge이므로
일부 termios/ioctl, modem control, flow control 기능은 별도 구현이 필요할 수 있습니다.

2차 구현 제안: class device compatibility layer

1차 구현이 libusb/USB serial 중심이라면, 2차 구현은 input/video/audio 같은 Linux class device를 Android API 또는 userspace bridge로 흉내내는 방향이 될 것 같습니다.

2-1. HID/gamepad input shim 또는 제한적 evdev compatibility layer

비루팅 Android 환경에서는 /dev/input/eventX나 /dev/uinput 접근이 어렵기 때문에,
완전한 evdev 에뮬레이션은 난이도가 높을 것 같습니다.

현실적인 1차 목표는 다음과 같을 수 있습니다.

• HID/gamepad 입력을 Android Input 또는 USB Host API로 수집
• SDL/GLFW/X11/input 관련 경로에 전달할 수 있는 shim 구현
• 필요 시 제한적인 evdev compatibility layer 제공

즉, 초기 목표는 완전한 /dev/input/eventX 구현이 아니라,
게임패드나 일부 HID 입력 장치를 Linux 프로그램에서 사용할 수 있게 하는 것입니다.

2-2. UVC camera frame bridge → V4L2 ioctl compatibility layer

UVC 카메라는 Linux에서는 일반적으로 /dev/video0와 V4L2 ioctl을 통해 사용합니다.

하지만 비루팅 Android/proroot 환경에서는 실제 V4L2 device node를 만들기 어렵기 때문에,
단계적으로 접근하는 것이 현실적일 것 같습니다.

예상 단계는 다음과 같습니다.
현실적인 1차 목표는 다음과 같을 수 있습니다.

1. Android USB Host API 또는 별도 UVC userspace 처리로 frame 획득
2. MJPEG/YUYV/H.264 frame stream을 pipe/socket/shared memory로 proroot 내부에 전달
3. ffmpeg, GStreamer, OpenCV 등 특정 앱/프레임워크용 입력 wrapper 제공
4. 필요 시 제한적인 V4L2 ioctl compatibility layer 구현

초기 목표는 완전한 /dev/video0 구현이 아니라, UVC frame bridge부터 시작하는 것이 현실적일 것 같습니다.

2-3. PulseAudio/ALSA client → Android AudioTrack/AAudio/Oboe bridge

USB DAC/audio device의 경우 Linux에서는 ALSA/PulseAudio/PipeWire 장치로 노출되는 것이 일반적입니다.

하지만 비루팅 Android 환경에서는 실제 ALSA USB device를 proroot 내부에 노출하기 어렵기 때문에, USB DAC을 직접 ALSA 장치로 만드는 것보다는 Android audio stack과 연결하는 bridge가 현실적일 것 같습니다.

예상 구조는 다음과 같습니다.

proroot 내부 Linux audio client
→ PulseAudio/ALSA compatibility layer
→ Termux/Android-side audio bridge
→ Android AudioTrack / AAudio / Oboe
→ Android가 선택한 출력 장치
→ USB DAC 또는 기본 오디오 출력

즉, USB DAC 전용 구현이라기보다는 Linux audio client를 Android audio stack으로 연결하는 bridge 형태가 적절해 보입니다.

비목표

초기 구현에서 다음 항목들은 비목표로 두는 것이 현실적일 것 같습니다.

• udev 완전 구현
• 커널 USB 드라이버 로딩
• 실제 /dev/ttyUSB0, /dev/video0, /dev/input/eventX 자동 생성
• V4L2/ALSA/evdev 완전 에뮬레이션
• 모든 USB 장치의 범용 지원
• Android SELinux/App sandbox 제한 우회
• 진짜 chroot와 동일한 USB subsystem 제공

기대 효과

이 기능이 구현되면 비루팅 Android + Termux + proroot 환경에서 다음과 같은 사용성이 가능해질 수 있습니다.

• libusb 기반 USB 장치 사용
• MCU flashing/debugging tool 사용
• HID/custom USB tool 사용
• RTL-SDR류 장치 사용 가능성 확보
• USB serial adapter를 PTY bridge로 사용
• 이후 input/video/audio class device compatibility layer로 확장 가능

proroot가 기존 proot 대비 syscall/path translation 오버헤드를 줄여 실사용성을 크게 개선한 것처럼, USB 쪽에서도 Android USB 권한/FD 모델을 Linux libusb/serial 모델로 번역하는 compatibility layer를 제공하면 비루팅 Android 환경의 활용 범위가 크게 넓어질 것 같습니다.

최종정리

1차 구현: libusb/USB serial 중심 USB compatibility layer

• termux-usb FD broker
• libusb_wrap_sys_device() 기반 FD bridge
• libusb shim
• USB serial → PTY bridge

2차 구현: Linux class device compatibility layer

• HID/gamepad input shim 또는 제한적 evdev compatibility layer
• UVC camera frame bridge 후, 필요 시 V4L2 ioctl compatibility layer
• PulseAudio/ALSA client → Android AudioTrack/AAudio/Oboe bridge

완전한 chroot 대체라기보다는, 비루팅 Android 환경에서 proroot의 실사용 범위를 chroot에 더 가깝게 확장하는 기능으로 볼 수 있을 것 같습니다.
(이미 성능은 bionic 네이티브 혹은 chroot와 동급이라고 생각합니다.)

구현 공수가 큰 기능이라는 점 알고있지만, proroot의 compatibility feature 방향성과도 잘 맞을 수 있는 주제 같아 제안드립니다.

검토 부탁드리며,
다시 한번 proroot 개발에 기여해주셔서 정말 감사드립니다! :)

[coderredlab]

@hansm629 안녕하세요. 길고 정성스러운 제안 정말 감사합니다.

핵심 아이디어 — Android UsbManager 의 FD 를 guest 의 libusb 까지 전달해 libusb_wrap_sys_device() 로 wrap, 그 위에 PTY / class device shim 을 단계적으로 — 는 architectural 으로 깔끔하고 비루팅 Android 환경의 Linux 활용 범위를 크게 넓힐 수 있는 방향이라 생각합니다.

다만 진행 방향은 spec 의 abstraction 을 한 칸 위로 잡으려 합니다.

proroot 의 포지셔닝: proroot 는 기본적으로 자체 APK 앱을 위한 Linux userland runtime 라이브러리 성격이 강합니다. Android 앱이 본인의 jniLibs 에 proroot 바이너리를 넣고, 본인의 Kotlin/Java 코드로 host integration (UI / USB / audio / etc) 을 직접 책임지는 모델입니다. Termux 호환은 부수적으로 따라오는 것이지 first-class target 은 아닙니다.

그래서 spec 에 termux-usb 가 hard contract 으로 들어가면 본질과 충돌합니다. 우리가 잡으려는 방향은:

[임의의 host APK]
  Android UsbManager.requestPermission(device)
  UsbDeviceConnection.openDevice() → getFileDescriptor() → int fd
  proroot launcher 호출 시 FD inherit + 환경변수 전달

[proroot]
  launcher 가 env 보고 FD 보존
  guest 의 libusb 가 libusb_wrap_sys_device(fd) 로 wrap

Termux 도 termux-usb 가 위 contract 를 충족하는 wrapper 를 만들면 자연스럽게 호환됩니다. 단 우리가 reference 로 정의하는 건 host-app-agnostic 한 FD passthrough contract 자체입니다.

기술적 검토: 1차 (libusb FD passthrough) 는 사실상 zero-cost 로 가능할 가능성이 큽니다. exec chain 에서 FD 는 O_CLOEXEC 안 걸린 채로 자동 inherit 되고 libusb_wrap_sys_device() (libusb 1.0.23+) 가 그 위에서 동작합니다. 단 외부 (Bionic / ROM) seccomp 이 USBDEVFS ioctl 을 차단하는지는 ROM-dependent — issue #4 의 HyperOS clone3 trap 과 같은 패턴이라 실측 검증이 필요합니다.

우선순위: 현재 v1.x 라인은 issue #3 의 9 FAIL 진단 + issue #4 / #5 의 v1.2.2 stable 승격이 우선입니다. 그 이후 USB compatibility layer 트랙으로 진입 예정이고, design doc 정해지면 다시 공유하겠습니다.

다시 한 번 좋은 제안 감사드립니다 :)

[hansm629]

@coderredlab
자세한 답변 감사합니다!
proroot 프로젝트의 방향성을 명확히 알수있게 되어서 너무 좋았습니다.
말씀해주신대로라면 Termux에 종속되지 않은 완벽한 리눅스 환경이 꾸려질거 같아서 오히려 더욱 기대되네요!

사실 Termux가 일반인들이 접근하기엔 허들이 좀 많이 높은편이라 저도 예전부터
안드로이드 환경에서 리눅스가 APK 형태로 제공되어서 일반인들도 설치 후, 원탭(원클릭)만으로 실행해서 사용할 방법 없을까?

하고 생각했는데 proroot 덕분에 아래와 같은 APK 1개의 형태로 배포되어 일반인들도 쉽게
안드로이드 호스트 디바이스에서 리눅스 컨테이너를 네이티브 성능급으로 사용할것으로 전망되어서 너무 좋네요!

Android APK
└─ app private dir
   ├─ proroot 런타임/라이브러리
   │    ├─ libproroot.so
   │    ├─ libproroot-runtime.so
   │    ├─ libproroot-bridge.so
   │    └─ libproroot-linker.so
   │
   └─ files/rootfs/
         └─ linux arm64 glibc rootfs
   └─ X11 server
         └─ termux-x11 backend base

x11vnc를 통해서 X서버를 사용하기보단 (성능이 너무 떨어지기에)
termux-x11 X서버를 내장해서 GUI 구현하면 딱일듯 합니다.

게다가 최근
Linux Plumbers Conference 2025의 Android MC 세션에서 구글 엔지니어가
안드로이드 AVF 관련 발표 때 이후, 과제로 안드로이드 위 Wayland compositor 통합이 있더라구요!

현재 구글 카나리아 빌드 기준, AVF에서 디스플레이 서버 구현은 Weston + Kiosk Shell 조합(AHB에 직접 렌더링)으로
작동하는데, 쉘 구조가 아닌 안드로이드 자체에 Wayland를 내장해서 작동되게끔 하는게 목표인걸로 보입니다.

이게 적용되면
Android surface 위에서 Wayland surface가 오버레이 형태로 작동하지 않을까 추측합니다.
이러면 x11vnc나 termux-x11 없어도 리눅스에서 제대로 된 디스플레이 서버를 쓸 수 있을것으로 전망합니다.

미래의 이야기가 너무 길어졌네요! ㅎㅎㅎ

말씀처럼 termux-usb를 hard contract로 두기보다는, host-app-agnostic한 FD passthrough contract를 proroot 쪽 기준으로 잡고,
Termux는 그 contract를 만족하는 wrapper 형태로 따라가는 구조가 더 적절해 보입니다.

1차 libusb FD passthrough가 zero-cost에 가깝게 가능성이 있다면, 이후 design doc이 공유되었을 때 Termux 환경에서 테스트할 수 있는 장치들로 검증해보겠습니다.

특히 OneUI/Samsung 계열에서는 USBDEVFS ioctl이나 seccomp 관련 ROM-dependent 이슈가 있을 수 있으니, 필요하면 실제 기기에서 termux-usb FD 전달 + libusb_wrap_sys_device() 테스트를 도와드리겠습니다.

우선 v1.x 안정화 이후 USB compatibility layer 트랙으로 넘어가면 다시 확인해보겠습니다.
감사합니다!