libdrm Device Lookup¶

BEWARE THE DRAGONS! MIND THE TRAPDOORS!

In an attempt to warn anyone else who’s trying to figure out what’s goingon here, I’ll try to summarize the story. First things first, let’s clear upthe names, because the kernel internals, libdrm and the ioctls are all nameddifferently:

• GET_UNIQUE ioctl, implemented by drm_getunique is wrapped up in libdrmthrough the drmGetBusid function.
• The libdrm drmSetBusid function is backed by the SET_UNIQUE ioctl. Allthat code is nerved in the kernel withdrm_invalid_op().
• The internal set_busid kernel functions and driver callbacks areexclusively use by the SET_VERSION ioctl, because only drm 1.0 (which isnerved) allowed userspace to set the busid through the above ioctl.
• Other ioctls and functions involved are named consistently.

For anyone wondering what’s the difference between drm 1.1 and 1.4: Correctlyhandling pci domains in the busid on ppc. Doing this correctly was onlyimplemented in libdrm in 2010, hence can’t be nerved yet. No one knows what’sspecial with drm 1.2 and 1.3.

Now the actual horror story of how device lookup in drm works. At large,there’s 2 different ways, either by busid, or by device driver name.

Opening by busid is fairly simple:

1. First call SET_VERSION to make sure pci domains are handled properly. As aside-effect this fills out the unique name in the master structure.
2. Call GET_UNIQUE to read out the unique name from the master structure,which matches the busid thanks to step 1. If it doesn’t, proceed to trythe next device node.

Opening by name is slightly different:

1. Directly call VERSION to get the version and to match against the drivername returned by that ioctl. Note that SET_VERSION is not called, whichmeans the the unique name for the master node just opening is _not_ filledout. This despite that with current drm device nodes are always bound toone device, and can’t be runtime assigned like with drm 1.0.
2. Match driver name. If it mismatches, proceed to the next device node.
3. Call GET_UNIQUE, and check whether the unique name has length zero (bychecking that the first byte in the string is 0). If that’s not the caselibdrm skips and proceeds to the next device node. Probably this is justcopypasta from drm 1.0 times where a set unique name meant that the driverwas in use already, but that’s just conjecture.

Long story short: To keep the open by name logic working, GET_UNIQUE must_not_ return a unique string when SET_VERSION hasn’t been called yet,otherwise libdrm breaks. Even when that unique string can’t ever change, andis totally irrelevant for actually opening the device because runtimeassignable device instances were only support in drm 1.0, which is long dead.But the libdrm code in drmOpenByName somehow survived, hence this can’t bebroken.

Primary Nodes, DRM Master and Authentication¶

structdrm_master is used to track groups of clients with openprimary/legacy device nodes. For everystructdrm_file which has had atleast once successfully became the device master (either through theSET_MASTER IOCTL, or implicitly through opening the primary device node whenno one else is the current master that time) there exists onedrm_master.This is noted indrm_file.is_master. All other clients have just a pointerto thedrm_master they are associated with.

In addition only onedrm_master can be the current master for adrm_device.It can be switched through the DROP_MASTER and SET_MASTER IOCTL, orimplicitly through closing/openeing the primary device node. See alsodrm_is_current_master().

Clients can authenticate against the current master (if it matches their own)using the GETMAGIC and AUTHMAGIC IOCTLs. Together with exchanging masters,this allows controlled access to the device for an entire group of mutuallytrusted clients.

booldrm_is_current_master(structdrm_file * fpriv)¶

checks whetherpriv is the current master

Parameters

structdrm_file*fpriv

DRM file private

Description

Checks whetherfpriv is current master on its device. This decides whether aclient is allowed to run DRM_MASTER IOCTLs.

Most of the modern IOCTL which require DRM_MASTER are for kernel modesetting- the current master is assumed to own the non-shareable display hardware.

structdrm_master *drm_master_get(structdrm_master * master)¶

reference a master pointer

Parameters

structdrm_master*master

structdrm_master

Description

Increments the reference count ofmaster and returns a pointer tomaster.

voiddrm_master_put(structdrm_master ** master)¶

