.\"	$NetBSD: drm.4,v 1.21 2023/10/22 02:23:04 mrg Exp $
.\"
.\" Copyright (c) 2007, 2013 Thomas Klausner
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 21, 2023
.Dt DRM 4
.Os
.Sh NAME
.Nm drm
.Nd Direct Rendering Manager \(em display configuration and graphics rendering acceleration
.Sh SYNOPSIS
.Ss Kernel mode-setting drivers
.Cd "amdgpu*                at pci? dev ? function ?"
.Cd "i915drmkms*            at pci? dev ? function ?"
.Cd "nouveau*               at pci? dev ? function ?"
.Cd "radeon*                at pci? dev ? function ?"
.Cd "rkdrm*                 at fdt? pass 5"
.Cd "sunxidrm*              at fdt? pass 5"
.Cd "tegradrm*              at fdt? pass 5"
.Ss Legacy user mode-setting options and drivers
.Cd "options                DRM_LEGACY"
.Cd "viadrmums*             at drm?"
.Ss Options
.Cd "options        DRM_MAX_RESOLUTION_HORIZONTAL=integer"
.Cd "options        DRM_MAX_RESOLUTION_VERTICAL=integer"
.Sh DESCRIPTION
The Direct Rendering Manager is part of the Direct Rendering
Infrastructure for supporting display configuration and hardware
acceleration for graphics rendering and other computation on a graphics
processing unit
.Pq Tn GPU .
.Pp
.Nm
drivers come in two generations:
.Bl -tag -width No
.It Kernel mode-setting Pq Tn KMS
Modern drivers that query and control display configuration in the
kernel via
.Xr ioctl 2
commands exposed to userland.
.Pp
The
.Pa /dev/dri/render*
device nodes provide access to graphics buffers and command stream
submission for rendering.
The
.Pa /dev/dri/card*
device nodes additionally provide access to the display configuration.
.Pp
.Tn KMS
drivers provided as modules must generally be loaded by the bootloader,
configured in
.Xr boot.cfg 8 ,
and cannot be loaded dynamically.
.It User mode-setting Pq Tn UMS
Legacy drivers that rely on userland support code that accesses device
registers in the
.Xr X 7
server to query and control display configuration.
The kernel may be unable to recover if the display server crashes, or
the device is suspended or resumed.
.Pp
The kernel driver and
.Pa /dev/dri/card*
interfaces only manage buffers mapped in the
.Tn GPU
address space.
Display configuration from userland requires the
.Dv INSECURE
option
.Pq see Xr options 4
to allow userland access to device registers.
.Pp
The
.Dv DRM_LEGACY
option allows legacy
.Tn UMS
drivers to be loaded as modules
.Pq see Xr module 7 .
.El
.Pp
The
.Nm
drivers provide support for the following graphics devices:
.Bl -tag -width "i915drmkms" -offset indent
.It amdgpu
Newer
.Tn AMD
graphics devices.
.It i915drmkms
Intel integrated graphics devices from the i915 series onward.
.Po
Some i8xx support is included but not well-maintained.
i7xx is not supported.
.Pc
.It nouveau
.Tn NVIDIA
graphics devices.
.It radeon
Older
.Tn AMD
.Pq including formerly Tn ATI
Radeon graphics devices.
.It viadrmums Po legacy Tn UMS Pc
.Tn VIA
graphics devices.
.El
.Pp
With some drivers
.Pq at least Xr radeon 4 ,
in some cases the driver does not choose the resolution correctly.
The options
.Dv DRM_MAX_RESOLUTION_HORIZONTAL
and
.Dv DRM_MAX_RESOLUTION_VERTICAL
allow limiting the maximum resolution in X and Y direction.
.Pp
.Xr X 7
will attempt to create the device nodes automatically and use
.Nm
automatically.
To create a device node manually:
.Bd -literal -offset indent
mkdir -p /dev/dri
mknod /dev/dri/card0 c 180 0
chgrp wheel /dev/dri/card0
chmod 0660 /dev/dri/card0
.Ed
.Pp
Debugging output can be enabled and disabled by setting flag bits in
the
.Xr sysctl 8
node
.Dv hw.drm2.__drm_debug .
Various other knobs may be available under
.Dv hw.drm2 .
.Sh FILES
.Bl -tag -width ".Pa /dev/dri/render*"
.It Pa /dev/dri/render*
Provides access to graphics buffers and command stream submission for
rendering.
Generally unprivileged.
.It Pa /dev/dri/card*
In addition to everything provided by
.Pa /dev/dri/render* ,
provides access to change the display configuration.
Usually privileged.
.El
.Sh CODE REFERENCES
The
.Nm
subsystem and drivers mostly live under
.Pa sys/external/bsd/drm2 ,
with various Linux
.Tn API
shims in
.Pa sys/external/bsd/common
and some individual
.Nm
drivers scattered elsewhere in the tree.
.Sh SEE ALSO
.Xr Xorg 1 ,
.Xr agp 4 ,
.Xr xorg.conf 5 ,
.Xr X 7
.Pp
.Lk https://dri.freedesktop.org/ "Direct Rendering Infrastructure"
.Sh HISTORY
.Nm
was first available for Linux and later ported to
.Fx
and
.Nx .
The port to
.Nx
was redone after the introduction of
.Tn KMS .
.Pp
The first generation of
.Nm
drivers appeared in
.Nx 5.0 .
The second generation of
.Nm
with
.Tn KMS
appeared in
.Nx 7.0 .
.Sh AUTHORS
Too many to list.
.Pp
Work on the
.Nx
port was contributed by:
.An -nosplit
.An Anonymous ,
.An Nia Alarie ,
.An Eric Anholt ,
.An Rafal Boni ,
.An Taylor R Campbell ,
.An Mihai Chelaru ,
.An David Brownlee ,
.An Jarom\('ir Dole\[vc]ek ,
.An Matthias Drochner ,
.An Christoph Egger ,
.An FUKAUMI Naoki ,
.An Paul Goyette ,
.An matthew green ,
.An Yorick Hardy ,
.An Nick Hudson ,
.An Martin Husemann ,
.An Arto Huusko ,
.An Thomas Klausner ,
.An Jonathan Kollasch ,
.An Tonnerre Lombard ,
.An Jared McNeill ,
.An Jeremy Morse ,
.An Kimihiro Nonaka ,
.An Tobias Nygren ,
.An Rin Okuyama ,
.An Maya Rashish ,
.An Erik Reid ,
.An Masanobu SAITOH ,
.An Blair Sadewitz ,
.An Chuck Silvers ,
.An Nathanial Sloss ,
.An J\(:org Sonnenberger ,
.An Gr\('egoire Sutre ,
.An Matt Thomas ,
.An Izumi Tsutsui ,
.An Patrick Welche ,
and
.An Christos Zoulas .
.Sh CAVEATS
.Nm
is large and complicated and has no shortage of bugs.
On systems where graphics is not important, you may wish to use
.Xr userconf 4
to disable the special-purpose
.Nm
drivers for your graphics device and fall back to
.Xr vga 4
or
.Xr genfb 4
with the default display configuration provided by firmware.
.Pp
.Nm
is not
.Sq Digital Rights Management
and does not deprive you of agency over your own computer, except
insofar as the code base is difficult to maintain.