DragonFly On-Line Manual Pages
DRM(4) DragonFly Kernel Interfaces Manual DRM(4)
NAME
drm - Direct Rendering Manager (DRI kernel support)
DESCRIPTION
The Direct Rendering Manager is part of the Direct Rendering
Infrastructure (see http://dri.freedesktop.org/) for supporting video
acceleration.
The drm drivers provide support for the following chipsets:
Module Kernel option Chipset
i915.ko i915 Intel i915, i945, i965, G3x,
G4x
radeon.ko radeon AMD/ATI Radeon
amdgpu.ko n/a newer AMD chipsets
In most cases Xorg(1) will take care of loading the appropriate modules
and it is not necessary to modify loader.conf(5) or the kernel
configuration to enable drm support.
Newer versions of Xorg(1), like the one from dports(7), do a pretty good
job of figuring out the right configuration on their own, so having no
xorg.conf(5) file at all is usually the best advice. If for some reason
an xorg.conf(5) is preferred, DRI must be enabled:
Section "DRI"
Group "video"
Mode 0660
EndSection
With KMS, DRI is always enabled since the drm is always required.
To access /dev/dri/cardN devices user must be a member of the video
group. Users can be added to the video group with pw(8) groupmod option.
If Xorg(1) acceleration fails to initialize with a "contigmalloc_map:
failed size..." error in dmesg, the reserve of memory for DMA ran out
early and should be increased to a sufficiently high value by setting the
vm.dma_reserved loader tunable. A read only sysctl(8) variable of the
same name is provided for obtaining its current value.
LOADER TUNABLES
Tunables can be set at the loader(8) prompt before booting the kernel or
stored in loader.conf(5).
drm.debug
Enable internal verbose debug messages, might slow down the
machine. Debug categories are enabled by setting their bits:
0x001 CORE - generic drm code
0x002 DRIVER - vendor specific parts of the driver
0x004 KMS - modesetting troubleshoot
0x008 PRIME (no prime support)
0x010 ATOMIC - atomic code used by i915
0x100 PID - include pid number (useful in certain scenarios)
0x200 FIOCTL - failed ioctls
0x400 IOCTL - very spammy ioctl prints
0x800 VBLANK - very spammy vblank prints
drm.edid_firmware
Load external EDID binary monitor data from a firmware module.
Useful if the monitor is not sending an appropriate EDID block,
if there is no video on the connected monitor or if there is a
need to enforce custom video modes. Optionally, the connector
name can be specified before the firmware name followed by a
colon. For example:
drm.edid_firmware="DVI-D-1:edidfw_repaired"
Notes: drm and Xorg(1) use different naming conventions for
connector names. This tunable only applies for KMS drivers.
drm.video.<connector>
Can be used to set framebuffer parameters for drm(4) connector.
Mode specifier format:
<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]
<xres> X resolution, e.g. 1920
<yres> Y resolution, e.g. 1080
M calculate timings using VESA CVT instead of table
lookups
R reduced blanking on digital monitors
<bpp> color depth
<refresh> refresh rate
i calculate timings for interlaced mode
m margins used in calculations
e force enable output
D same as e option, but force digital output on HDMI/DVI
d force disable output
SYSCTL VARIABLES
A number of sysctl(8) variables are available:
hw.dri.debug If set, enables debugging output.
hw.dri.vblank_offdelay Specifies the delay (in milliseconds) until
the vblank interrupt is disabled again when
it's no longer needed. (0 = never disable,
negative value = disable immediately)
hw.dri.%d.busid Indicates the location of the device on the
PCI bus. The format is:
[0000-ffff]:[00-ff]:[00-1f].[0-7]
hw.dri.%d.modesetting Indicates if kernel mode setting
(DRIVER_MODESET feature) is set in the device
driver.
SEE ALSO
Xorg(1), amdgpu(4), i915(4), radeon(4), xorg.conf(5)
HISTORY
DRM was first available for Linux. Subsequently Eric Anholt ported the
DRM kernel modules to FreeBSD.
CAVEATS
Disable AIGLX if necessary (xorg.conf):
Section "ServerFlags"
Option "AIGLX" "off"
EndSection
options DRM_DEBUG can slow DRI down a lot, disable it once drm works.
DragonFly 6.3-DEVELOPMENT June 18, 2022 DragonFly 6.3-DEVELOPMENT
DRM-MEMORY(7) Direct Rendering Manager DRM-MEMORY(7)
NAME
drm-memory - DRM Memory Management
SYNOPSIS
#include <xf86drm.h>
DESCRIPTION
Many modern high-end GPUs come with their own memory managers. They
even include several different caches that need to be synchronized
during access. Textures, framebuffers, command buffers and more need
to be stored in memory that can be accessed quickly by the GPU.
Therefore, memory management on GPUs is highly driver- and
hardware-dependent.
However, there are several frameworks in the kernel that are used by
more than one driver. These can be used for trivial mode-setting
without requiring driver-dependent code. But for hardware-accelerated
rendering you need to read the manual pages for the driver you want to
work with.
Dumb-Buffers
Almost all in-kernel DRM hardware drivers support an API called
Dumb-Buffers. This API allows to create buffers of arbitrary size that
can be used for scanout. These buffers can be memory mapped via mmap(2)
so you can render into them on the CPU. However, GPU access to these
buffers is often not possible. Therefore, they are fine for simple
tasks but not suitable for complex compositions and renderings.
The DRM_IOCTL_MODE_CREATE_DUMB ioctl can be used to create a dumb
buffer. The kernel will return a 32-bit handle that can be used to
manage the buffer with the DRM API. You can create framebuffers with
drmModeAddFB(3) and use it for mode-setting and scanout. To access the
buffer, you first need to retrieve the offset of the buffer. The
DRM_IOCTL_MODE_MAP_DUMB ioctl requests the DRM subsystem to prepare the
buffer for memory-mapping and returns a fake-offset that can be used
with mmap(2).
The DRM_IOCTL_MODE_CREATE_DUMB ioctl takes as argument a structure of
type struct drm_mode_create_dumb:
struct drm_mode_create_dumb {
__u32 height;
__u32 width;
__u32 bpp;
__u32 flags;
__u32 handle;
__u32 pitch;
__u64 size;
};
The fields height, width, bpp and flags have to be provided by the
caller. The other fields are filled by the kernel with the return
values. height and width are the dimensions of the rectangular buffer
that is created. bpp is the number of bits-per-pixel and must be a
multiple of 8. You most commonly want to pass 32 here. The flags field
is currently unused and must be zeroed. Different flags to modify the
behavior may be added in the future. After calling the ioctl, the
handle, pitch and size fields are filled by the kernel. handle is a
32-bit gem handle that identifies the buffer. This is used by several
other calls that take a gem-handle or memory-buffer as argument. The
pitch field is the pitch (or stride) of the new buffer. Most drivers
use 32-bit or 64-bit aligned stride-values. The size field contains the
absolute size in bytes of the buffer. This can normally also be
computed with (height * pitch * width) * bpp / 4.
To prepare the buffer for mmap(2) you need to use the
DRM_IOCTL_MODE_MAP_DUMB ioctl. It takes as argument a structure of type
struct drm_mode_map_dumb:
struct drm_mode_map_dumb {
__u32 handle;
__u32 pad;
__u64 offset;
};
You need to put the gem-handle that was previously retrieved via
DRM_IOCTL_MODE_CREATE_DUMB into the handle field. The pad field is
unused padding and must be zeroed. After completion, the offset field
will contain an offset that can be used with mmap(2) on the DRM
file-descriptor.
If you don't need your dumb-buffer, anymore, you have to destroy it
with DRM_IOCTL_MODE_DESTROY_DUMB. If you close the DRM file-descriptor,
all open dumb-buffers are automatically destroyed. This ioctl takes as
argument a structure of type struct drm_mode_destroy_dumb:
struct drm_mode_destroy_dumb {
__u32 handle;
};
You only need to put your handle into the handle field. After this
call, the handle is invalid and may be reused for new buffers by the
dumb-API.
TTM
TTM stands for Translation Table Manager and is a generic
memory-manager provided by the kernel. It does not provide a common
user-space API so you need to look at each driver interface if you want
to use it. See for instance the radeon man pages for more information
on memory-management with radeon and TTM.
GEM
GEM stands for Graphics Execution Manager and is a generic DRM
memory-management framework in the kernel, that is used by many
different drivers. GEM is designed to manage graphics memory, control
access to the graphics device execution context and handle essentially
NUMA environment unique to modern graphics hardware. GEM allows
multiple applications to share graphics device resources without the
need to constantly reload the entire graphics card. Data may be shared
between multiple applications with gem ensuring that the correct memory
synchronization occurs.
GEM provides simple mechanisms to manage graphics data and control
execution flow within the linux DRM subsystem. However, GEM is not a
complete framework that is fully driver independent. Instead, if
provides many functions that are shared between many drivers, but each
driver has to implement most of memory-management with driver-dependent
ioctls. This manpage tries to describe the semantics (and if it
applies, the syntax) that is shared between all drivers that use GEM.
All GEM APIs are defined as ioctl(2) on the DRM file descriptor. An
application must be authorized via drmAuthMagic(3) to the current
DRM-Master to access the GEM subsystem. A driver that does not support
GEM will return ENODEV for all these ioctls. Invalid object handles
return EINVAL and invalid object names return ENOENT.
Gem provides explicit memory management primitives. System pages are
allocated when the object is created, either as the fundamental storage
for hardware where system memory is used by the graphics processor
directly, or as backing store for graphics-processor resident memory.
Objects are referenced from user-space using handles. These are, for
all intents and purposes, equivalent to file descriptors but avoid the
overhead. Newer kernel drivers also support the drm-prime (7)
infrastructure which can return real file-descriptor for GEM-handles
using the linux DMA-BUF API. Objects may be published with a name so
that other applications and processes can access them. The name remains
valid as long as the object exists. GEM-objects are reference counted
in the kernel. The object is only destroyed when all handles from
user-space were closed.
GEM-buffers cannot be created with a generic API. Each driver provides
its own API to create GEM-buffers. See for example DRM_I915_GEM_CREATE,
DRM_NOUVEAU_GEM_NEW or DRM_RADEON_GEM_CREATE. Each of these ioctls
returns a GEM-handle that can be passed to different generic ioctls.
The libgbm library from the mesa3D distribution tries to provide a
driver-independent API to create GBM buffers and retrieve a GBM-handle
to them. It allows to create buffers for different use-cases including
scanout, rendering, cursors and CPU-access. See the libgbm library for
more information or look at the driver-dependent man-pages (for example
drm-intel(7) or drm-radeon(7)).
GEM-buffers can be closed with drmCloseBufferHandle(3). It takes as
argument the GEM-handle to be closed. After this call the GEM handle
cannot be used by this process anymore and may be reused for new GEM
objects by the GEM API.
If you want to share GEM-objects between different processes, you can
create a name for them and pass this name to other processes which can
then open this GEM-object. Names are currently 32-bit integer IDs and
have no special protection. That is, if you put a name on your
GEM-object, every other client that has access to the DRM device and is
authenticated via drmAuthMagic(3) to the current DRM-Master, can guess
the name and open or access the GEM-object. If you want more
fine-grained access control, you can use the new drm-prime(7) API to
retrieve file-descriptors for GEM-handles. To create a name for a
GEM-handle, you use the DRM_IOCTL_GEM_FLINK ioctl. It takes as argument
a structure of type struct drm_gem_flink:
struct drm_gem_flink {
__u32 handle;
__u32 name;
};
You have to put your handle into the handle field. After completion,
the kernel has put the new unique name into the name field. You can now
pass this name to other processes which can then import the name with
the DRM_IOCTL_GEM_OPEN ioctl. It takes as argument a structure of type
struct drm_gem_open:
struct drm_gem_open {
__u32 name;
__u32 handle;
__u32 size;
};
You have to fill in the name field with the name of the GEM-object that
you want to open. The kernel will fill in the handle and size fields
with the new handle and size of the GEM-object. You can now access the
GEM-object via the handle as if you created it with the GEM API.
Besides generic buffer management, the GEM API does not provide any
generic access. Each driver implements its own functionality on top of
this API. This includes execution-buffers, GTT management, context
creation, CPU access, GPU I/O and more. The next higher-level API is
OpenGL. So if you want to use more GPU features, you should use the
mesa3D library to create OpenGL contexts on DRM devices. This does not
require any windowing-system like X11, but can also be done on raw DRM
devices. However, this is beyond the scope of this man-page. You may
have a look at other mesa3D man pages, including libgbm and libEGL. 2D
software-rendering (rendering with the CPU) can be achieved with the
dumb-buffer-API in a driver-independent fashion, however, for
hardware-accelerated 2D or 3D rendering you must use OpenGL. Any other
API that tries to abstract the driver-internals to access
GEM-execution-buffers and other GPU internals, would simply reinvent
OpenGL so it is not provided. But if you need more detailed information
for a specific driver, you may have a look into the driver-manpages,
including drm-intel(7), drm-radeon(7) and drm-nouveau(7). However, the
drm-prime(7) infrastructure and the generic GEM API as described here
allow display-managers to handle graphics-buffers and render-clients
without any deeper knowledge of the GPU that is used. Moreover, it
allows to move objects between GPUs and implement complex
display-servers that don't do any rendering on their own. See its
man-page for more information.
EXAMPLES
This section includes examples for basic memory-management tasks.
Dumb-Buffers
This examples shows how to create a dumb-buffer via the generic DRM
API. This is driver-independent (as long as the driver supports
dumb-buffers) and provides memory-mapped buffers that can be used for
scanout. This example creates a full-HD 1920x1080 buffer with 32
bits-per-pixel and a color-depth of 24 bits. The buffer is then bound
to a framebuffer which can be used for scanout with the KMS API (see
drm-kms(7)).
struct drm_mode_create_dumb creq;
struct drm_mode_destroy_dumb dreq;
struct drm_mode_map_dumb mreq;
uint32_t fb;
int ret;
void *map;
/* create dumb buffer */
memset(&creq, 0, sizeof(creq));
creq.width = 1920;
creq.height = 1080;
creq.bpp = 32;
ret = drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &creq);
if (ret < 0) {
/* buffer creation failed; see "errno" for more error codes */
...
}
/* creq.pitch, creq.handle and creq.size are filled by this ioctl with
* the requested values and can be used now. */
/* create framebuffer object for the dumb-buffer */
ret = drmModeAddFB(fd, 1920, 1080, 24, 32, creq.pitch, creq.handle, &fb);
if (ret) {
/* frame buffer creation failed; see "errno" */
...
}
/* the framebuffer "fb" can now used for scanout with KMS */
/* prepare buffer for memory mapping */
memset(&mreq, 0, sizeof(mreq));
mreq.handle = creq.handle;
ret = drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &mreq);
if (ret) {
/* DRM buffer preparation failed; see "errno" */
...
}
/* mreq.offset now contains the new offset that can be used with mmap() */
/* perform actual memory mapping */
map = mmap(0, creq.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, mreq.offset);
if (map == MAP_FAILED) {
/* memory-mapping failed; see "errno" */
...
}
/* clear the framebuffer to 0 */
memset(map, 0, creq.size);
REPORTING BUGS
Bugs in this manual should be reported to
https://gitlab.freedesktop.org/mesa/drm/-/issues
SEE ALSO
drm(7), drm-kms(7), drm-prime(7), drmAvailable(3), drmOpen(3),
drm-intel(7), drm-radeon(7), drm-nouveau(7)
September 2012 DRM-MEMORY(7)