README.md

   1 # DRM Lease Manager
   2
   3 The DRM Lease Manager uses the DRM Lease feature, introduced in the Linux kernel version 4.15,
   4 to partition display controller output resources between multiple processes.
   5
   6 For more information on the DRM lease functionality, please see the blog posts published by Keith
   7 Packard, who developed the feature, at https://keithp.com/blogs/DRM-lease/
   8
   9 This repository contains a user space daemon to create and manage DRM leases, and distribute them
  10 to client applications.  This implementation is independent of any window system / compositor,
  11 such as X11 or wayland, so can be used with clients that directly access a DRM device.
  12
  13 This repository also provides a library that clients can use to communicate with the DRM Lease Manager.
  14
  15 ## Building
  16
  17 Build this repository requires a recent version of the [meson](https://mesonbuild.com/Getting-meson.html) build system.
  18
  19 The basic build procedure is as follows:
  20
  21     meson <build_dir>
  22     ninja -C <build_dir>
  23     sudo ninja -C <build_dir> install
  24
  25 `<build_dir>` can be any directory name, but `build` is commonly used.
  26
  27 ## Configuration
  28
  29 The drm-lease-manager configuration file allows the user to specify the mapping
  30 of DRM connectors to DRM leases. The location of the configuration file can
  31 be specified with the `--config` command line option.
  32
  33 The configuration file consists of a list of lease definitions, containing a name
  34 of the lease and a list of the included connector names.
  35
  36 Each list entry is of the following form:
  37
  38 ```toml
  39 [[lease]]
  40 name="My lease"
  41 connectors=["connector 1", "connector 2"]
  42 ```
  43 * Note: quotes around all string values are mandatory.
  44
  45 This will create a lease named `My lease` and add the two connectors `connector 1` and
  46 `connector 2` to the lease.
  47 If there is no connector with either of the names exists on the system, that name
  48 will be omitted from the lease.
  49
  50 ### Default configuration
  51
  52 If no configuration file is specified one DRM lease will be created for each connector
  53 on the DRM device (up to the number of available CRTCs).
  54
  55 The names of the DRM leases will have the following pattern:
  56
  57     <device>-<connector name>
  58
  59 So, for example, a DRM lease for the first LVDS device on the device `/dev/dri/card0` would be named
  60 `card0-LVDS-1`.
  61
  62 ## Running
  63
  64 Once installed, running the following command will start the DRM Lease Manager daemon
  65
  66     drm-lease-manager [<path DRM device>]
  67
  68 If no DRM device is specified, the first available device capabale of modesetting will
  69 be used.  More detailed options can be displayed by specifying the `-h` flag.
  70
  71 ### Dynamic lease transfer
  72
  73 When `drm-lease-manager` is started with the `-t` option, the
  74 ownership of a leases resources can be transferred from
  75 one client to another.
  76
  77 This allows the ownership of the leased resources to be transferred
  78 without the display being closed and the screen blanking.
  79 `drm-lease-manager` handles the timing of the transfer and manages the
  80 references to the DRM device, so that the last framebuffer of
  81 the old client stays on screen until the new client presents its first frame.
  82
  83 The transition can be completed without direct communication between the old
  84 and new client applications, however, the client that the lease will be
  85 transitioned *from* must be able to handle unexpected lease revocation.
  86 Once the lease is revoked, all DRM API calls referring to the DRM
  87 resources managed by the lease will fail with -ENOENT.  The client
  88 should be able to gracefully handle this condition by, for example,
  89 pausing or shutting down its rendering operations.
  90
  91 ## Client API usage
  92
  93 The libdmclient handles all communication with the DRM Lease Manager and provides file descriptors that
  94 can be used as if the DRM device was opened directly. Clients only need to replace their calls to
  95 `drmOpen()` and `drmClose()` with the appropriate libdlmclient API calls.
  96
  97 The client library API is described in `dlmclient.h` in the `libdlmclient` directory.
  98
  99 If doxygen is available, building the repository will generate doxygen documentation in the
 100 `<build_dir>/libdlmclient/docs/html` directory.
 101
 102 ### Examples
 103
 104 _Error handling has been omitted for brevity and clarity of examples._
 105
 106 #### Requesting a lease from the DRM Lease Manager
 107
 108 ```c
 109   struct dlm_lease *lease = dlm_get_lease("card0-HDMI-A-1");
 110   int drm_device_fd = dlm_lease_fd(lease);
 111 ```
 112
 113 `drm_device_fd` can now be used to access the DRM device
 114
 115 #### Releasing a lease
 116
 117 ```c
 118   dlm_release_lease(lease);
 119 ```
 120
 121 **Note: `drm_device_fd` is not usable after calling `dlm_release_lease()`**
 122
 123 ## Runtime directory
 124 A runtime directory under the `/var` system directory is used by the drm-lease-manager and clients to
 125 communicate with each other.
 126 The default path is `/var/run/drm-lease-manager`, but can be changed by setting the `-Druntime_subdir`
 127 option during configuration with `meson`.
 128
 129 The runtime directory can also be specified at runtime by setting the `DLM_RUNTIME_PATH` environment variable.