Add support for lease transition

When enabled allow the ownership of a lease to transition from
one client to another.

If a request is made for a lease that is already allocated to
a client, revoke the lease from the old client and issue a new
lease for the same resources to the new client.

This allows the ownership of the leased resources to be transferred
without the display being closed and the screen blanking.

During the tranistion, hold a reference to the old clients lease fd so
that the last frame presented by the old client will remain on screen until
the new client presents its first frame.

Currenly there is no notification or authentication mechanism
implemeted for the transition.  Any client can request a transition
from any other. The only notification that a transfer has happened
is that the previous client's DRM API calls will suddenly fail with
-ENOENT, since all resources will have been removed.
It is up to the client to sensibly handle this condition.

Bug-AGL: SPEC-3816

Change-Id: Iaff87e275f909f3b6ef448df39364d6fe62007b1
Signed-off-by: Damian Hobson-Garcia <dhobsong@igel.co.jp>

1 files changed, 20 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5368f6b..84af0a7 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,26 @@ The names of the DRM leases will have the following pattern:
 So, for example, a DRM lease for the first LVDS device on the device `/dev/dri/card0` would be named
 `card0-LVDS-1`.
 
+### Dynamic lease transfer
+
+When `drm-lease-manager` is started with the `-t` option, the
+ownership of a leases resourses can be transfered from
+one client to another.
+
+This allows the ownership of the leased resources to be transferred
+without the display being closed and the screen blanking.
+`drm-lease-manager` handles the timing of the tranfser and manages the
+references to the DRM device, so that the last framebuffer of
+the old client stays on screen until the new client presents its first frame.
+
+The transition can be completed without direct communication between the old
+and new client applications, however, the client that the lease will be
+transitioned *from* must be able to handle unexpected lease revokation.
+Once the lease is revoked, all DRM API calls referring to the DRM
+resources managed by the lease will fail with -ENOENT.  The client
+should be able to gracefully handle this condition by, for example,
+pausing or shutting down its rendering operations.
+
 ## Client API usage
 
 The libdmclient handles all communication with the DRM Lease Manager and provides file descriptors that