^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) What is udlfb?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) This is a driver for DisplayLink USB 2.0 era graphics chips.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) DisplayLink chips provide simple hline/blit operations with some compression,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) pairing that with a hardware framebuffer (16MB) on the other end of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) USB wire. That hardware framebuffer is able to drive the VGA, DVI, or HDMI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) monitor with no CPU involvement until a pixel has to change.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) The CPU or other local resource does all the rendering; optionally compares the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) result with a local shadow of the remote hardware framebuffer to identify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) the minimal set of pixels that have changed; and compresses and sends those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) pixels line-by-line via USB bulk transfers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Because of the efficiency of bulk transfers and a protocol on top that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) does not require any acks - the effect is very low latency that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) can support surprisingly high resolutions with good performance for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) non-gaming and non-video applications.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Mode setting, EDID read, etc are other bulk or control transfers. Mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) setting is very flexible - able to set nearly arbitrary modes from any timing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Advantages of USB graphics in general:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) * Ability to add a nearly arbitrary number of displays to any USB 2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) capable system. On Linux, number of displays is limited by fbdev interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) (FB_MAX is currently 32). Of course, all USB devices on the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) host controller share the same 480Mbs USB 2.0 interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Advantages of supporting DisplayLink chips with kernel framebuffer interface:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) * The actual hardware functionality of DisplayLink chips matches nearly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) one-to-one with the fbdev interface, making the driver quite small and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) tight relative to the functionality it provides.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) * X servers and other applications can use the standard fbdev interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) from user mode to talk to the device, without needing to know anything
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) about USB or DisplayLink's protocol at all. A "displaylink" X driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) and a slightly modified "fbdev" X driver are among those that already do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Disadvantages:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) * Fbdev's mmap interface assumes a real hardware framebuffer is mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) In the case of USB graphics, it is just an allocated (virtual) buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Writes need to be detected and encoded into USB bulk transfers by the CPU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Accurate damage/changed area notifications work around this problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) In the future, hopefully fbdev will be enhanced with an small standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) interface to allow mmap clients to report damage, for the benefit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) of virtual or remote framebuffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) * Fbdev does not arbitrate client ownership of the framebuffer well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) * Fbcon assumes the first framebuffer it finds should be consumed for console.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) * It's not clear what the future of fbdev is, given the rise of KMS/DRM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) How to use it?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Udlfb, when loaded as a module, will match against all USB 2.0 generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) DisplayLink chips (Alex and Ollie family). It will then attempt to read the EDID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) of the monitor, and set the best common mode between the DisplayLink device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) and the monitor's capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) If the DisplayLink device is successful, it will paint a "green screen" which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) means that from a hardware and fbdev software perspective, everything is good.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) At that point, a /dev/fb? interface will be present for user-mode applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) to open and begin writing to the framebuffer of the DisplayLink device using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) standard fbdev calls. Note that if mmap() is used, by default the user mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) application must send down damage notifications to trigger repaints of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) changed regions. Alternatively, udlfb can be recompiled with experimental
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) defio support enabled, to support a page-fault based detection mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) that can work without explicit notification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) The most common client of udlfb is xf86-video-displaylink or a modified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) xf86-video-fbdev X server. These servers have no real DisplayLink specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) code. They write to the standard framebuffer interface and rely on udlfb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) to do its thing. The one extra feature they have is the ability to report
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) rectangles from the X DAMAGE protocol extension down to udlfb via udlfb's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) damage interface (which will hopefully be standardized for all virtual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) framebuffers that need damage info). These damage notifications allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) udlfb to efficiently process the changed pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Module Options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) Special configuration for udlfb is usually unnecessary. There are a few
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) options, however.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) From the command line, pass options to modprobe
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) modprobe udlfb fb_defio=0 console=1 shadow=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) Or modify options on the fly at /sys/module/udlfb/parameters directory via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) sudo nano fb_defio
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) change the parameter in place, and save the file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Unplug/replug USB device to apply with new settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Or for permanent option, create file like /etc/modprobe.d/udlfb.conf with text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) options udlfb fb_defio=0 console=1 shadow=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) Accepted boolean options:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) =============== ================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) module to track changed areas of the framebuffer by page faults.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Standard fbdev applications that use mmap but that do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) report damage, should be able to work with this enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Disable when running with X server that supports reporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) changed regions via ioctl, as this method is simpler,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) more stable, and higher performance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) default: fb_defio=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) console Allow fbcon to attach to udlfb provided framebuffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Can be disabled if fbcon and other clients
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) (e.g. X with --shared-vt) are in conflict.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) default: console=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) shadow Allocate a 2nd framebuffer to shadow what's currently across
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) the USB bus in device memory. If any pixels are unchanged,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) do not transmit. Spends host memory to save USB transfers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Enabled by default. Only disable on very low memory systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) default: shadow=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) =============== ================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Sysfs Attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Udlfb creates several files in /sys/class/graphics/fb?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Where ? is the sequential framebuffer id of the particular DisplayLink device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) ======================== ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) edid If a valid EDID blob is written to this file (typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) by a udev rule), then udlfb will use this EDID as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) backup in case reading the actual EDID of the monitor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) attached to the DisplayLink device fails. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) especially useful for fixed panels, etc. that cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) communicate their capabilities via EDID. Reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) this file returns the current EDID of the attached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) monitor (or last backup value written). This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) useful to get the EDID of the attached monitor,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) which can be passed to utilities like parse-edid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) metrics_bytes_rendered 32-bit count of pixel bytes rendered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) metrics_bytes_identical 32-bit count of how many of those bytes were found to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) unchanged, based on a shadow framebuffer check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) metrics_bytes_sent 32-bit count of how many bytes were transferred over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) USB to communicate the resulting changed pixels to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) hardware. Includes compression and protocol overhead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) above pixels (in thousands of cycles).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) metrics_reset Write-only. Any write to this file resets all metrics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) above to zero. Note that the 32-bit counters above
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) roll over very quickly. To get reliable results, design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) performance tests to start and finish in a very short
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) period of time (one minute or less is safe).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) ======================== ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Bernie Thompson <bernie@plugable.com>
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags