linux-imx

=============

DRM Internals

=============

​

This chapter documents DRM internals relevant to driver authors and

developers working to add support for the latest features to existing

drivers.

​

First, we go over some typical driver initialization requirements, like

setting up command buffers, creating an initial output configuration,

and initializing core services. Subsequent sections cover core internals

in more detail, providing implementation notes and examples.

​

The DRM layer provides several services to graphics drivers, many of

them driven by the application interfaces it provides through libdrm,

the library that wraps most of the DRM ioctls. These include vblank

event handling, memory management, output management, framebuffer

management, command submission & fencing, suspend/resume support, and

DMA services.

​

Driver Initialization

=====================

​

At the core of every DRM driver is a :c:type:`struct drm_driver

<drm_driver>` structure. Drivers typically statically initialize

a drm_driver structure, and then pass it to

:c:func:`drm_dev_alloc()` to allocate a device instance. After the

device instance is fully initialized it can be registered (which makes

it accessible from userspace) using :c:func:`drm_dev_register()`.

​

The :c:type:`struct drm_driver <drm_driver>` structure

contains static information that describes the driver and features it

supports, and pointers to methods that the DRM core will call to

implement the DRM API. We will first go through the :c:type:`struct

drm_driver <drm_driver>` static information fields, and will

then describe individual operations in details as they get used in later

sections.

​

Driver Information

------------------

​

Major, Minor and Patchlevel

~~~~~~~~~~~~~~~~~~~~~~~~~~~

​

int major; int minor; int patchlevel;

The DRM core identifies driver versions by a major, minor and patch

level triplet. The information is printed to the kernel log at

initialization time and passed to userspace through the

DRM_IOCTL_VERSION ioctl.

​

The major and minor numbers are also used to verify the requested driver

API version passed to DRM_IOCTL_SET_VERSION. When the driver API

changes between minor versions, applications can call

DRM_IOCTL_SET_VERSION to select a specific version of the API. If the

requested major isn't equal to the driver major, or the requested minor

is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will

return an error. Otherwise the driver's set_version() method will be

called with the requested version.

​

Name, Description and Date

~~~~~~~~~~~~~~~~~~~~~~~~~~

​

char \*name; char \*desc; char \*date;

The driver name is printed to the kernel log at initialization time,

used for IRQ registration and passed to userspace through

DRM_IOCTL_VERSION.

​

The driver description is a purely informative string passed to

userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by

the kernel.

​

The driver date, formatted as YYYYMMDD, is meant to identify the date of

the latest modification to the driver. However, as most drivers fail to

update it, its value is mostly useless. The DRM core prints it to the

kernel log at initialization time and passes it to userspace through the

DRM_IOCTL_VERSION ioctl.

​

Device Instance and Driver Handling

-----------------------------------

​

.. kernel-doc:: drivers/gpu/drm/drm_drv.c

   :doc: driver instance overview

​

.. kernel-doc:: include/drm/drm_device.h

   :internal:

​

.. kernel-doc:: include/drm/drm_drv.h

   :internal:

​

.. kernel-doc:: drivers/gpu/drm/drm_drv.c

   :export:

​