logo

drewdevault.com

[mirror] blog and personal website of Drew DeVault git clone https://hacktivis.me/git/mirror/drewdevault.com.git

DRM-leasing-and-VR-for-Wayland.md (20439B)

    

  1. ---
  2. date: 2019-08-09
  3. title: "DRM leasing: VR for Wayland"
  4. layout: post
  5. tags: [wayland]
  6. ---
  8. As those who read my [status updates](/2019/07/15/Status-update-July-2019.html)
  9. have been aware, recently I've been working on bringing VR to Wayland (and vice
  10. versa). The deepest and most technical part of this work is *DRM leasing*
  11. (Direct Rendering Manager, *not* Digital Restrictions Management), and I think
  12. it'd be good to write in detail about what's involved in this part of the
  13. effort. This work has been sponsored by [Status.im](https://status.im/), as part
  14. of an effort to build a comprehensive Wayland-driven VR workspace. When we got
  15. started, most of the plumbing was missing for VR headsets to be useful on
  16. Wayland, so this has been my focus for a while. The result of this work is
  17. summed up in this crappy handheld video:
  19. <video src="https://yukari.sr.ht/steamvr.webm" controls>
  20.   Your web browser does not support the webm video codec. Please consider using
  21.   web browsers that support free and open standards.
  22. </video>
  24. Keith Packard, a long time Linux graphics developer, [wrote several blog posts
  25. documenting his work implementing this feature for
  26. X11](https://keithp.com/blogs/DRM-lease/). My journey was somewhat similar,
  27. though thanks to his work I was able to save a lot of time. The rub of this idea
  28. is that the Wayland compositor, the DRM (Direct Rendering Manager) master, can
  29. "lease" some of its resources to a client so they can drive your display
  30. directly. DRM is the kernel subsystem we use for enumerating and setting modes,
  31. allocating pixel buffers, and presenting them in sync with the display's refresh
  32. rate. For a number of reasons, minimizing latency being an important one, VR
  33. applications prefer to do these tasks directly rather than be routed through the
  34. display server like most applications are. The main tasks for implementing this
  35. for Wayland were:
  37. 1. Draft a [protocol extension][wl-ext] for issuing DRM leases
  38. 1. Write implementations for [wlroots][wlr-pr] and [sway][sway-pr]
  39. 1. Get a [simple test client][kmscube] working
  40. 1. Draft a Vulkan extension for leasing via Wayland
  41. 1. Write an implementation for [Mesa's Vulkan WSI implementation][wsi]
  42. 1. Get a more complex [Vulkan test client][xrgears] working
  43. 1. Add support to [Xwayland][xwayland]
  45. [wl-ext]: https://lists.freedesktop.org/archives/wayland-devel/2019-July/040768.html
  46. [wlr-pr]: https://github.com/swaywm/wlroots/pull/1730
  47. [sway-pr]: https://github.com/swaywm/sway/pull/4289
  48. [kmscube]: https://git.sr.ht/~sircmpwn/kmscube
  49. [wsi]: https://gitlab.freedesktop.org/mesa/mesa/merge_requests/1509
  50. [xrgears]: https://git.sr.ht/~sircmpwn/xrgears
  51. [xwayland]: https://gitlab.freedesktop.org/xorg/xserver/merge_requests/248
  53. Let's break down exactly what was necessary for each of these steps.
  55. ## Wayland protocol extension
  57. Writing a protocol extension was the first order of business. There was an
  58. [earlier attempt][original proposal] which petered off in January. I started
  59. with this, by cleaning it up based on my prior experience writing protocols,
  60. normalizing much of the terminology and style, and cleaning up the state
  61. management. After some initial rounds of review, there were some questions to
  62. answer. The most important ones were:
  64. - How do we identify the display? Should we send the EDID, which may be
  65.   bigger than the maximum size of a Wayland message?
  66. - Are there security concerns? Could malicious clients read from framebuffers
  67.   they weren't given a lease for?
  69. The EDID I ended up sending in a side channel (file descriptor to shared
  70. memory), and the latter was proven to be a non-issue by writing a malicious
  71. client and demonstrating that the kernel rejects its attempts to do evil.
  73. ```xml
  74. <event name="edid">
  75.   <description summary="edid">
  76.     The compositor may send this event once the connector is created to
  77.     provide a file descriptor which may be memory-mapped to read the
  78.     connector's EDID, to assist in selecting the correct connectors
  79.     for lease. The fd must be mapped with MAP_PRIVATE by the recipient.
  81.     Note that not all displays have an EDID, and this event will not be
  82.     sent in such cases.
  83.   </description>
  84.   <arg name="edid" type="fd" summary="EDID file descriptor" />
  85.   <arg name="size" type="uint" summary="EDID size, in bytes"/>
  86. </event> 
  87. ```
  89. A few more changes would happen to this protocol in the following weeks, but
  90. this was good enough to move on to...
  92. [original proposal]: https://lists.freedesktop.org/archives/wayland-devel/2018-January/036652.html
  94. ## wlroots & sway implementation
  96. After a chat with Scott Anderson (the maintainer of DRM support in wlroots) and
  97. thanks to his timely refactoring efforts, the stage was well set for introducing
  98. this feature to wlroots. I had a good idea of how it would take shape. [Half of
  99. the work][state machine] - the state machine which maintains the server-side
  100. view of the protocol - is well trodden ground and was fairly easy to put
  101. together. Despite being a well-understood problem in the wlroots codebase, these
  102. state machines are always a bit tedious to implement correctly, and I was still
  103. to flushing out bugs well into the remainder of this workstream.
  105. [state machine]: https://github.com/swaywm/wlroots/pull/1730/files#diff-77b17feac8a8af251811a20e5b9bbdd1
  107. The other half of this work was in [the DRM subsystem][drm subsystem]. We
  108. decided that we'd have leased connectors appear "destroyed" to the compositor,
  109. and thus the compositor would have an opportunity to clean it up and stop using
  110. them, similar to the behavior of when an output is hotplugged. Further changes
  111. were necessary to have the DRM internals elegantly carry around some state for
  112. the leased connector and avoid using the connector itself, as well as dealing
  113. with the termination of the lease (either by the client or by the compositor).
  114. With all of this in place, it's a [simple matter][lease issuance] to enumerate
  115. the DRM object IDs for all of the resources we intend to lease and issue the
  116. lease itself.
  118. ```c
  119. int nobjects = 0;
  120. for (int i = 0; i < nconns; ++i) {
  121. 	struct wlr_drm_connector *conn = conns[i];
  122. 	assert(conn->state != WLR_DRM_CONN_LEASED);
  123. 	nobjects += 0
  124. 		+ 1 /* connector */
  125. 		+ 1 /* crtc */
  126. 		+ 1 /* primary plane */
  127. 		+ (conn->crtc->cursor != NULL ? 1 : 0) /* cursor plane */
  128. 		+ conn->crtc->num_overlays; /* overlay planes */
  129. }
  130. if (nobjects <= 0) {
  131. 	wlr_log(WLR_ERROR, "Attempted DRM lease with <= 0 objects");
  132. 	return -1;
  133. }
  134. wlr_log(WLR_DEBUG, "Issuing DRM lease with the %d objects:", nobjects);
  135. uint32_t objects[nobjects + 1];
  136. for (int i = 0, j = 0; i < nconns; ++i) {
  137. 	struct wlr_drm_connector *conn = conns[i];
  138. 	objects[j++] = conn->id;
  139. 	objects[j++] = conn->crtc->id;
  140. 	objects[j++] = conn->crtc->primary->id;
  141. 	wlr_log(WLR_DEBUG, "connector: %d crtc: %d primary plane: %d",
  142. 			conn->id, conn->crtc->id, conn->crtc->primary->id);
  143. 	if (conn->crtc->cursor) {
  144. 		wlr_log(WLR_DEBUG, "cursor plane: %d", conn->crtc->cursor->id);
  145. 		objects[j++] = conn->crtc->cursor->id;
  146. 	}
  147. 	if (conn->crtc->num_overlays > 0) {
  148. 		wlr_log(WLR_DEBUG, "+%zd overlay planes:", conn->crtc->num_overlays);
  149. 	}
  150. 	for (size_t k = 0; k < conn->crtc->num_overlays; ++k) {
  151. 		objects[j++] = conn->crtc->overlays[k];
  152. 		wlr_log(WLR_DEBUG, "\toverlay plane: %d", conn->crtc->overlays[k]);
  153. 	}
  154. }
  155. int lease_fd = drmModeCreateLease(backend->fd,
  156. 		objects, nobjects, 0, lessee_id);
  157. if (lease_fd < 0) {
  158. 	return lease_fd;
  159. }
  160. wlr_log(WLR_DEBUG, "Issued DRM lease %d", *lessee_id);
  161. for (int i = 0; i < nconns; ++i) {
  162. 	struct wlr_drm_connector *conn = conns[i];
  163. 	conn->lessee_id = *lessee_id;
  164. 	conn->crtc->lessee_id = *lessee_id;
  165. 	conn->state = WLR_DRM_CONN_LEASED;
  166. 	conn->lease_terminated_cb = lease_terminated_cb;
  167. 	conn->lease_terminated_data = lease_terminated_data;
  168. 	wlr_output_destroy(&conn->output);
  169. }
  170. return lease_fd;
  171. ```
  173. [drm subsystem]: https://github.com/swaywm/wlroots/pull/1730/files#diff-8b05a774317ee8e87d51422170f82d4b
  174. [lease issuance]: https://github.com/swaywm/wlroots/pull/1730/files#diff-8b05a774317ee8e87d51422170f82d4bR1601
  176. The [sway implementation][sway-pr] is very simple. I added a note in wlroots
  177. which exposes whether or not an output is considered "non-desktop" (a property
  178. which is set for most VR headsets), then sway just rigs up the lease manager and
  179. offers all non-desktop outputs for lease.
  181. ## kmscube
  183. Testing all of this required the use of a simple test client. During his earlier
  184. work, Keith wrote some patches on top of
  185. [kmscube](https://gitlab.freedesktop.org/mesa/kmscube/), a simple Mesa demo
  186. which renders a spinning cube directly via DRM/KMS/GBM. A [few simple
  187. tweaks][kmscube patch] was suitable to get this working through my protocol
  188. extension, and for the first time I saw something rendered on my headset through
  189. sway!
  191. <video src="https://yukari.sr.ht/vr.webm" controls>
  192.   Your web browser does not support the webm video codec. Please consider using
  193.   web browsers that support free and open standards.
  194. </video>
  196. [kmscube patch]: https://git.sr.ht/~sircmpwn/kmscube/commit/60d89ef1d9304427a1289174d9a311ab06e39b44
  198. ## Vulkan
  200. Vulkan has a subsystem called WSI - Window System Integration - which handles
  201. the linkage between Vulkan's rendering process and the underlying window system,
  202. such as Wayland, X11, or win32. Keith added an extension to this system called
  203. [VK_EXT_acquire_xlib_display][VK_EXT_acquire_xlib_display], which lives on top
  204. of [VK_EXT_direct_mode_display][VK_EXT_direct_mode_display], a system for
  205. driving displays directly with Vulkan. As the name implies, this system is
  206. especially X11-specific, so I've drafted my own VK extension for Wayland:
  207. VK_EXT_acquire_wl_display. This is the crux of it:
  209. [VK_EXT_acquire_xlib_display]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_EXT_acquire_xlib_display
  210. [VK_EXT_direct_mode_display]: https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_EXT_direct_mode_display
  212. ```xml
  213. <command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_INITIALIZATION_FAILED">
  214.   <proto><type>VkResult</type> <name>vkAcquireWaylandDisplayEXT</name></proto>
  215.   <param><type>VkPhysicalDevice</type> <name>physicalDevice</name></param>
  216.   <param>struct <type>wl_display</type>* <name>display</name></param>
  217.   <param>struct <type>zwp_drm_lease_manager_v1</type>* <name>manager</name></param>
  218.   <param><type>int</type> <name>nConnectors</name></param>
  219.   <param><type>VkWaylandLeaseConnectorEXT</type>* <name>pConnectors</name></param>
  220. </command>
  221. ```
  223. I chose to leave it up to the user to enumerate the leasable connectors from the
  224. Wayland protocol, then populate these structs with references to the connectors
  225. they want to lease:
  227. ```xml
  228. <type category="struct" name="VkWaylandLeaseConnectorEXT">
  229.   <member>struct <type>zwp_drm_lease_connector_v1</type>* <name>pConnectorIn</name></member>
  230.   <member><type>VkDisplayKHR</type> <name>displayOut</name></member>
  231. </type>
  232. ```
  234. Again, this was the result of some iteration and design discussions with other
  235. folks knowledgable in these topics. I owe special thanks to Daniel Stone for
  236. sitting down with me (figuratively, on IRC) and going over ideas for how to
  237. design the Vulkan API. Armed with this specification, I now needed a Vulkan
  238. driver which supported it.
  240. ## Implementing the VK extension in Mesa
  242. [Mesa](https://www.mesa3d.org/) is the premier free software graphics suite
  243. powering graphics on Linux and other operating systems. It includes an
  244. implementation of OpenGL and Vulkan for several GPU vendors, and is the home of
  245. the userspace end of AMDGPU, Intel, nouveau, and other graphics drivers. A
  246. specification is nothing without its implementation, so I set out to
  247. implementing this extension for Mesa. In the end, it turned out to be much
  248. simpler than the corresponding X version. This is the complete code for the WSI
  249. part of this feature:
  251. ```c
  252. static void drm_lease_handle_lease_fd(
  253.       void *data,
  254.       struct zwp_drm_lease_v1 *zwp_drm_lease_v1,
  255.       int32_t leased_fd)
  256. {
  257.    struct wsi_display *wsi = data;
  258.    wsi->fd = leased_fd;
  259. }
  261. static void drm_lease_handle_finished(
  262.       void *data,
  263.       struct zwp_drm_lease_v1 *zwp_drm_lease_v1)
  264. {
  265.    struct wsi_display *wsi = data;
  266.    if (wsi->fd > 0) {
  267.       close(wsi->fd);
  268.       wsi->fd = -1;
  269.    }
  270. }
  272. static const struct zwp_drm_lease_v1_listener drm_lease_listener = {
  273.    drm_lease_handle_lease_fd,
  274.    drm_lease_handle_finished,
  275. };
  277. /* VK_EXT_acquire_wl_display */
  278. VkResult
  279. wsi_acquire_wl_display(VkPhysicalDevice physical_device,
  280.                        struct wsi_device *wsi_device,
  281.                        struct wl_display *display,
  282.                        struct zwp_drm_lease_manager_v1 *manager,
  283.                        int nConnectors,
  284.                        VkWaylandLeaseConnectorEXT *connectors)
  285. {
  286.    struct wsi_display *wsi =
  287.       (struct wsi_display *) wsi_device->wsi[VK_ICD_WSI_PLATFORM_DISPLAY];
  289.    /* XXX no support for mulitple leases yet */
  290.    if (wsi->fd >= 0)
  291.       return VK_ERROR_INITIALIZATION_FAILED;
  293.    /* XXX no support for mulitple connectors yet */
  294.    /* The solution will eventually involve adding a listener to each
  295.     * connector, round tripping, and matching EDIDs once the lease is
  296.     * granted. */
  297.    if (nConnectors > 1)
  298.       return VK_ERROR_INITIALIZATION_FAILED;
  300.    struct zwp_drm_lease_request_v1 *lease_request =
  301.       zwp_drm_lease_manager_v1_create_lease_request(manager);
  302.    for (int i = 0; i < nConnectors; ++i) {
  303.       zwp_drm_lease_request_v1_request_connector(lease_request,
  304.                                                  connectors[i].pConnectorIn);
  305.    }
  307.    struct zwp_drm_lease_v1 *drm_lease =
  308.       zwp_drm_lease_request_v1_submit(lease_request);
  309.    zwp_drm_lease_request_v1_destroy(lease_request);
  310.    zwp_drm_lease_v1_add_listener(drm_lease, &drm_lease_listener, wsi);
  311.    wl_display_roundtrip(display);
  313.    if (wsi->fd < 0)
  314.       return VK_ERROR_INITIALIZATION_FAILED;
  316.    int nconn = 0;
  317.    drmModeResPtr res = drmModeGetResources(wsi->fd);
  318.    drmModeObjectListPtr lease = drmModeGetLease(wsi->fd);
  319.    for (uint32_t i = 0; i < res->count_connectors; ++i) {
  320.       for (uint32_t j = 0; j < lease->count; ++j) {
  321.          if (res->connectors[i] != lease->objects[j]) {
  322.             continue;
  323.          }
  324.          struct wsi_display_connector *connector =
  325.             wsi_display_get_connector(wsi_device, res->connectors[i]);
  326.          /* TODO: Match EDID with requested connector */
  327.          connectors[nconn].displayOut =
  328.             wsi_display_connector_to_handle(connector);
  329.          ++nconn;
  330.       }
  331.    }
  332.    drmModeFreeResources(res);
  334.    return VK_SUCCESS;
  335. }
  336. ```
  338. Rigging it up to each driver's WSI shim is pretty straightforward from this
  339. point. I only did it for radv - AMD's Vulkan driver (cause that's the hardware I
  340. was using at the time) - but the rest should be trivial to add. Equipped with a
  341. driver in hand, it's time to make a Real VR Application work on Wayland.
  343. ## xrgears
  345. [xrgears](https://gitlab.com/lubosz/xrgears) is another simple demo application
  346. like kmscube - but designed to render a VR scene. It leverages Vulkan and
  347. [OpenHMD](http://www.openhmd.net/) (Open Head Mounted Display) to display this
  348. scene and stick the camera to your head. With the Vulkan extension implemented,
  349. it was a fairly simple matter to [rig up a Wayland backend][xrgears-patch]. The
  350. result:
  352. [xrgears-patch]: https://git.sr.ht/~sircmpwn/xrgears/commit/41ef1d1dfe3e56766d1f8b72b335567eb7842d04
  354. <video src="https://yukari.sr.ht/xrgears.webm" controls>
  355.   Your web browser does not support the webm video codec. Please consider using
  356.   web browsers that support free and open standards.
  357. </video>
  359. ## Xwayland
  361. The final step was to integrate this extension with Xwayland, so that X
  362. applications which took advantage of Keith's work would work via Xwayland. This
  363. ended up being more difficult than I expected for one reason in particular:
  364. modes. Keith's Vulkan extension is designed in two steps:
  366. 1. Convert an RandR output into a VkDisplayKHR
  367. 2. Acquire a lease for a set of VkDisplayKHRs
  369. Between these steps, you can query the modes (available resolutions and refresh
  370. rates) of the display. However, the Wayland protocol I designed does not let you
  371. query modes until *after* you get the DRM handle, at which point you should
  372. query them through DRM, thus reducing the number of sources of truth and
  373. simplifying things considerably. This is arguably a design misstep in the
  374. original Vulkan extension, but it's shipped in a lot of software and is beyond
  375. fixing. So how do we deal with it?
  377. One way (which was suggested at one point) would be to change the protocol to
  378. include the relevant mode information, so that Xwayland could populate the RandR
  379. modes from it. I found this distasteful, because it was making the protocol more
  380. complex for the sake of a legacy system. Another option would be to make a
  381. second protocol which includes this extra information especially for Xwayland,
  382. but this also seemed like a compromise that compositors would rather not make.
  383. Yet another option would be to have Xwayland request a lease with zero objects
  384. and scan connectors itself, but zero-object leases are not possible.
  386. The option I ended up going with is to have Xwayland open the DRM device itself
  387. and scan connectors there. This is less palatable because (1) we can't be sure
  388. which DRM device is correct, and (2) we can't be sure Xwayland will have
  389. permission to read it. We're still not sure how best to solve this in the long
  390. term. As it stands, this approach is sufficient to get it working in the common
  391. case. The code looks something like this:
  393. ```c
  394. static RRModePtr *
  395. xwl_get_rrmodes_from_connector_id(int32_t connector_id, int *nmode, int *npref)
  396. {
  397.     drmDevicePtr devices[1];
  398.     drmModeConnectorPtr conn;
  399.     drmModeModeInfoPtr kmode;
  400.     RRModePtr *rrmodes;
  401.     int drm;
  402.     int pref, i;
  404.     *nmode = *npref = 0;
  406.     /* TODO: replace with zero-object lease once kernel supports them */
  407.     if (drmGetDevices2(DRM_NODE_PRIMARY, devices, 1) < 1
  408.             || !*devices[0]->nodes[0]) {
  409.         ErrorF("Failed to enumerate DRM devices");
  410.         return NULL;
  411.     }
  412.     drm = open(devices[0]->nodes[0], O_RDONLY);
  413.     drmFreeDevices(devices, 1);
  415.     conn = drmModeGetConnector(drm, connector_id);
  416.     if (!conn) {
  417.         close(drm);
  418.         ErrorF("drmModeGetConnector failed");
  419.         return NULL;
  420.     }
  421.     rrmodes = xallocarray(conn->count_modes, sizeof(RRModePtr));
  422.     if (!rrmodes) {
  423.         close(drm);
  424.         ErrorF("Failed to allocate connector modes");
  425.         return NULL;
  426.     }
  428.     /* This spaghetti brought to you courtesey of xf86RandrR12.c
  429.      * It adds preferred modes first, then non-preferred modes */
  430.     for (pref = 1; pref >= 0; pref--) {
  431.         for (i = 0; i < conn->count_modes; ++i) {
  432.             kmode = &conn->modes[i];
  433.             if ((pref != 0) == ((kmode->type & DRM_MODE_TYPE_PREFERRED) != 0)) {
  434.                 xRRModeInfo modeInfo;
  435.                 RRModePtr rrmode;
  437.                 modeInfo.nameLength = strlen(kmode->name);
  439.                 modeInfo.width = kmode->hdisplay;
  440.                 modeInfo.dotClock = kmode->clock * 1000;
  441.                 modeInfo.hSyncStart = kmode->hsync_start;
  442.                 modeInfo.hSyncEnd = kmode->hsync_end;
  443.                 modeInfo.hTotal = kmode->htotal;
  444.                 modeInfo.hSkew = kmode->hskew;
  446.                 modeInfo.height = kmode->vdisplay;
  447.                 modeInfo.vSyncStart = kmode->vsync_start;
  448.                 modeInfo.vSyncEnd = kmode->vsync_end;
  449.                 modeInfo.vTotal = kmode->vtotal;
  450.                 modeInfo.modeFlags = kmode->flags;
  452.                 rrmode = RRModeGet(&modeInfo, kmode->name);
  453.                 if (rrmode) {
  454.                     rrmodes[*nmode] = rrmode;
  455.                     *nmode = *nmode + 1;
  456.                     *npref = *npref + pref;
  457.                 }
  458.             }
  459.         }
  460.     }
  462.     close(drm);
  463.     return rrmodes;
  464. }
  466. ```
  468. A simple update to the Wayland protocol was necessary to add the `CONNECTOR_ID`
  469. atom to the RandR output, which is used by Mesa's Xlib WSI code for acquiring
  470. the display, and was reused here to line up a connector offered by the Wayland
  471. compositor with a connector found in the kernel. The [rest of the
  472. changes][xwayland] were pretty simple, and the result is that SteamVR works,
  473. capping everything off nicely:
  475. <video src="https://yukari.sr.ht/steamvr.webm" controls>
  476.   Your web browser does not support the webm video codec. Please consider using
  477.   web browsers that support free and open standards.
  478. </video>