docs/06_Component_Documentation/05_drm_lease_manager.md

   1 ---
   2 title: DRM lease manager
   3 ---
   4
   5 # DRM Lease Manager
   6
   7 ## Overview
   8
   9 The DRM Lease Manager is used in AGL to allocate display controller outputs to different processes. Each process has direct access to its allocated output via the kernel DRM interface, and is prevented from accessing any other outputs managed by the display controller.
  10
  11 The display controller partitioning is made possible by using the kernel DRM Lease feature.  For more information on the DRM lease functionality, please see the Linux kernel [DRM userspace API documentation](https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html).
  12
  13
  14 ## Usage
  15
  16 ### Building DRM Lease manager and sample clients
  17
  18 Enable the  `agl-drm-lease` AGL feature when setting up your build environment
  19 with aglsetup.sh.
  20
  21 This will add the drm-lease-manager package to the image, and will add DRM
  22 lease support to the following packages:
  23
  24 * weston
  25 * kmscube
  26
  27 kmscube is not included in the image by default. To add the package to the
  28 image, add the following to your local.conf
  29
  30 ```
  31 IMAGE_INSTALL_append = " kmscube"
  32 ```
  33
  34 ### Starting the DRM lease manager
  35
  36 The drm-lease-manager must be the only process to directly open the DRM device.
  37 Shut down any running window systems (eg. weston or agl-compositor) and run:
  38
  39 ```shell
  40   systemctl start drm-lease-manager
  41 ```
  42
  43 This will create a lease for each output connection on the platform.
  44 The name of each lease will be in the form of `card0-<output name>`
  45  (eg. `card0-LVDS-1` or `card0-HDMI-A-1`)
  46
  47 **Note**: `drm-lease-manager` can be started on a different display controller (i.e. not `card0`) by modifying the command line in the systemd unit file.
  48
  49 Run the help command for details.
  50
  51 ```shell
  52   drm-lease-manager --help
  53 ```
  54
  55 ### Running weston
  56
  57 weston can be started on any available DRM lease by running with the
  58 `--drm-lease=<lease name>` option.
  59
  60 ```shell
  61   weston --drm-lease=card0-HDMI-A-1
  62 ```
  63
  64 ### Running kmscube sample
  65 With the `drm-lease-manager` running, `kmscube` can display on any available
  66 lease by launching it with the `-L -D<lease name>` options.
  67
  68 ```shell
  69   kmscube -L -Dcard0-HDMI-A-1
  70 ```
  71
  72 Multiple weston or kmscube instances (one per DRM lease) can be started at the same time.
  73
  74 ## Adding support to your application
  75
  76 The DRM Lease Manager packages includes a client library (libdlmclient) to request access to the DRM leases it creates.  The client library provides file descriptors that can be used as if they were created by directly opening the underlying DRM device.
  77
  78 Clients that want _direct access_ to the DRM device can use this library to do so.  Compositor (agl-compositor or weston) client applications do not need to use this interface.
  79
  80
  81 To use the DRM leases, clients only need to replace their calls to
  82 `drmOpen()` and `drmClose()` with the appropriate libdlmclient API calls.
  83
  84 ### libdlmclient API usage
  85
  86 _Error handling has been omitted for brevity and clarity of examples._
  87
  88 #### Requesting a lease from the DRM Lease Manager
  89
  90 ```c
  91   struct dlm_lease *lease = dlm_get_lease("card0-HDMI-A-1");
  92   int drm_device_fd = dlm_lease_fd(lease);
  93 ```
  94
  95 `drm_device_fd` can now be used to access the DRM device
  96
  97 #### Releasing a lease
  98
  99 ```c
 100   dlm_release_lease(lease);
 101 ```
 102
 103 **Note: `drm_device_fd` is not usable after calling `dlm_release_lease()`**
 104
 105 ## Runtime directory
 106 A runtime directory under `/var` is used to keep the Unix Domain sockets that the drm-lease-manager and clients to communicate with each other.
 107
 108 The default path is `/var/run/drm-lease-manager`, but can be changed by setting the `DLM_RUNTIME_PATH` environment variable.