Editing Direct Rendering Manager (section)

=== {{Anchor|Kernel mode setting|KMS driver}} Kernel Mode Setting ===
[[File:Linux kernel and daemons with exclusive access.svg|thumb|There must be a "DRM master" in user-space, this program has exclusive access to KMS.]]

In order to work properly, a video card or graphics adapter must set a ''[[Framebuffer#Display modes|mode]]''&mdash;a combination of [[screen resolution]], [[color depth]] and [[refresh rate]]&mdash;that is within the range of values supported by itself and the attached [[Computer monitor|display screen]]. This operation is called [[mode-setting]],{{r|Kernelnewbies linux 2.6.29}} and it usually requires raw access to the graphics hardware&mdash;i.e. the ability to write to certain registers of the video card [[display controller]].{{r|OSDev VGA}}{{r|Rathmann 2008}} A mode-setting operation must be performed before starting to use the [[framebuffer]], and also when the mode is required to change by an application or the user.

In the early days, [[User_space_and_kernel_space|user-space]] programs that wanted to use the graphical framebuffer were also responsible for providing the mode-setting operations.{{r|White}} Thus, they needed to run with privileged access to the video hardware. In Unix-type operating systems, the [[X Window System|X Server]] was the most prominent example. Its mode-setting implementation lived in the [[Device Dependent X|DDX driver]] for each specific type of video card.{{r|Paalanen 2014}} This approach, later referred to as ''User space Mode-Setting'' or UMS,{{r|kms manpage}}{{r|Corbet 2010}} poses several issues.{{r|X wiki modesetting}}{{r|Kernelnewbies linux 2.6.29}} It not only breaks the isolation that operating systems should provide between programs and hardware, raising both stability and security concerns, but also could leave the graphics hardware in an inconsistent state if two or more user space programs try to do the mode-setting at the same time. To avoid these conflicts, the X Server became in practice the only user space program that performed mode-setting operations; the remainder user space programs relied on the X Server to set the appropriate mode and to handle any other operation involving mode-setting. Initially the mode-setting was performed exclusively during the X Server startup process, but later the X Server gained the ability to do it while running.{{r|Corbet 2007 LCA}} The XFree86-VidModeExtension extension was introduced in [[XFree86]] 3.1.2 to let any X client request [[XFree86 Modeline|modeline]] (resolution) changes to the X Server.{{r|XF86vidmode man}}{{r|X11R6.1 relnotes}} VidMode extension was later superseded by the more generic [[XRandR]] extension.

However, this was not the only code doing mode-setting in a [[Linux]] system. During the system booting process, the Linux kernel must set a minimal [[text mode]] for the [[Linux console|virtual console]] (based on the standard modes defined by [[VESA BIOS]] extensions).{{r|Corbet 2004}} Also the [[Linux framebuffer|Linux kernel framebuffer driver]] contained mode-setting code to configure framebuffer devices.{{r|fb doc}} To avoid mode-setting conflicts, the [[XFree86|XFree86 Server]]&mdash;and later the [[X.Org Server]]&mdash;handled the case when the user switched from the graphical environment to a text [[virtual console]] by saving its mode-setting state, and restoring it when the user switched back to X.{{r|Fedora KMS}} This process caused an annoying flicker in the transition, and also can fail, leading to a corrupted or unusable output display.{{r|Barnes modesetting}}

The user space mode setting approach also caused other issues:{{r|DRI Wiki modesetting}}{{r|Barnes modesetting}}
* The [[sleep mode|suspend/resume process]] has to rely on user space tools to restore the previous mode. One single failure or crash of one of these programs could leave the system without a working display due to a modeset misconfiguration, and therefore unusable.
* It was also impossible for the kernel to show error or debug messages when the screen was in a graphics mode&mdash;for example when X was running&mdash;since the only modes the kernel knew about were the VESA BIOS standard text modes.
* A more pressing issue was the proliferation of graphical applications bypassing the X Server and the emergence of other graphics stack alternatives to X, extending the duplication of mode-setting code across the system even further.

To address these problems, the mode-setting code was moved to a single place inside the kernel, specifically to the existing DRM module.{{r|X wiki modesetting}}{{r|Corbet 2007 LCA}}{{r|Packard 2007}}{{r|Barnes modesetting}}{{r|DRI Wiki modesetting}} Then, every process&mdash;including the X Server&mdash;should be able to command the kernel to perform mode-setting operations, and the kernel would ensure that concurrent operations don't result in an inconsistent state. The new kernel API and code added to the DRM module to perform these mode-setting operations was called ''Kernel Mode-Setting'' (KMS).{{r|Kernelnewbies linux 2.6.29}}

Kernel Mode-Setting provides several benefits. The most immediate is of course the removal of duplicate mode-setting code, from both the kernel (Linux console, fbdev) and user space (X Server DDX drivers). KMS also makes it easier to write alternative graphics systems, which now don't need to implement their own mode-setting code.{{r|Barnes modesetting}}{{r|DRI Wiki modesetting}} By providing centralized mode management, KMS solves the flickering issues while changing between console and X, and also between different instances of X (fast user switching).{{r|Fedora KMS}}{{r|Packard 2007}} Since it is available in the kernel, it can also be used at the beginning of the boot process, saving flickering due to mode changes in these early stages.

The fact that KMS is part of the kernel allows it to use resources only available at kernel space such as [[Hardware interrupt|interrupts]].{{r|Packard 2009}} For example, the mode recovery after a suspend/resume process simplifies a lot by being managed by the kernel itself, and incidentally improves security (no more user space tools requiring root permissions). The kernel also allows the [[hotplug]] of new display devices easily, solving a longstanding problem.{{r|Packard 2009}} Mode-setting is also closely related to memory management&mdash;since framebuffers are basically memory buffers&mdash;so a tight integration with the graphics memory manager is highly recommended. That's the main reason why the kernel mode-setting code was incorporated into DRM and not as a separate subsystem.{{r|Packard 2007}}

To avoid breaking backwards compatibility of the DRM API, Kernel Mode-Setting is provided as an additional ''driver feature'' of certain DRM drivers.{{r|drmbook-init}} Any DRM driver can choose to provide the {{mono|DRIVER_MODESET}} flag when it registers with the DRM core to indicate that supports the KMS API.{{r|Kitching 2012}} Those drivers that implement Kernel Mode-Setting are often called ''KMS drivers'' as a way to differentiate them from the legacy&mdash;without KMS&mdash;DRM drivers.

KMS has been adopted to such an extent that certain drivers which lack 3D acceleration (or for which the hardware vendor doesn't want to expose or implement it) nevertheless implement the KMS API without the rest of the DRM API, allowing display servers (like [[Wayland (protocol)|Wayland]]) to run with ease.<ref>{{Cite web |date=2023-01-31 |title=q3k (@q3k@hackerspace.pl) |url=https://social.hackerspace.pl/@q3k/109783347119397449 |access-date=2023-02-13 |website=Warsaw Hackerspace Social Club |language=en |quote=DRM/KMS driver fully working now, although still without DMA. Oh, and it's written in Rust, although it's mostly just full of raw unsafe blocks.}}</ref><ref>{{Cite web |date=2023-01-31 |title=q3k (@q3k@hackerspace.pl) |url=https://social.hackerspace.pl/@q3k/109785149255867298 |access-date=2023-02-13 |website=Warsaw Hackerspace Social Club |language=en |quote=Cool thing is, since we have a 'normal' DRM/KMS driver (and help from @emersion@hackerspace.pl) we can just do things like... run Wayland! Weston on an iPod Nano 5G.}}</ref>

==== KMS device model ====
KMS models and manages the output devices as a series of abstract hardware blocks commonly found on the display output pipeline of a [[display controller]]. These blocks are:{{r|drmbook-kms}}

* '''CRTCs''': each CRTC (from [[Cathode-ray tube|CRT]] Controller{{r|X wiki videocards}}{{r|Paalanen 2014}}) represents a scanout engine of the display controller, pointing to a ''scanout buffer'' ([[framebuffer]]).{{r|drmbook-kms}} The purpose of a CRTC is to read the pixel data currently in the scanout buffer and generate from it the [[Video signal|video mode timing signal]] with the help of a [[Phase-locked loop|PLL circuit]].{{r|Deucher 2010}} The number of CRTCs available determines how many independent output devices the hardware can handle at the same time, so in order to use ''[[Multi-monitor|multi-head]]'' configurations at least one CRTC per display device is required.{{r|drmbook-kms}} Two&mdash;or more&mdash;CRTCs can also work in ''clone mode'' if they scan out from the same framebuffer to send the same image to several output devices.{{r|Deucher 2010}}{{r|X wiki videocards}}
* '''Connectors''': a connector represents where the display controller sends the video signal from a scanout operation to be displayed. Usually, the KMS concept of a connector corresponds to a physical connector ([[VGA connector|VGA]], [[Digital Visual Interface|DVI]], [[FPD-Link]], [[HDMI]], [[DisplayPort]], [[S-Video]], ...) in the hardware where an output device ([[Computer monitor|monitor]], [[laptop]] panel, ...) is permanently or can temporarily be attached. Information related to the current physically attached output device&mdash;such as connection status, [[Extended Display Identification Data|EDID]] data, [[VESA Display Power Management Signaling|DPMS]] status or supported video modes&mdash;is also stored within the connector.{{r|drmbook-kms}}
* '''Encoders''': the display controller must encode the video mode timing signal from the CRTC using a format suitable for the intended connector.{{r|drmbook-kms}} An encoder represents the hardware block able to do one of these encodings. Examples of encodings&mdash;for digital outputs&mdash;are [[Transition-minimized differential signaling|TMDS]] and [[Low-voltage differential signaling|LVDS]]; for analog outputs such as [[Video Graphics Array|VGA]] and TV out, specific [[Digital-to-analog converter|DAC]] blocks are generally used. A connector can only receive the signal from one encoder at a time,{{r|drmbook-kms}} and each type of connector only supports some encodings. There also might be additional physical restrictions by which not every CRTC is connected to every available encoder, limiting the possible combinations of CRTC-encoder-connector.
* '''Planes''': a plane is not a hardware block but a memory object containing a buffer from which a scanout engine (a CRTC) is fed. The plane that holds the [[framebuffer]] is called the ''primary plane'', and each CRTC must have one associated,{{r|drmbook-kms}} since it is the source for the CRTC to determine the video mode&mdash;display resolution (width and height), pixel size, pixel format, refresh rate, etc. A CRTC might have also ''cursor planes'' associated to it if the display controller supports hardware cursor overlays, or ''secondary planes'' if it's able to scan out from additional [[hardware overlay]]s and compose or blend "on the fly" the final image sent to the output device.{{r|Paalanen 2014}}

==== {{Anchor|Atomic mode setting|nuclear pageflip}}Atomic Display ====
In recent years there has been an ongoing effort to bring [[Atomicity (programming)|atomicity]] to some regular operations pertaining the KMS API, specifically to the [[mode setting]] and [[page flipping]] operations.{{r|Paalanen 2014}}{{r|Vetter 2015 LWN p1}} This enhanced KMS API is what is called ''Atomic Display'' (formerly known as ''atomic mode-setting'' and ''atomic'' or ''nuclear pageflip'').
 
The purpose of the ''atomic mode-setting'' is to ensure a correct change of mode in complex configurations with multiple restrictions, by avoiding intermediate steps which could lead to an inconsistent or invalid video state;{{r|Vetter 2015 LWN p1}} it also avoids risky video states when a failed mode-setting process has to be undone ("rollback").{{r|Reding 2015|p=9}} Atomic mode-setting allows one to know beforehand if certain specific mode configuration is appropriate, by providing mode testing capabilities.{{r|Vetter 2015 LWN p1}} When an atomic mode is tested and its validity confirmed, it can be applied with a single indivisible (atomic) [[Atomic commit|commit]] operation. Both test and commit operations are provided by the same new [[ioctl]] with different flags.

''Atomic page flip'' on the other hand allows to update multiple planes on the same output (for instance the primary plane, the cursor plane and maybe some overlays or secondary planes) all synchronized within the same [[Vertical blanking interval|VBLANK]] interval, ensuring a proper display without tearing.{{r|Reding 2015|p=9,14}}{{r|Vetter 2015 LWN p1}} This requirement is especially relevant to mobile and embedded display controllers, that tend to use multiple planes/overlays to save power.

The new atomic API is built upon the old KMS API. It uses the same model and objects (CRTCs, encoders, connectors, planes, ...), but with an increasing number of object properties that can be modified.{{r|Vetter 2015 LWN p1}} The atomic procedure is based on changing the relevant properties to build the state that we want to test or commit. The properties we want to modify depend on whether we want to do a mode-setting (mostly CRTCs, encoders and connectors properties) or page flipping (usually planes properties). The ioctl is the same for both cases, the difference being the list of properties passed with each one.{{r|Vetter 2015 LWN p2}}