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 ## Running
  28
  29 Once installed, running the following command will start the DRM Lease Manager daemon
  30
  31     drm-lease-manager [<path DRM device>]
  32
  33 If no DRM device is specified, `/dev/dri/card0` will be used.
  34 More detailed options can be displayed by specifying the `-h` flag.
  35
  36 ### Lease naming
  37
  38 One DRM lease will be created for each connector on the DRM device (up to the number of available CRTCs).
  39
  40 The names of the DRM leases will have the following pattern:
  41
  42     <device>-<connector name>
  43
  44 So, for example, a DRM lease for the first LVDS device on the device `/dev/dri/card0` would be named
  45 `card0-LVDS-1`.
  46
  47 ## Client API usage
  48
  49 The libdmclient handles all communication with the DRM Lease Manager and provides file descriptors that
  50 can be used as if the DRM device was opened directly. Clients only need to replace their calls to
  51 `drmOpen()` and `drmClose()` with the appropriate libdlmclient API calls.
  52
  53 The client library API is described in `dlmclient.h` in the `libdlmclient` directory.
  54
  55 If doxygen is available, building the repository will generate doxygen documentation in the
  56 `<build_dir>/libdlmclient/docs/html` directory.
  57
  58 ### Examples
  59
  60 _Error handling has been omitted for brevity and clarity of examples._
  61
  62 #### Requesting a lease from the DRM Lease Manager
  63
  64 ```c
  65   struct dlm_lease *lease = dlm_get_lease("card0-HDMI-A-1");
  66   int drm_device_fd = dlm_lease_fd(lease);
  67 ```
  68
  69 `drm_device_fd` can now be used to access the DRM device
  70
  71 #### Releasing a lease
  72
  73 ```c
  74   dlm_release_lease(lease);
  75 ```
  76
  77 **Note: `drm_device_fd` is not usable after calling `dlm_release_lease()`**
  78
  79 ## Runtime directory
  80 A runtime directory under the `/var` system directory is used by the drm-lease-manager and clients to
  81 communicate with each other.
  82 The default path is `/var/run/drm-lease-manager`, but can be changed by setting the `-Druntime_subdir`
  83 option during configuration with `meson`.
  84
  85 The runtime directory can also be specified at runtime by setting the `DLM_RUNTIME_PATH` environment variable.