Skip to content

docs: community troubleshooting for hybrid DisplayLink docks #586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0jrm wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: community troubleshooting for hybrid DisplayLink docks #586

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Troubleshooting notes (community)

These notes are for end-users and packagers diagnosing DisplayLink docks that use EVDI. They are not part of the libevdi API.

## Recognizing a DisplayLink dock

```bash
lsusb | grep -iE '17e9|DisplayLink'
```

Example (Dell Universal Dock UD22):

* `413c:f6d0` — Dell Universal Dock UD22
* `17e9:6013` — DisplayLink Dell Universal Hybrid Video Dock

EVDI alone is **not** a complete DisplayLink driver. You also need DisplayLink's userspace driver (`displaylink-driver` / `DisplayLinkManager`).

## Hybrid docks and misleading MST symptoms

Some docks (including Dell UD22) are **hybrid**: USB-C may negotiate DP Alt Mode / MST on the laptop GPU **and** expose DisplayLink over USB.

If DisplayLink userspace / EVDI is missing:

* Monitors may appear as GPU `DP-*` connectors with valid EDIDs
* One panel may be blank; another may flash or only offer 640×480 in the compositor
* Kernel logs may show MST errors (`failed to lookup MSTB`, DPCD read failures)

This is often mistaken for an i915/amdgpu/nvidia bug. Install and start DisplayLink, then look for EVDI connectors (`DVI-I-*` under `/sys/class/drm/`).

## Custom kernels / Pop!_OS

Prebuilt distro packages such as Ubuntu `linux-modules-evdi-*` only match specific kernel ABIs. On custom kernels (for example Pop!_OS / System76 `7.0.x-7607…`), build EVDI via DKMS from the Synaptics package or from this repository.

## Dual monitors, only one EVDI sink

If only one external monitor appears on EVDI:

* Check whether the second panel is still attached to a GPU `DP-*` MST connector
* Try increasing `initial_device_count` (see module parameters)
* Confirm `DisplayLinkManager` is running and both physical dock video ports have signal

## Wayland

Modern DisplayLink + EVDI releases can work on Wayland compositors (verified with Pop!_OS COSMIC). If displays are blank only on Wayland, compare with an X11 session and check compositor multi-GPU / multi-DRM-card support.
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ pages:
- Home: 'index.md'
- Quick Start: 'quickstart.md'
- Detailed description: 'details.md'
- Troubleshooting (community): 'troubleshooting.md'

markdown_extensions:
- toc:
Expand Down