1.\" $NetBSD: drm.4,v 1.21 2023/10/22 02:23:04 mrg Exp $ 2.\" 3.\" Copyright (c) 2007, 2013 Thomas Klausner 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd October 21, 2023 27.Dt DRM 4 28.Os 29.Sh NAME 30.Nm drm 31.Nd Direct Rendering Manager \(em display configuration and graphics rendering acceleration 32.Sh SYNOPSIS 33.Ss Kernel mode-setting drivers 34.Cd "amdgpu* at pci? dev ? function ?" 35.Cd "i915drmkms* at pci? dev ? function ?" 36.Cd "nouveau* at pci? dev ? function ?" 37.Cd "radeon* at pci? dev ? function ?" 38.Cd "rkdrm* at fdt? pass 5" 39.Cd "sunxidrm* at fdt? pass 5" 40.Cd "tegradrm* at fdt? pass 5" 41.Ss Legacy user mode-setting options and drivers 42.Cd "options DRM_LEGACY" 43.Cd "viadrmums* at drm?" 44.Ss Options 45.Cd "options DRM_MAX_RESOLUTION_HORIZONTAL=integer" 46.Cd "options DRM_MAX_RESOLUTION_VERTICAL=integer" 47.Sh DESCRIPTION 48The Direct Rendering Manager is part of the Direct Rendering 49Infrastructure for supporting display configuration and hardware 50acceleration for graphics rendering and other computation on a graphics 51processing unit 52.Pq Tn GPU . 53.Pp 54.Nm 55drivers come in two generations: 56.Bl -tag -width No 57.It Kernel mode-setting Pq Tn KMS 58Modern drivers that query and control display configuration in the 59kernel via 60.Xr ioctl 2 61commands exposed to userland. 62.Pp 63The 64.Pa /dev/dri/render* 65device nodes provide access to graphics buffers and command stream 66submission for rendering. 67The 68.Pa /dev/dri/card* 69device nodes additionally provide access to the display configuration. 70.Pp 71.Tn KMS 72drivers provided as modules must generally be loaded by the bootloader, 73configured in 74.Xr boot.cfg 8 , 75and cannot be loaded dynamically. 76.It User mode-setting Pq Tn UMS 77Legacy drivers that rely on userland support code that accesses device 78registers in the 79.Xr X 7 80server to query and control display configuration. 81The kernel may be unable to recover if the display server crashes, or 82the device is suspended or resumed. 83.Pp 84The kernel driver and 85.Pa /dev/dri/card* 86interfaces only manage buffers mapped in the 87.Tn GPU 88address space. 89Display configuration from userland requires the 90.Dv INSECURE 91option 92.Pq see Xr options 4 93to allow userland access to device registers. 94.Pp 95The 96.Dv DRM_LEGACY 97option allows legacy 98.Tn UMS 99drivers to be loaded as modules 100.Pq see Xr module 7 . 101.El 102.Pp 103The 104.Nm 105drivers provide support for the following graphics devices: 106.Bl -tag -width "i915drmkms" -offset indent 107.It amdgpu 108Newer 109.Tn AMD 110graphics devices. 111.It i915drmkms 112Intel integrated graphics devices from the i915 series onward. 113.Po 114Some i8xx support is included but not well-maintained. 115i7xx is not supported. 116.Pc 117.It nouveau 118.Tn NVIDIA 119graphics devices. 120.It radeon 121Older 122.Tn AMD 123.Pq including formerly Tn ATI 124Radeon graphics devices. 125.It viadrmums Po legacy Tn UMS Pc 126.Tn VIA 127graphics devices. 128.El 129.Pp 130With some drivers 131.Pq at least Xr radeon 4 , 132in some cases the driver does not choose the resolution correctly. 133The options 134.Dv DRM_MAX_RESOLUTION_HORIZONTAL 135and 136.Dv DRM_MAX_RESOLUTION_VERTICAL 137allow limiting the maximum resolution in X and Y direction. 138.Pp 139.Xr X 7 140will attempt to create the device nodes automatically and use 141.Nm 142automatically. 143To create a device node manually: 144.Bd -literal -offset indent 145mkdir -p /dev/dri 146mknod /dev/dri/card0 c 180 0 147chgrp wheel /dev/dri/card0 148chmod 0660 /dev/dri/card0 149.Ed 150.Pp 151Debugging output can be enabled and disabled by setting flag bits in 152the 153.Xr sysctl 8 154node 155.Dv hw.drm2.__drm_debug . 156Various other knobs may be available under 157.Dv hw.drm2 . 158.Sh FILES 159.Bl -tag -width ".Pa /dev/dri/render*" 160.It Pa /dev/dri/render* 161Provides access to graphics buffers and command stream submission for 162rendering. 163Generally unprivileged. 164.It Pa /dev/dri/card* 165In addition to everything provided by 166.Pa /dev/dri/render* , 167provides access to change the display configuration. 168Usually privileged. 169.El 170.Sh CODE REFERENCES 171The 172.Nm 173subsystem and drivers mostly live under 174.Pa sys/external/bsd/drm2 , 175with various Linux 176.Tn API 177shims in 178.Pa sys/external/bsd/common 179and some individual 180.Nm 181drivers scattered elsewhere in the tree. 182.Sh SEE ALSO 183.Xr Xorg 1 , 184.Xr agp 4 , 185.Xr xorg.conf 5 , 186.Xr X 7 187.Pp 188.Lk https://dri.freedesktop.org/ "Direct Rendering Infrastructure" 189.Sh HISTORY 190.Nm 191was first available for Linux and later ported to 192.Fx 193and 194.Nx . 195The port to 196.Nx 197was redone after the introduction of 198.Tn KMS . 199.Pp 200The first generation of 201.Nm 202drivers appeared in 203.Nx 5.0 . 204The second generation of 205.Nm 206with 207.Tn KMS 208appeared in 209.Nx 7.0 . 210.Sh AUTHORS 211Too many to list. 212.Pp 213Work on the 214.Nx 215port was contributed by: 216.An -nosplit 217.An Anonymous , 218.An Nia Alarie , 219.An Eric Anholt , 220.An Rafal Boni , 221.An Taylor R Campbell , 222.An Mihai Chelaru , 223.An David Brownlee , 224.An Jarom\('ir Dole\[vc]ek , 225.An Matthias Drochner , 226.An Christoph Egger , 227.An FUKAUMI Naoki , 228.An Paul Goyette , 229.An matthew green , 230.An Yorick Hardy , 231.An Nick Hudson , 232.An Martin Husemann , 233.An Arto Huusko , 234.An Thomas Klausner , 235.An Jonathan Kollasch , 236.An Tonnerre Lombard , 237.An Jared McNeill , 238.An Jeremy Morse , 239.An Kimihiro Nonaka , 240.An Tobias Nygren , 241.An Rin Okuyama , 242.An Maya Rashish , 243.An Erik Reid , 244.An Masanobu SAITOH , 245.An Blair Sadewitz , 246.An Chuck Silvers , 247.An Nathanial Sloss , 248.An J\(:org Sonnenberger , 249.An Gr\('egoire Sutre , 250.An Matt Thomas , 251.An Izumi Tsutsui , 252.An Patrick Welche , 253and 254.An Christos Zoulas . 255.Sh CAVEATS 256.Nm 257is large and complicated and has no shortage of bugs. 258On systems where graphics is not important, you may wish to use 259.Xr userconf 4 260to disable the special-purpose 261.Nm 262drivers for your graphics device and fall back to 263.Xr vga 4 264or 265.Xr genfb 4 266with the default display configuration provided by firmware. 267.Pp 268.Nm 269is not 270.Sq Digital Rights Management 271and does not deprive you of agency over your own computer, except 272insofar as the code base is difficult to maintain. 273