unreference and clear a master pointer

Parameters

structdrm_master**master

pointer to a pointer ofstructdrm_master

Description

This decrements thedrm_master behindmaster and sets it to NULL.

structdrm_master¶

drm master structure

Definition

struct drm_master {  struct kref refcount;  struct drm_device *dev;  char *unique;  int unique_len;  struct idr magic_map;  void *driver_priv;  struct drm_master *lessor;  int lessee_id;  struct list_head lessee_list;  struct list_head lessees;  struct idr leases;  struct idr lessee_idr;};

Members

refcount

Refcount for this master object.

dev

Link back to the DRM device

unique

Unique identifier: e.g. busid. Protected bydrm_device.master_mutex.

unique_len

Length of unique field. Protected bydrm_device.master_mutex.

magic_map

Map of used authentication tokens. Protected bydrm_device.master_mutex.

driver_priv

Pointer to driver-private information.

lessor

Lease holder

lessee_id

id for lessees. Owners always have id 0

lessee_list

other lessees of the same master

lessees

drm_masters leasing from this one

leases

Objects leased to this drm_master.

lessee_idr

All lessees under this owner (only used where lessor == NULL)

Description

Note that master structures are only relevant for the legacy/primary devicenodes, hence there can only be one per device, not one per drm_minor.

Open-Source Userspace Requirements¶

The DRM subsystem has stricter requirements than most other kernel subsystems onwhat the userspace side for new uAPI needs to look like. This section hereexplains what exactly those requirements are, and why they exist.

The short summary is that any addition of DRM uAPI requires correspondingopen-sourced userspace patches, and those patches must be reviewed and ready formerging into a suitable and canonical upstream project.

GFX devices (both display and render/GPU side) are really complex bits ofhardware, with userspace and kernel by necessity having to work together reallyclosely. The interfaces, for rendering and modesetting, must be extremely wideand flexible, and therefore it is almost always impossible to precisely definethem for every possible corner case. This in turn makes it really practicallyinfeasible to differentiate between behaviour that’s required by userspace, andwhich must not be changed to avoid regressions, and behaviour which is only anaccidental artifact of the current implementation.

Without access to the full source code of all userspace users that means itbecomes impossible to change the implementation details, since userspace coulddepend upon the accidental behaviour of the current implementation in minutedetails. And debugging such regressions without access to source code is prettymuch impossible. As a consequence this means:

• The Linux kernel’s “no regression” policy holds in practice only foropen-source userspace of the DRM subsystem. DRM developers are perfectly fineif closed-source blob drivers in userspace use the same uAPI as the opendrivers, but they must do so in the exact same way as the open drivers.Creative (ab)use of the interfaces will, and in the past routinely has, leadto breakage.
• Any new userspace interface must have an open-source implementation asdemonstration vehicle.

The other reason for requiring open-source userspace is uAPI review. Since thekernel and userspace parts of a GFX stack must work together so closely, codereview can only assess whether a new interface achieves its goals by looking atboth sides. Making sure that the interface indeed covers the use-case fullyleads to a few additional requirements:

• The open-source userspace must not be a toy/test application, but the realthing. Specifically it needs to handle all the usual error and corner cases.These are often the places where new uAPI falls apart and hence essential toassess the fitness of a proposed interface.
• The userspace side must be fully reviewed and tested to the standards of thatuserspace project. For e.g. mesa this means piglit testcases and review on themailing list. This is again to ensure that the new interface actually gets thejob done. The userspace-side reviewer should also provide an Acked-by on thekernel uAPI patch indicating that they believe the proposed uAPI is sound andsufficiently documented and validated for userspace’s consumption.
• The userspace patches must be against the canonical upstream, not some vendorfork. This is to make sure that no one cheats on the review and testingrequirements by doing a quick fork.
• The kernel patch can only be merged after all the above requirements are met,but itmust be merged to either drm-next or drm-misc-nextbefore theuserspace patches land. uAPI always flows from the kernel, doing things theother way round risks divergence of the uAPI definitions and header files.

