Add opt-in linear KMS capture prototype with explicit security limitations

This commit is contained in:
VallierDev committed 2026-10-15 10:49:12 +08:00
1 parent f123f0ba05
commit d461ef9bed
13 files changed
+241 -8

No files matched your search

+11
View File
@@ -275,3 +275,14 @@ xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`.
Rolling Arch FFmpeg may be newer than supported `inproc-av` (FFmpeg 6.x); use the default process
pipeline or build against a separate FFmpeg 6 prefix. Do not downgrade the system FFmpeg.
User-bus headless setup and the official Mac checklist: [virtual desktop acceptance](contrib/virtual-desktop/ACCEPTANCE.md).
### Experimental KMS / 实验后端
`--features kms` plus explicit `UU_DESKTOP_BACKEND=kms` enables a limited linear-framebuffer
prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted
`cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges.
Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use.
Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard
is unavailable without a desktop session. No default release behavior changes.
For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md);
the existing offer behavior is retained.
+2
View File
@@ -16,6 +16,8 @@ path = "src/main.rs"
[features]
default = []
wayland = []
# Experimental direct linear framebuffer capture; never enabled in release builds.
kms = []
portal = []
# In-process capture and encoding through FFmpeg 6 libraries (libavcodec/libavdevice dev packages).
# Off by default so release binaries do not link the build machine's libav.
+11
View File
@@ -313,3 +313,14 @@ xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`.
Rolling Arch FFmpeg may be newer than supported `inproc-av` (FFmpeg 6.x); use the default process
pipeline or build against a separate FFmpeg 6 prefix. Do not downgrade the system FFmpeg.
User-bus headless setup and the official Mac checklist: [virtual desktop acceptance](contrib/virtual-desktop/ACCEPTANCE.md).
### Experimental KMS / 实验后端
`--features kms` plus explicit `UU_DESKTOP_BACKEND=kms` enables a limited linear-framebuffer
prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted
`cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges.
Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use.
Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard
is unavailable without a desktop session. No default release behavior changes.
For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md);
the existing offer behavior is retained.
+11
View File
@@ -295,3 +295,14 @@ xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`.
Rolling Arch FFmpeg may be newer than supported `inproc-av` (FFmpeg 6.x); use the default process
pipeline or build against a separate FFmpeg 6 prefix. Do not downgrade the system FFmpeg.
User-bus headless setup and the official Mac checklist: [virtual desktop acceptance](contrib/virtual-desktop/ACCEPTANCE.md).
### Experimental KMS / 实验后端
`--features kms` plus explicit `UU_DESKTOP_BACKEND=kms` enables a limited linear-framebuffer
prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted
`cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges.
Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use.
Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard
is unavailable without a desktop session. No default release behavior changes.
For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md);
the existing offer behavior is retained.
+10
View File
@@ -9,6 +9,16 @@ fn main() {
let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
if target_os == "linux" {
if std::env::var_os("CARGO_FEATURE_KMS").is_some() {
println!("cargo:rerun-if-changed=c_engine/kms_engine.c");
let output=std::process::Command::new("pkg-config").args(["--cflags","libdrm"]).output().expect("KMS requires pkg-config and libdrm development headers");
assert!(output.status.success(), "KMS requires libdrm development headers");
let mut build=cc::Build::new();
build.file("c_engine/kms_engine.c");
for flag in String::from_utf8_lossy(&output.stdout).split_whitespace() { build.flag(flag); }
build.compile("uu_kms_engine");
println!("cargo:rustc-link-lib=drm");
}
cc::Build::new()
.file("c_engine/x11_engine.c")
.file("c_engine/clipboard.c")
+100
View File
@@ -0,0 +1,100 @@
/* Opt-in KMS prototype: read active primary-plane linear XRGB/ARGB buffers.
* No modesetting, DRM master acquisition, authentication or content logging.
*/
#include <xf86drm.h>
#include <xf86drmMode.h>
#include <drm_fourcc.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <errno.h>
struct uu_kms { int fd; uint32_t crtc, plane, width, height; };
static uint32_t primary_plane(int fd, uint32_t crtc_id) {
drmModePlaneRes *planes=drmModeGetPlaneResources(fd);
if (!planes) return 0;
uint32_t selected=0;
for (uint32_t i=0;i<planes->count_planes && !selected;i++) {
drmModePlane *plane=drmModeGetPlane(fd,planes->planes[i]);
if (plane && plane->crtc_id==crtc_id && plane->fb_id) {
drmModeObjectProperties *props=drmModeObjectGetProperties(fd,plane->plane_id,DRM_MODE_OBJECT_PLANE);
if (props) {
for (uint32_t j=0;j<props->count_props;j++) {
drmModePropertyRes *prop=drmModeGetProperty(fd,props->props[j]);
if (prop && strcmp(prop->name,"type")==0 && props->prop_values[j]==DRM_PLANE_TYPE_PRIMARY) selected=plane->plane_id;
if (prop) drmModeFreeProperty(prop);
}
drmModeFreeObjectProperties(props);
}
}
if (plane) drmModeFreePlane(plane);
}
drmModeFreePlaneResources(planes);
return selected;
}
static void close_handles(int fd, drmModeFB2 *fb) {
for (int i=0;i<4;i++) {
if (!fb->handles[i]) continue;
int duplicate=0;
for (int j=0;j<i;j++) if (fb->handles[j]==fb->handles[i]) duplicate=1;
if (!duplicate) { struct drm_gem_close c={.handle=fb->handles[i]}; drmIoctl(fd,DRM_IOCTL_GEM_CLOSE,&c); }
}
}
void uu_kms_close(struct uu_kms *s) { if (s) { close(s->fd); free(s); } }
struct uu_kms *uu_kms_open(const char *device, uint32_t *w, uint32_t *h) {
int fd=open(device,O_RDWR|O_CLOEXEC);
if (fd<0) return NULL;
if (drmSetClientCap(fd,DRM_CLIENT_CAP_UNIVERSAL_PLANES,1)<0) { close(fd); return NULL; }
drmModeRes *res=drmModeGetResources(fd);
if (!res) { close(fd); return NULL; }
struct uu_kms *s=NULL;
for (int i=0;i<res->count_crtcs;i++) {
drmModeCrtc *crtc=drmModeGetCrtc(fd,res->crtcs[i]);
uint32_t plane=crtc ? primary_plane(fd,crtc->crtc_id) : 0;
if (crtc && plane && crtc->mode_valid && crtc->width && crtc->height && crtc->width<=16384 && crtc->height<=16384) {
s=calloc(1,sizeof(*s));
if (s) { s->fd=fd; s->crtc=crtc->crtc_id; s->plane=plane; s->width=crtc->width; s->height=crtc->height; *w=s->width; *h=s->height; }
}
if (crtc) drmModeFreeCrtc(crtc);
if (s) break;
}
drmModeFreeResources(res);
if (!s) close(fd);
return s;
}
int uu_kms_read(struct uu_kms *s, uint8_t *out, size_t length) {
drmModeCrtc *crtc=drmModeGetCrtc(s->fd,s->crtc);
if (!crtc) return -1;
drmModePlane *plane=drmModeGetPlane(s->fd,s->plane);
uint32_t id=plane ? plane->fb_id : 0;
if (plane) drmModeFreePlane(plane);
int valid=crtc->mode_valid && crtc->width==s->width && crtc->height==s->height;
drmModeFreeCrtc(crtc);
if (!valid || !id) return -2; /* mode changed: caller must reopen */
drmModeFB2 *fb=drmModeGetFB2(s->fd,id);
if (!fb) return -3;
int result=-4;
if (!fb->handles[0]) { result=-5; goto done; } /* DRM master or CAP_SYS_ADMIN needed */
if (fb->width!=s->width || fb->height!=s->height ||
(fb->pixel_format!=DRM_FORMAT_XRGB8888 && fb->pixel_format!=DRM_FORMAT_ARGB8888) ||
((fb->flags & DRM_MODE_FB_MODIFIERS) && fb->modifier!=DRM_FORMAT_MOD_LINEAR) ||
fb->handles[1] || fb->pitches[0] < s->width*4 || length!=(size_t)s->width*s->height*4) goto done;
struct drm_mode_map_dumb map={.handle=fb->handles[0]};
if (drmIoctl(s->fd,DRM_IOCTL_MODE_MAP_DUMB,&map)<0) { result=-6; goto done; }
size_t bytes=(size_t)fb->pitches[0]*fb->height+fb->offsets[0];
void *data=mmap(NULL,bytes,PROT_READ,MAP_SHARED,s->fd,map.offset);
if (data==MAP_FAILED) { result=-7; goto done; }
for (uint32_t y=0;y<s->height;y++) {
uint8_t *row=out+(size_t)y*s->width*4;
memcpy(row,(uint8_t*)data+fb->offsets[0]+(size_t)y*fb->pitches[0],s->width*4);
for (uint32_t x=0;x<s->width;x++) row[x*4+3]=255;
}
munmap(data,bytes);
result=0;
done:
close_handles(s->fd,fb);
drmModeFreeFB2(fb);
return result;
}
+13 -3
View File
@@ -46,6 +46,7 @@ pub struct ScreenCapture {
pub init_error: Option<String>,
pub portal: Option<std::sync::Arc<crate::portal::PortalSession>>,
pub display: String,
kms: Option<crate::kms::Capture>,
pub width: u32,
pub height: u32,
buffer: Mutex<Vec<u8>>,
@@ -54,15 +55,21 @@ pub struct ScreenCapture {
impl ScreenCapture {
pub fn new() -> Result<Self, String> {
let backend=crate::desktop_backend::detect()?;
if backend == crate::desktop_backend::DesktopBackend::Kms {
let kms=crate::kms::Capture::open()?;
let (width,height)=(kms.width,kms.height);
return Ok(Self { backend,init_error:None,portal:None,display:"kms:linear".into(),width,height,
buffer:Mutex::new(vec![0;width as usize*height as usize*4]),kms:Some(kms) });
}
if backend == crate::desktop_backend::DesktopBackend::Portal {
let session=std::sync::Arc::new(crate::portal::PortalSession::open()?);
let (width,height)=(session.width,session.height);
return Ok(Self { backend,init_error:None,portal:Some(session),display:"wayland:portal".into(),width,height,
return Ok(Self { backend,init_error:None,portal:Some(session),kms:None,display:"wayland:portal".into(),width,height,
buffer:Mutex::new(vec![0;(width as usize)*(height as usize)*4]) });
}
if backend == crate::desktop_backend::DesktopBackend::Wayland {
let (width,height)=crate::wayland::init()?;
return Ok(Self { backend, init_error:None, portal:None, display:"wayland:native".into(), width,height,
return Ok(Self { backend, init_error:None, portal:None, kms:None, display:"wayland:native".into(), width,height,
buffer:Mutex::new(vec![0;(width as usize)*(height as usize)*4]) });
}
let ret = unsafe { x11_init(std::ptr::null()) };
@@ -90,6 +97,7 @@ impl ScreenCapture {
backend,
init_error:None,
portal:None,
kms:None,
display,
width: w as u32,
height: h as u32,
@@ -100,13 +108,14 @@ impl ScreenCapture {
/// Metadata for non-desktop tools. Never advertise a usable fake screen.
pub fn unavailable(error:String)->Self {
Self { backend:crate::desktop_backend::detect().unwrap_or(crate::desktop_backend::DesktopBackend::X11),
init_error:Some(error), portal:None, display:String::new(), width:0,height:0,buffer:Mutex::new(Vec::new()) }
init_error:Some(error), portal:None, kms:None, display:String::new(), width:0,height:0,buffer:Mutex::new(Vec::new()) }
}
/// 截取一帧 BGRA 图像
pub fn capture_frame(&self) -> Result<Vec<u8>, String> {
if let Some(error)=&self.init_error { return Err(error.clone()); }
let mut buf = self.buffer.lock().unwrap();
if let Some(kms)=&self.kms { kms.capture(&mut buf)?; return Ok(buf.clone()); }
if let Some(session)=&self.portal { session.capture(&mut buf)?; return Ok(buf.clone()); }
if self.backend == crate::desktop_backend::DesktopBackend::Wayland {
crate::wayland::capture(&mut buf)?;
@@ -132,6 +141,7 @@ impl Drop for ScreenCapture {
/// Keep the display visible only while a peer is streaming; never unlock it.
pub fn keep_display_awake() -> Result<(), String> {
if crate::desktop_backend::detect()? == crate::desktop_backend::DesktopBackend::Kms { return Ok(()); }
if crate::desktop_backend::detect()? == crate::desktop_backend::DesktopBackend::Portal { return Ok(()); }
if crate::desktop_backend::detect()? == crate::desktop_backend::DesktopBackend::Wayland {
return crate::wayland::wake();
+1 -1
View File
@@ -20,7 +20,7 @@ extern "C" {
pub fn start(display: String) -> ClipboardBridge {
if display == "wayland:native" { return start_wayland(); }
if display == "wayland:portal" {
if display == "wayland:portal" || display.starts_with("kms:") {
let (incoming,_)=watch::channel(None);let (_,outgoing)=watch::channel(None);
let (sender,ready)=tokio::sync::oneshot::channel();let _=sender.send(false);
return ClipboardBridge {incoming,outgoing,ready};
+4 -2
View File
@@ -1,6 +1,6 @@
//! Select the host desktop, not the presence of an XWayland DISPLAY socket.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DesktopBackend { X11, Wayland, Portal }
pub enum DesktopBackend { X11, Wayland, Portal, Kms }
/// `UU_DESKTOP_BACKEND=none`: headless host — no display is opened; terminal, file transfer and
/// port mapping stay available (servers without a monitor or logged-in session).
@@ -19,6 +19,7 @@ fn select(explicit: Option<&str>, session: Option<&str>, socket: Option<&str>) -
match explicit {
Some("x11") => Ok(DesktopBackend::X11),
Some("wayland") => Ok(DesktopBackend::Wayland),
Some("kms") => Ok(DesktopBackend::Kms),
Some("portal") => Ok(DesktopBackend::Portal),
Some("none") => Ok(DesktopBackend::X11), // never opened, see headless()
None | Some("auto") => {
@@ -26,7 +27,7 @@ fn select(explicit: Option<&str>, session: Option<&str>, socket: Option<&str>) -
Ok(DesktopBackend::Wayland)
} else { Ok(DesktopBackend::X11) }
},
Some(_) => Err("UU_DESKTOP_BACKEND must be auto, x11, wayland, portal or none".into()),
Some(_) => Err("UU_DESKTOP_BACKEND must be auto, x11, wayland, portal, kms or none".into()),
}
}
@@ -39,6 +40,7 @@ mod tests {
assert_eq!(select(None,None,Some("wayland-1")),Ok(DesktopBackend::Wayland));
assert_eq!(select(None,Some("x11"),None),Ok(DesktopBackend::X11));
assert_eq!(select(Some("x11"),Some("wayland"),Some("wayland-0")),Ok(DesktopBackend::X11));
assert_eq!(select(Some("kms"),Some("wayland"),Some("wayland-0")),Ok(DesktopBackend::Kms));
assert!(select(Some("typo"),None,None).is_err());
}
}
+3
View File
@@ -232,6 +232,7 @@ impl InputInjector {
return Self::uinput_result(uinput.move_absolute(scale(x,w),scale(y,h)));
}
}
if self.backend==crate::desktop_backend::DesktopBackend::Kms { return -1; }
if let Some(portal)=self.portal.lock().unwrap().as_ref() { return self.portal_result("motion", portal.move_pointer(f64::from(x),f64::from(y),relative)); }
if self.backend==crate::desktop_backend::DesktopBackend::Portal {return self.portal_result("motion", Err("Portal input session is not bound".into()));}
if self.backend==crate::desktop_backend::DesktopBackend::Wayland { crate::wayland::move_pointer(x,y,relative) }
@@ -242,6 +243,7 @@ impl InputInjector {
if let Some((v,h))=crate::uinput::wheel_step(button) { return if pressed { Self::uinput_result(uinput.wheel(v,h)) } else { 0 }; }
if let Some(code)=crate::uinput::button_code(button) { return Self::uinput_result(uinput.button(code,pressed)); }
}
if self.backend==crate::desktop_backend::DesktopBackend::Kms { return -1; }
if let Some(portal)=self.portal.lock().unwrap().as_ref() { return self.portal_result("button", portal.button(button,pressed)); }
if self.backend==crate::desktop_backend::DesktopBackend::Portal {return self.portal_result("button", Err("Portal input session is not bound".into()));}
if self.backend==crate::desktop_backend::DesktopBackend::Wayland { crate::wayland::button(button,pressed) }
@@ -251,6 +253,7 @@ impl InputInjector {
if let Some(uinput)=&self.uinput {
if let Some(code)=crate::uinput::keysym_to_evdev(symbol) { return Self::uinput_result(uinput.key(code,pressed)); }
}
if self.backend==crate::desktop_backend::DesktopBackend::Kms { return -1; }
if let Some(portal)=self.portal.lock().unwrap().as_ref() { return self.portal_result("keyboard", portal.key(symbol,pressed)); }
if self.backend==crate::desktop_backend::DesktopBackend::Portal {return self.portal_result("keyboard", Err("Portal input session is not bound".into()));}
if self.backend==crate::desktop_backend::DesktopBackend::Wayland { crate::wayland::key(symbol,pressed) }
+50
View File
@@ -0,0 +1,50 @@
//! Experimental linear KMS framebuffer capture. Never selected automatically.
#[cfg(all(feature="kms",target_os="linux"))]
mod imp {
use std::ffi::CString;
use std::sync::Mutex;
extern "C" {
fn uu_kms_open(device:*const libc::c_char,w:*mut u32,h:*mut u32)->*mut libc::c_void;
fn uu_kms_read(handle:*mut libc::c_void,out:*mut u8,length:usize)->i32;
fn uu_kms_close(handle:*mut libc::c_void);
}
struct Handle(*mut libc::c_void);
// The FD/CRTC handle is exclusively accessed through Capture's mutex.
unsafe impl Send for Handle {}
impl Drop for Handle { fn drop(&mut self) { unsafe { uu_kms_close(self.0) }; } }
pub struct Capture { handle:Mutex<Handle>, pub width:u32, pub height:u32 }
impl Capture {
pub fn open()->Result<Self,String> {
let device=CString::new(std::env::var("UU_KMS_DEVICE").unwrap_or_else(|_|"/dev/dri/card0".into())).map_err(|_|"Invalid KMS device")?;
let (mut width,mut height)=(0,0);
let handle=unsafe { uu_kms_open(device.as_ptr(),&mut width,&mut height) };
if handle.is_null() { return Err("KMS: cannot open an active CRTC; check card permissions and connected output".into()); }
let capture=Self { handle:Mutex::new(Handle(handle)), width,height };
// Do not advertise a desktop until we have actually read the buffer.
let mut frame=vec![0; width as usize*height as usize*4];
capture.capture(&mut frame)?;
if frame.chunks_exact(4).all(|p| p[..3]==[0,0,0]) {
log::warn!("KMS initial frame is uniformly black; GPU buffer visibility is unverified (see KMS limitations)");
}
Ok(capture)
}
pub fn capture(&self,output:&mut [u8])->Result<(),String> {
if output.len()!=self.width as usize*self.height as usize*4 { return Err("KMS: invalid frame dimensions".into()); }
let handle=self.handle.lock().unwrap();
match unsafe { uu_kms_read(handle.0,output.as_mut_ptr(),output.len()) } {
0=>Ok(()), -2=>Err("KMS mode changed; restart host to refresh desktop geometry".into()),
-5=>Err("KMS framebuffer handles unavailable; requires cap_sys_admin+ep".into()),
code=>Err(format!("KMS capture failed ({code}); prototype needs a mappable linear XRGB/ARGB dumb buffer")),
}
}
}
}
#[cfg(all(feature="kms",target_os="linux"))]
pub use imp::Capture;
#[cfg(not(all(feature="kms",target_os="linux")))]
pub struct Capture { pub width:u32, pub height:u32 }
#[cfg(not(all(feature="kms",target_os="linux")))]
impl Capture {
pub fn open()->Result<Self,String> { Err("KMS requires Linux and --features kms".into()) }
pub fn capture(&self,_:&mut [u8])->Result<(),String> { Err("KMS requires Linux and --features kms".into()) }
}
+1
View File
@@ -12,6 +12,7 @@ mod login;
mod login_ui;
mod session_lock;
mod capture;
mod kms;
mod file_trans;
mod input;
mod uinput;
+24 -2
View File
@@ -192,7 +192,13 @@ async fn read_encoder_with(
size: (u32,u32),display:String,portal:Option<Arc<crate::portal::PortalSession>>,latest:mpsc::Sender<Arc<CompleteFrame>>,encoder:Encoder,sequence:Arc<std::sync::atomic::AtomicU64>,
mut settings: VideoSettings, #[cfg_attr(not(feature = "inproc-av"), allow(unused_variables))] idr: Arc<AtomicBool>,
)->Result<(),String>{
let wayland=display.starts_with("wayland:");
let kms=display.starts_with("kms:");
let wayland=kms || display.starts_with("wayland:");
let kms_capture=if kms {
let capture=tokio::task::spawn_blocking(crate::kms::Capture::open).await.map_err(|_|"KMS worker failed")??;
if (capture.width,capture.height)!=size { return Err("KMS mode changed; restart host to refresh desktop geometry".into()); }
Some(Arc::new(capture))
} else { None };
#[cfg(feature = "inproc-av")]
if !wayland && portal.is_none() && crate::inproc_encoder::selected() {
let max_kbps = settings.max_kbps().unwrap_or(30_000) as i64;
@@ -264,7 +270,23 @@ async fn read_encoder_with(
.stderr(std::process::Stdio::inherit())
.spawn().map_err(|e| format!("Start scoped encoder: {e}"))?;
// Scope capture to this encoder. Dropping either task kills its child.
let _capture=if let Some(session)=portal {
let _capture=if let Some(capture)=kms_capture {
let mut sink=child.stdin.take().ok_or("Encoder stdin missing")?;
Some(EncoderTask(tokio::spawn(async move {
use tokio::io::AsyncWriteExt;
let mut tick=tokio::time::interval(Duration::from_nanos(1_000_000_000/u64::from(settings.fps)));
tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
loop {
tick.tick().await;
let capture=capture.clone();
let bytes=tokio::task::spawn_blocking(move || {
let mut bytes=vec![0;capture.width as usize*capture.height as usize*4];
capture.capture(&mut bytes)?; Ok::<_,String>(bytes)
}).await.map_err(|_|"KMS worker failed")??;
sink.write_all(&bytes).await.map_err(|_|"KMS encoder pipe failed")?;
}
})))
} else if let Some(session)=portal {
let mut sink=child.stdin.take().ok_or("Encoder stdin missing")?;
Some(EncoderTask(tokio::spawn(async move {
use tokio::io::AsyncWriteExt;