Re: Proposal on WSDISPLAYIO damage reporting IOCTL

[Michael <macallan1888%gmail.com@localhost>]

Hello,

On Mon, 12 May 2025 13:54:01 +0100
"Jiaxun Yang" <jiaxun.yang%flygoat.com@localhost> wrote:

> I'm new to NetBSD development and have been working on improving display support
> for emulated platforms. This has resulted in a new driver for the Bochs DISPI
> device (PR kern/59410) and enhancements to the not-yet-committed viogpu driver
> (PR kern/58681).
> 
> While implementing X11 userspace support for viogpu, I identified a need for a
> unified WSDISPLAYIO mechanism to report framebuffer damage areas to drivers.
> Unlike conventional dumb framebuffers that continuously scan out VRAM content,
> devices like viogpu (non-VGA compliant variant) require explicit notification
> of damaged areas. The udl(4) driver presents a similar case, where only damaged
> portions of the framebuffer should be transmitted over USB for efficiency.

So, more or less, userland scribbles into framebuffer, then tells the
driver which portions it changed in order to update the actual image
displayed. Sounds useful.
With that we could get rid of the wildcat workaround as well.

> Other Unix systems handled this differently:
> - Linux FBDEV created device-specific IOCTLs for udlfb, though plans for a unified
>   approach were superseded by DRM adoption
> - OpenBSD implemented a device-specific IOCTL for udl(4) (which was commented out when
>   ported to NetBSD)
> 
> 
> I propose the following unified IOCTL interface:
> 
> ```
> --- a/sys/dev/wscons/wsconsio.h
> +++ b/sys/dev/wscons/wsconsio.h
> @@ -688,6 +688,7 @@ struct wsdisplayio_fbinfo {
>  /* fbi_flags */
>  #define WSFB_VRAM_IS_RAM       0x0001  /* hint for wsfb - don't shadow */
>  #define WSFB_VRAM_IS_SPLIT     0x0002  /* workaround for wildcat... */
> +#define WSFB_VRAM_NEEDS_DAMAGE 0x0004  /* framebuffer needs damage reporting */
>  
>  #define WSDISPLAYIO_GET_FBINFO _IOWR('W', 104, struct wsdisplayio_fbinfo)
>  
> @@ -747,4 +748,20 @@ struct wsdisplay_getfont {
>  
>  #define WSDISPLAYIO_GFONT      _IOWR('W', 108, struct wsdisplay_getfont)
>  
> +/*
> + * Repoort framebuffer damage
> + *
> + * Only necessary if WSFB_VRAM_NEEDS_DAMAGE is set in fbi_flags.
> + */
> +
> +struct wsdisplay_damage {
> +       uint32_t        flags;
> +#define WSDISPLAY_DAMAGE_WAIT  0x0001 /* Wait for damage flush to finish */
> +       uint32_t        x;
> +       uint32_t        y;
> +       uint32_t        width;
> +       uint32_t        height;
> +};
> +#define WSDISPLAYIO_DAMAGE     _IOWR('W', 109, struct wsdisplay_damage)
> +
>  #endif /* _DEV_WSCONS_WSCONSIO_H_ */
> ```

Looks good to me.

> This unified approach would allow consistent damage reporting across different
> device types without requiring device-specific implementations.
> 
> There are also some alternative ways to archive similar functionality, such
> as implementing blit from userspace pointer, or implement page flip mechanism
> for WSDISPLAYIO. I'm happy to look into them if damage reporting is deemed
> inappropriate.

I was working on blit support many years ago, there are remnants of it
in wsconsio.h which no driver is currently using. It was intended for X
on shark, but then I ended up writing xf86-video-igs instead.

have fun
Michael