These are fairly steep requirements, but have grown out from years of sharedpain and experience with uAPI added hastily, and almost always regretted aboutjust as fast. GFX devices change really fast, requiring a paradigm shift andentire new set of uAPI interfaces every few years at least. Together with theLinux kernel’s guarantee to keep existing userspace running for 10+ years thisis already rather painful for the DRM subsystem, with multiple different uAPIsfor the same thing co-existing. If we add a few more complete mistakes into themix every year it would be entirely unmanageable.

Render nodes¶

DRM core provides multiple character-devices for user-space to use.Depending on which device is opened, user-space can perform a differentset of operations (mainly ioctls). The primary node is always createdand called card<num>. Additionally, a currently unused control node,called controlD<num> is also created. The primary node provides alllegacy operations and historically was the only interface used byuserspace. With KMS, the control node was introduced. However, theplanned KMS control interface has never been written and so the controlnode stays unused to date.

With the increased use of offscreen renderers and GPGPU applications,clients no longer require running compositors or graphics servers tomake use of a GPU. But the DRM API required unprivileged clients toauthenticate to a DRM-Master prior to getting GPU access. To avoid thisstep and to grant clients GPU access without authenticating, rendernodes were introduced. Render nodes solely serve render clients, thatis, no modesetting or privileged ioctls can be issued on render nodes.Only non-global rendering commands are allowed. If a driver supportsrender nodes, it must advertise it via the DRIVER_RENDER DRM drivercapability. If not supported, the primary node must be used for renderclients together with the legacy drmAuth authentication procedure.

If a driver advertises render node support, DRM core will create aseparate render node called renderD<num>. There will be one render nodeper device. No ioctls except PRIME-related ioctls will be allowed onthis node. Especially GEM_OPEN will be explicitly prohibited. Rendernodes are designed to avoid the buffer-leaks, which occur if clientsguess the flink names or mmap offsets on the legacy interface.Additionally to this basic interface, drivers must mark theirdriver-dependent render-only ioctls as DRM_RENDER_ALLOW so renderclients can use them. Driver authors must be careful not to allow anyprivileged ioctls on render nodes.

With render nodes, user-space can now control access to the render nodevia basic file-system access-modes. A running graphics server whichauthenticates clients on the privileged primary/legacy node is no longerrequired. Instead, a client can open the render node and is immediatelygranted GPU access. Communication between clients (or servers) is donevia PRIME. FLINK from render node to legacy node is not supported. Newclients must not use the insecure FLINK interface.

Besides dropping all modeset/global ioctls, render nodes also drop theDRM-Master concept. There is no reason to associate render clients witha DRM-Master as they are independent of any graphics server. Besides,they must work without any running master, anyway. Drivers must be ableto run without a master object if they support render nodes. If, on theother hand, a driver requires shared state between clients which isvisible to user-space and accessible beyond open-file boundaries, theycannot support render nodes.

IOCTL Support on Device Nodes¶

First things first, driver private IOCTLs should only be needed for driverssupporting rendering. Kernel modesetting is all standardized, and extendedthrough properties. There are a few exceptions in some existing drivers,which define IOCTL for use by the display DRM master, but they all predateproperties.

Now if you do have a render driver you always have to support it throughdriver private properties. There’s a few steps needed to wire all the thingsup.

First you need to define the structure for your IOCTL in your driver privateUAPI header ininclude/uapi/drm/my_driver_drm.h:

struct my_driver_operation {        u32 some_thing;        u32 another_thing;};

Please make sure that you follow all the best practices fromDocumentation/process/botching-up-ioctls.rst. Note thatdrm_ioctl()automatically zero-extends structures, hence make sure you can add more stuffat the end, i.e. don’t put a variable sized array there.

Then you need to define your IOCTL number, using one of DRM_IO(), DRM_IOR(),DRM_IOW() or DRM_IOWR(). It must start with the DRM_IOCTL_ prefix:

##define DRM_IOCTL_MY_DRIVER_OPERATION  *         DRM_IOW(DRM_COMMAND_BASE, struct my_driver_operation)

