Module Name: src
Committed By: riastradh
Date: Wed Oct 18 10:28:07 UTC 2023
Modified Files:
src/share/man/man4: drm.4
Log Message:
drm(4): Update man page over the last decade.
While here, credit contributors just to the NetBSD port. Too many
upstream contributors to list, not even sure where I'd find them all.
To generate a diff of this commit:
cvs rdiff -u -r1.18 -r1.19 src/share/man/man4/drm.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/drm.4
diff -u src/share/man/man4/drm.4:1.18 src/share/man/man4/drm.4:1.19
--- src/share/man/man4/drm.4:1.18 Wed Mar 10 07:23:42 2021
+++ src/share/man/man4/drm.4 Wed Oct 18 10:28:06 2023
@@ -1,4 +1,4 @@
-.\" $NetBSD: drm.4,v 1.18 2021/03/10 07:23:42 wiz Exp $
+.\" $NetBSD: drm.4,v 1.19 2023/10/18 10:28:06 riastradh Exp $
.\"
.\" Copyright (c) 2007, 2013 Thomas Klausner
.\" All rights reserved.
@@ -23,75 +23,112 @@
.\" (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 March 10, 2021
+.Dd October 17, 2023
.Dt DRM 4
.Os
.Sh NAME
.Nm drm
-.Nd Direct Rendering Manager (DRI kernel support)
+.Nd Direct Rendering Manager \(em display configuration and graphics rendering acceleration
.Sh SYNOPSIS
-.Cd i915drm* at drm?
-.Cd mach64drm* at drm?
-.Cd mgadrm* at drm?
-.Cd r128drm* at drm?
-.Cd radeondrm* at drm?
-.Cd savagedrm* at drm?
-.Cd sisdrm* at drm?
-.Cd tdfxdrm* at drm?
-.Pp
-.Cd options DRM_DEBUG
-.Cd options DRM_NO_AGP
-.Cd options DRM_MAX_RESOLUTION_HORIZONTAL=integer
-.Cd options DRM_MAX_RESOLUTION_VERTICAL=integer
+.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 video acceleration (3d acceleration,
-mostly).
+Infrastructure for supporting display configuration and hardware
+acceleration for graphics rendering and other computation on a graphics
+processing unit
+.Pq Tn GPU .
.Pp
-The
.Nm
-drivers provide support for the following chipsets:
-.Bl -tag -width XsavagedrmXXX -offset indent -compact
-.It i915drm
-Intel i915, i945
-.It mach64drm
-Mach64 (3D Rage Pro, Rage)
-.It mgadrm
-Matrox G[24]00, G[45]50
-.It r128drm
-ATI Rage 128
-.It radeondrm
-ATI Radeon
-.It savagedrm
-S3 Savage
-.It sisdrm
-SiS
-.It tdfxdrm
-3dfx (Voodoo)
-.It viadrm
-VIA
-.El
+drivers come in two generations:
+.Bl -tag -width No
+.It Kernel mode-setting Pq Tn KMS
+Modern drivers that query and control device configuration in the
+kernel via
+.Xr ioctl 2
+commands exposed to userland.
.Pp
-To make use of the driver, the kernel must include
-.Xr agp 4
-(for some drivers, using
-.Cd options DRM_NO_AGP
-instead may be sufficient),
-.Xr X 7
-must be compiled with DRI support, Mesa DRI drivers must be installed,
-the appropriate
+The
+.Pa /dev/dri/render*
+device nodes provide access to graphics buffers and command stream
+submission for rendering.
+The
.Pa /dev/dri/card*
-device must exist, and DRI must be enabled in the X configuration
-file.
+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
-provided with
-.Nx
-and compiled from
-.Xr pkgsrc 7
-do so automatically where supported.
+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 formerly Tn ATI
+Radeon graphics devices.
+.It viadrmums Po legacy Tn UMS Pc
+.Tn VIA
+graphics devices.
+.El
.Pp
-With some drivers (at least
-.Xr radeon 4 ) ,
+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
@@ -100,8 +137,10 @@ and
allow limiting the maximum resolution in X and Y direction.
.Pp
.Xr X 7
-will attempt to create the device node automatically.
-To create the device node manually:
+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
@@ -109,106 +148,124 @@ chgrp wheel /dev/dri/card0
chmod 0660 /dev/dri/card0
.Ed
.Pp
-To enable DRI in the X configuration add the following to either
-.Pa xorg.conf
-for
-.Xr Xorg 1
-or
-.Pa XF86Config
-for
-.Xr XFree86 1
-:
-.Bd -literal -offset indent
-Section "Module"
- ...
- Load "dri"
- Load "dri2"
- Load "glx"
-EndSection
-\&...
-Section "DRI"
- Group "wheel"
- Mode 0660
-EndSection
-.Ed
-.Pp
-Debugging output can be enabled and disabled by setting the
+Debugging output can be enabled and disabled by setting flag bits in
+the
.Xr sysctl 8
node
-.Ar hw.dri.debug .
-Additional information can be obtained from the
-.Xr sysctl 8
-nodes
-.Ar hw.dri ,
-.Ar hw.dri.card0 ,
-.Ar hw.dri.card1 ,
-etc.
+.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 XFree86 1 ,
.Xr Xorg 1 ,
.Xr agp 4 ,
-.Xr XF86Config 5 ,
.Xr xorg.conf 5 ,
-.Xr X 7 ,
-.Pa /usr/X11R[67]/lib/X11/doc/README.DRI
+.Xr X 7
.Pp
-.Lk http://dri.freedesktop.org/ "Direct Rendering Infrastructure"
+.Lk https://dri.freedesktop.org/ "Direct Rendering Infrastructure"
.Sh HISTORY
-DRM was first available for Linux.
-Subsequently Eric Anholt ported the DRM kernel modules to
-.Fx .
-Erik Reid adapted the
+.Nm
+was first available for Linux and later ported to
.Fx
-DRM kernel modules to
+and
.Nx .
-As DRM continued to develop the
-.Nx
-support was neglected.
-Tonnerre Lombard got the DRM modules working again, but DRM
-development once again left the
+The port to
.Nx
-support behind.
-Finally Yorick Hardy took the
-.Fx
-DRM source and managed to get it compiling and working again on
-.Nx ,
-thanks largely to the efforts of all those mentioned above.
-Subsequently Matthias Drochner improved the DRM file hierarchy for
-.Nx
-and committed the DRM kernel drivers.
-Matthew Green cleaned up this port and merged a set of newer
-drivers, with Arto Huusko and FUKAUMI Naoki helping to get
-the latest Mesa port up to date.
+was redone after the introduction of
+.Tn KMS .
.Pp
-The
+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 Terry Barnaby ,
-.An Erdi Chen ,
-.An Michel Daenzer ,
-.An Leif Delgass ,
-.An Frank C. Earl ,
-.An Rickard E. Faith ,
-.An Jose Fonseca ,
-.An Nicolai Haehnle ,
-.An Jeff Hartmann ,
-.An Thomas Hellstrom ,
-.An Gareth Hughes ,
-.An Felix Kuehling ,
-.An Sung-Ching Lin ,
-.An Kevin E. Martin ,
-.An Daryll Strauss ,
-.An Keith Whitwell
+.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
-In case of errors,
-.Pa /dev/dri/card0
-may be changed, make sure to recreate it in that case.
+.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
-.Cd options DRM_DEBUG
-can slow DRI down a lot; disable it once
.Nm
-works.
+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.
