AM01S SubScreen Driver

Linux DRM/DKMS support for the 960×400 internal USB sub-screen found in AM01S-class mini PCs.

中文说明

What this project does

The sub-screen typically enumerates as:

345f:9133 USB Display usb extscreen

The modern MacroSilicon driver recognizes the device and advertises its native 960×400 mode, but its DRM configuration originally rejects framebuffers shorter than 480 pixels. GNOME/Mutter therefore cannot create the native framebuffer and leaves the connector disabled.

This project downloads the tested modern-kernel MS91xx driver, applies the min_height: 480 → 400 fix, installs it through DKMS, and configures the modules to load before the display manager. It also forces Mutter software cursors because the vendor driver exposes no atomic cursor plane.

Hardware status

Item	Value
Confirmed USB ID	345f:9133
Chip	MacroSilicon MS912C
Native mode	960×400@60
USB interface	Vendor-specific interface 3
Driver	usbdisp_drm + usbdisp_usb / msdisp_usb
Desktop tested	GNOME on Wayland
Kernels tested	Ubuntu generic 7.0.0-29 and 7.0.0-30

The upstream driver contains IDs for other MS91xx devices, but this patch is specifically verified on the AM01S 345f:9133 panel.

Installation

Requirements: Debian/Ubuntu, Internet access, sudo, and matching kernel headers.

git clone https://github.com/NOirBRight/AM01S-SubScreen-Driver.git
cd AM01S-SubScreen-Driver
./scripts/install-dkms.sh
sudo reboot

Do not use rmmod to hot-reload the vendor driver. Its teardown path has a known use-after-free risk. Reboot after installation or upgrades.

Verify after reboot:

./scripts/verify-drm.sh
./scripts/verify-cursor.sh

Successful output includes:

Driver=msdisp_usb
connector=cardN-HDMI-A-N status=connected mode=960x400 enabled=enabled
CHECK drm-ready: connected 960x400 connector is enabled

Secure Boot

DKMS signs the modules when distribution signing infrastructure is available. With Secure Boot enabled, MOK enrollment may still be required during reboot.

mokutil --sb-state
sudo dmesg | grep -Ei 'usbdisp|verification|secure boot'

Invisible mouse cursor on GNOME

The vendor DRM driver exposes primary planes but no atomic cursor plane. Modern Mutter may place the pointer on a hardware cursor path that never reaches the USB framebuffer. The installer adds:

MUTTER_DEBUG_DISABLE_HW_CURSORS=1

through /etc/environment.d/90-am01s-subscreen-cursor.conf. This makes Mutter composite the pointer into the framebuffer sent to the sub-screen. A logout or reboot is required. After signing in again, run ./scripts/verify-cursor.sh.

Cursor trails and refresh latency

The vendor atomic update path incorrectly transmits old_state->fb, making the USB output one framebuffer behind. If the pointer leaves the sub-screen and no later commit occurs there, that stale framebuffer can leave a permanent cursor trail. The installer patches the update path to transmit plane->state->fb, the newly committed framebuffer.

The advertised panel mode is already 60 Hz. There is no low fixed FPS limiter in the driver: it compares successive framebuffers and sends the changed bounding rectangle. Small updates such as cursor movement can therefore be much faster than full-screen motion. Full-screen effective refresh remains limited by USB 2.0 bandwidth, color conversion, and synchronous transfer overhead; advertising a mode above 60 Hz does not increase the panel's physical refresh.

Kernel upgrades

DKMS should rebuild automatically. If a newly booted kernel has no module, run the installer again and reboot.

Troubleshooting

lsusb -d 345f:9133
lsusb -t | grep msdisp_usb
lsmod | grep usbdisp
dkms status
grep -E 'min_height|fb = plane->state->fb' /usr/src/msdisp-3.0.3.13/drm/msdisp_drm_modeset.c

The last command should report both dev->mode_config.min_height = 400; and fb = plane->state->fb;.

Uninstall

Do not unload the live modules. Remove the installed files, then reboot:

sudo dkms remove msdisp/3.0.3.13 --all
sudo rm -rf /usr/src/msdisp-3.0.3.13
sudo rm -f /etc/modules-load.d/am01-usb-display.conf
sudo rm -f /etc/environment.d/90-am01s-subscreen-cursor.conf
sudo reboot

中文快速开始

本项目用于点亮 AM01S 上通过内部 USB 连接的 345f:9133、原生分辨率 960×400 的副屏。

驱动原本把 DRM 最小 framebuffer 高度写死为 480，导致桌面环境无法创建 960×400 framebuffer。本项目将其修正为 400，并通过 DKMS 安装。

git clone https://github.com/NOirBRight/AM01S-SubScreen-Driver.git
cd AM01S-SubScreen-Driver
./scripts/install-dkms.sh
sudo reboot
./scripts/verify-drm.sh

请勿使用 rmmod 热卸载驱动；厂商卸载路径存在 UAF 风险，安装或升级后应直接重启。

Upstream and license

The installer downloads bambinounos/ms91xx-linux-drm, a modern-kernel fork of MacroSilicon's GPL driver. The tested upstream revision is pinned in the installer.

Licensed under GNU GPL v2.0. See LICENSE.