DRM driver private IOCTL must be in the range from DRM_COMMAND_BASE toDRM_COMMAND_END. Finally you need an array ofstructdrm_ioctl_desc to wireup the handlers and set the access rights:

static const struct drm_ioctl_desc my_driver_ioctls[] = {    DRM_IOCTL_DEF_DRV(MY_DRIVER_OPERATION, my_driver_operation,            DRM_AUTH|DRM_RENDER_ALLOW),};

And then assign this to thedrm_driver.ioctls field in your driverstructure.

See the separate chapter onfile operations for howthe driver-specific IOCTLs are wired up.

struct drm_ioctl_desc {  unsigned int cmd;  enum drm_ioctl_flags flags;  drm_ioctl_t *func;  const char *name;};

Testing and validation¶

$ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto

$ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v

struct drm_info_list {  const char *name;  int (*show)(struct seq_file*, void*);  u32 driver_features;  void *data;};

struct drm_info_node {  struct drm_minor *minor;  const struct drm_info_list *info_ent;};

Sysfs Support¶

DRM provides very little additional support to drivers for sysfsinteractions, beyond just all the standard stuff. Drivers who want to exposeadditional sysfs properties and property groups can attach them at eitherdrm_device.dev ordrm_connector.kdev.

Registration is automatically handled when callingdrm_dev_register(), ordrm_connector_register() in case of hot-plugged connectors. Unregistration isalso automatically handled bydrm_dev_unregister() anddrm_connector_unregister().

voiddrm_sysfs_hotplug_event(structdrm_device * dev)¶

generate a DRM uevent

Parameters

structdrm_device*dev

DRM device

Description

Send a uevent for the DRM device specified bydev. Currently we onlyset HOTPLUG=1 in the uevent environment, but this could be expanded todeal with other types of events.

Any new uapi should be using thedrm_sysfs_connector_status_event()for uevents on connector status change.

voiddrm_sysfs_connector_status_event(structdrm_connector * connector, structdrm_property * property)¶

generate a DRM uevent for connector property status change

Parameters

structdrm_connector*connector

connector on which property status changed

structdrm_property*property

connector property whose status changed.

Description

Send a uevent for the DRM device specified bydev. Currently weset HOTPLUG=1 and connector id along with the attached property idrelated to the status change.

intdrm_class_device_register(structdevice * dev)¶

register new device with the DRM sysfs class

Parameters

structdevice*dev

device to register

Description

Registers a newstructdevice within the DRM sysfs class. Essentially onlyused by ttm to have a place for its global settings. Drivers should never usethis.

voiddrm_class_device_unregister(structdevice * dev)¶

unregister device with the DRM sysfs class

Parameters

structdevice*dev

device to unregister

Description

Unregisters astructdevice from the DRM sysfs class. Essentially only usedby ttm to have a place for its global settings. Drivers should never usethis.

VBlank event handling¶

The DRM core exposes two vertical blank related ioctls:

DRM_IOCTL_WAIT_VBLANK

This takes a struct drm_wait_vblank structure as its argument, andit is used to block or request a signal when a specified vblankevent occurs.

DRM_IOCTL_MODESET_CTL

This was only used for user-mode-settind drivers around modesettingchanges to allow the kernel to update the vblank interrupt aftermode setting, since on many devices the vertical blank counter isreset to 0 at some point during modeset. Modern drivers should notcall this any more since with kernel mode setting it is a no-op.

Userspace API Structures¶

DRM exposes many UAPI and structure definition to have a consistentand standardized interface with user.Userspace can refer to these structure definitions and UAPI formatsto communicate to driver

structhdr_metadata_infoframe¶

HDR Metadata Infoframe Data.

Definition

struct hdr_metadata_infoframe {  __u8 eotf;  __u8 metadata_type;  struct {    __u16 x, y;  } display_primaries[3];  struct {    __u16 x, y;  } white_point;  __u16 max_display_mastering_luminance;  __u16 min_display_mastering_luminance;  __u16 max_cll;  __u16 max_fall;};

Members

eotf

Electro-Optical Transfer Function (EOTF)used in the stream.

metadata_type

Static_Metadata_Descriptor_ID.

