Skip to content
LinuxDeep Dive Published Updated 7 min readViews unavailable

Linux DRM Display Leases: KMS Object Delegation, Revocation, and Recovery

Delegate Linux DRM/KMS objects through a lease FD, track lessees, and plan revocation separately from atomic-commit validation.

Linux DRM display leases let a current display-resource owner grant another DRM master control over a subset of kernel mode-setting objects. The client receives a file descriptor for that lease and can use the leased objects without receiving control of every display resource. This is an ownership boundary for KMS objects, not a new way to submit an atomic commit and not a guarantee that a given compositor or driver supports every leasing workflow.

This guide covers the lease lifecycle and its operational limits. The Linux UAPI header and kernel implementation URLs cited below track master, while the DRM UAPI documentation is the current kernel documentation site. Verify the headers and behavior for the exact kernel and userspace stack you deploy; this article does not certify a release-specific compositor or hardware combination.

Treat a lease as a bounded KMS capability

The DRM documentation distinguishes an owner, a lessor, and a lessee. The original DRM master owns the device’s available display resources. It can create another DRM master and lease selected objects to it. A lessee controls only the objects in its lease; state queries can make resources it does not control appear idle or unusable. For example, an unleased connector is reported as disconnected to that client.

This is useful when separate clients need independent display ownership, such as a compositor delegating one output to another display server or a controlled immersive/display session. The grant should be as small as the client needs. Do not hand a client every connector, CRTC, and plane merely because a broad lease is easier to prototype. Enumerate the available objects on the target device, map the output to its required KMS resources, and keep an owner-side record of the object set and the recipient.

Leases do not form an arbitrary delegation tree. The documented model allows the device owner to issue leases, but lessees cannot create subleases; the lease tree has a maximum depth of one. A resource cannot be leased to multiple lessees at once. Design the owner as the single allocation and revocation authority, and make it responsible for reconciling the resource map when a client exits or a grant is revoked.

Create a lease from a deliberate object set

The UAPI’s drm_mode_create_lease structure takes a pointer to an array of object IDs and a count, accepts lease-file flags, and returns both a lessee ID and a new file descriptor. The kernel implementation permits O_CLOEXEC and O_NONBLOCK flags. Use close-on-exec for a lease FD unless the receiving process is intentionally meant to inherit it; a leaked descriptor can extend the lease beyond the service lifecycle you thought controlled it.

Build the object list from the running device rather than copying numeric IDs from another boot or machine. For a non-empty lease, the current UAPI header requires at least one CRTC and one connector, plus at least one plane when DRM_CLIENT_CAP_UNIVERSAL_PLANES is enabled. The same header documents that an empty lease is also valid. This detail matters when reviewing a “missing object” error: object requirements depend on the client’s universal-plane capability, and the kernel can reject a set that appears plausible from a connector name alone.

Create the lease only after checking that the current process is the intended device owner and that the target driver supports KMS. The Linux implementation returns EOPNOTSUPP when the DRM device lacks DRIVER_MODESET, rejects unsupported flags, and rejects an attempt to create a sublease. Do not interpret access to a render node as proof that a client can lease display objects; render access and KMS resource control are distinct interfaces.

After creation, pass the returned FD to the intended client using a controlled IPC mechanism. Treat the FD itself as the grant: a numeric lessee ID is useful for owner-side management, but it is not a substitute for giving the client the file descriptor that carries the lease. Track both values, the exact object IDs, the target device identity, creation time, and the process or session that owns the recipient FD. Avoid logging a sensitive session token or unrelated process data with that record.

Observe and revoke leases as a lifecycle

The UAPI provides structures to list lessee IDs, retrieve the objects in a lease, and request revocation by lessee ID. Both list-style structures use an input capacity and an output count, so a caller can first query the required size and then fetch the array. Handle a count change between calls by allocating again and retrying within a bound; do not assume the lease roster is static while clients start and exit.

Closing the lessee’s DRM file ends that lease. The owner can also revoke a lease before the recipient closes its descriptor. Make shutdown and recovery explicit: on normal disconnect, close the client-side FD and remove the owner record; on a stuck or unauthorized client, revoke by the tracked lessee ID, then verify the device’s remaining lease roster and object allocation before granting those resources again. The DRM code removes the leased objects as part of revocation; applications should still re-query and reconcile state rather than assume that their own cached connector and plane state is current.

A controlled test should cover both completion paths. First create a lease for one known output and verify that the client can enumerate and use only its leased resources. Then close the lease FD and confirm that the owner can safely allocate the resources again. Repeat with owner-initiated revocation while the client is still running, and require that the client handles the resulting loss of authority instead of continuing with stale KMS assumptions. Finally, attempt an invalid resource set, a duplicate-object grant, and a sublease; confirm that failures are visible and do not leave an unintended lease behind.

Keep atomic state validation separate from lease allocation. The lease answers “which KMS objects may this DRM master control?” An atomic test-only commit answers “can this proposed state transition be applied?” A successful lease does not guarantee that a mode, plane format, routing combination, or atomic commit will work. Use the normal atomic validation and commit path after the recipient receives the lease FD, and diagnose allocation failures separately from state-validation failures.

Set realistic isolation and recovery expectations

A lease narrows DRM master control to a set of display resources. It is not a general sandbox for arbitrary GPU execution, a device-ownership transfer, or a guarantee that the lessor can undo an external application’s side effects instantly. Give the recipient only the descriptor and objects it needs, retain the ability to close or revoke the grant, and do not assume that revocation repairs application state or gracefully stops a client.

Plan for an owner-controller restart without confusing loss of its in-memory inventory with release of the kernel’s real master file. Linux calls drm_lease_revoke() when drm_master_release() releases that real master, removing its outstanding leases. A lessee process may still hold its lease FD, but that descriptor no longer grants control of the leased KMS objects. A restarted controller can inspect the old lease tree only if a broker or another process deliberately keeps the real-master FD open and makes it available to that controller; otherwise it must reacquire ownership, rediscover the device’s objects, and issue new leases under policy. On startup, reconcile the actual kernel state with the session manager, and refuse to reassign resources whose ownership is unknown until policy resolves it. Log creation, FD transfer, close, revoke, and reconciliation outcomes so display failures can be separated from ordinary atomic-commit errors.

DRM leasing is valuable because it turns display delegation into an explicit kernel-managed capability. The operational contract remains narrow: an owner grants an object set through an FD, a lessee cannot re-delegate it, closing the lessee’s DRM file or revoking the lease ends that grant, and releasing the real owner master revokes its outstanding leases. Reliable deployments pair that contract with runtime object discovery, descriptor hygiene, lifecycle tracking, and separate tests for the atomic display state the client intends to program.

Related:

Sources:

Comments