display_primaries

Color Primaries of the Data.These are coded as unsigned 16-bit values in units of0.00002, where 0x0000 represents zero and 0xC350represents 1.0000.display_primaries.x: X cordinate of color primary.display_primaries.y: Y cordinate of color primary.

white_point

White Point of Colorspace Data.These are coded as unsigned 16-bit values in units of0.00002, where 0x0000 represents zero and 0xC350represents 1.0000.white_point.x: X cordinate of whitepoint of color primary.white_point.y: Y cordinate of whitepoint of color primary.

max_display_mastering_luminance

Max Mastering Display Luminance.This value is coded as an unsigned 16-bit value in units of 1 cd/m2,where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.

min_display_mastering_luminance

Min Mastering Display Luminance.This value is coded as an unsigned 16-bit value in units of0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFFrepresents 6.5535 cd/m2.

max_cll

Max Content Light Level.This value is coded as an unsigned 16-bit value in units of 1 cd/m2,where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.

max_fall

Max Frame Average Light Level.This value is coded as an unsigned 16-bit value in units of 1 cd/m2,where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.

Description

HDR Metadata Infoframe as per CTA 861.G spec. This is expectedto match exactly with the spec.

Userspace is expected to pass the metadata information as perthe format described in this structure.

structhdr_output_metadata¶

HDR output metadata

Definition

struct hdr_output_metadata {  __u32 metadata_type;  union {    struct hdr_metadata_infoframe hdmi_metadata_type1;  };};

Members

metadata_type

Static_Metadata_Descriptor_ID.

{unnamed_union}

anonymous

hdmi_metadata_type1

HDR Metadata Infoframe.

Description

Metadata Information to be passed from userspace

structdrm_mode_create_blob¶

Create New block property

Definition

struct drm_mode_create_blob {  __u64 data;  __u32 length;  __u32 blob_id;};

Members

data

Pointer to data to copy.

length

Length of data to copy.

blob_id

new property ID.Create a new ‘blob’ data property, copying length bytes from data pointer,and returning new blob ID.

structdrm_mode_destroy_blob¶

Destroy user blob

Definition

struct drm_mode_destroy_blob {  __u32 blob_id;};

Members

blob_id

blob_id to destroyDestroy a user-created blob property.

structdrm_mode_create_lease¶

Create lease

Definition

struct drm_mode_create_lease {  __u64 object_ids;  __u32 object_count;  __u32 flags;  __u32 lessee_id;  __u32 fd;};

Members

object_ids

Pointer to array of object ids.

object_count

Number of object ids.

flags

flags for new FD.

lessee_id

unique identifier for lessee.

fd

file descriptor to new drm_master file.Lease mode resources, creating another drm_master.

structdrm_mode_list_lessees¶

List lessees

Definition

struct drm_mode_list_lessees {  __u32 count_lessees;  __u32 pad;  __u64 lessees_ptr;};

Members

count_lessees

Number of lessees.

pad

pad.

lessees_ptr

Pointer to lessess.List lesses from a drm_master

structdrm_mode_get_lease¶

Get Lease

Definition

struct drm_mode_get_lease {  __u32 count_objects;  __u32 pad;  __u64 objects_ptr;};

Members

count_objects

Number of leased objects.

pad

pad.

objects_ptr

Pointer to objects.Get leased objects

structdrm_mode_revoke_lease¶

Revoke lease

Definition

struct drm_mode_revoke_lease {  __u32 lessee_id;};

Members

lessee_id

Unique ID of lessee.Revoke lease

structdrm_mode_rect¶

Two dimensional rectangle.

Definition

struct drm_mode_rect {  __s32 x1;  __s32 y1;  __s32 x2;  __s32 y2;};

Members

x1

Horizontal starting coordinate (inclusive).

y1

Vertical starting coordinate (inclusive).

x2

Horizontal ending coordinate (exclusive).

y2

Vertical ending coordinate (exclusive).

Description

With drm subsystem using struct drm_rect to manage rectangular area thisexport it to user-space.

Currently used by drm_mode_atomic blob property FB_DAMAGE_CLIPS.