240 lines
11 KiB
Groff
240 lines
11 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "DRM-KMS" 7 "September 2012" "" "Direct Rendering Manager"
|
|
.SH NAME
|
|
drm-kms \- Kernel Mode-Setting
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fB#include <xf86drm.h>\fP
|
|
.sp
|
|
\fB#include <xf86drmMode.h>\fP
|
|
.SH DESCRIPTION
|
|
.sp
|
|
Each DRM device provides access to manage which monitors and displays are
|
|
currently used and what frames to be displayed. This task is called \fIKernel
|
|
Mode\-Setting\fP (KMS). Historically, this was done in user\-space and called
|
|
\fIUser\-space Mode\-Setting\fP (UMS). Almost all open\-source drivers now provide the
|
|
KMS kernel API to do this in the kernel, however, many non\-open\-source binary
|
|
drivers from different vendors still do not support this. You can use
|
|
\fBdrmModeSettingSupported\fP(3) to check whether your driver supports this. To
|
|
understand how KMS works, we need to introduce 5 objects: \fICRTCs\fP, \fIPlanes\fP,
|
|
\fIEncoders\fP, \fIConnectors\fP and \fIFramebuffers\fP\&.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B CRTCs
|
|
A \fICRTC\fP short for \fICRT Controller\fP is an abstraction representing a part of
|
|
the chip that contains a pointer to a scanout buffer. Therefore, the number
|
|
of CRTCs available determines how many independent scanout buffers can be
|
|
active at any given time. The CRTC structure contains several fields to
|
|
support this: a pointer to some video memory (abstracted as a frame\-buffer
|
|
object), a list of driven connectors, a display mode and an (x, y) offset
|
|
into the video memory to support panning or configurations where one piece
|
|
of video memory spans multiple CRTCs. A CRTC is the central point where
|
|
configuration of displays happens. You select which objects to use, which
|
|
modes and which parameters and then configure each CRTC via
|
|
\fBdrmModeCrtcSet\fP(3) to drive the display devices.
|
|
.TP
|
|
.B Planes
|
|
A \fIplane\fP respresents an image source that can be blended with or overlayed
|
|
on top of a CRTC during the scanout process. Planes are associated with a
|
|
frame\-buffer to crop a portion of the image memory (source) and optionally
|
|
scale it to a destination size. The result is then blended with or overlayed
|
|
on top of a CRTC. Planes are not provided by all hardware and the number of
|
|
available planes is limited. If planes are not available or if not enough
|
|
planes are available, the user should fall back to normal software blending
|
|
(via GPU or CPU).
|
|
.TP
|
|
.B Encoders
|
|
An \fIencoder\fP takes pixel data from a CRTC and converts it to a format
|
|
suitable for any attached connectors. On some devices, it may be possible to
|
|
have a CRTC send data to more than one encoder. In that case, both encoders
|
|
would receive data from the same scanout buffer, resulting in a \fIcloned\fP
|
|
display configuration across the connectors attached to each encoder.
|
|
.TP
|
|
.B Connectors
|
|
A \fIconnector\fP is the final destination of pixel\-data on a device, and
|
|
usually connects directly to an external display device like a monitor or
|
|
laptop panel. A connector can only be attached to one encoder at a time. The
|
|
connector is also the structure where information about the attached display
|
|
is kept, so it contains fields for display data, \fIEDID\fP data, \fIDPMS\fP and
|
|
\fIconnection status\fP, and information about modes supported on the attached
|
|
displays.
|
|
.TP
|
|
.B Framebuffers
|
|
\fIFramebuffers\fP are abstract memory objects that provide a source of pixel
|
|
data to scanout to a CRTC. Applications explicitly request the creation of
|
|
framebuffers and can control their behavior. Framebuffers rely on the
|
|
underneath memory manager for low\-level memory operations. When creating a
|
|
framebuffer, applications pass a memory handle through the API which is used
|
|
as backing storage. The framebuffer itself is only an abstract object with
|
|
no data. It just refers to memory buffers that must be created with the
|
|
\fBdrm\-memory\fP(7) API.
|
|
.UNINDENT
|
|
.SS Mode\-Setting
|
|
.sp
|
|
Before mode\-setting can be performed, an application needs to call
|
|
\fBdrmSetMaster\fP(3) to become \fIDRM\-Master\fP\&. It then has exclusive access to
|
|
the KMS API. A call to \fBdrmModeGetResources\fP(3) returns a list of \fICRTCs\fP,
|
|
\fIConnectors\fP, \fIEncoders\fP and \fIPlanes\fP\&.
|
|
.sp
|
|
Normal procedure now includes: First, you select which connectors you want to
|
|
use. Users are mostly interested in which monitor or display\-panel is active so
|
|
you need to make sure to arrange them in the correct logical order and select
|
|
the correct ones to use. For each connector, you need to find a CRTC to drive
|
|
this connector. If you want to clone output to two or more connectors, you may
|
|
use a single CRTC for all cloned connectors (if the hardware supports this). To
|
|
find a suitable CRTC, you need to iterate over the list of encoders that are
|
|
available for each connector. Each encoder contains a list of CRTCs that it can
|
|
work with and you simply select one of these CRTCs. If you later program the
|
|
CRTC to control a connector, it automatically selects the best encoder.
|
|
However, this procedure is needed so your CRTC has at least one working encoder
|
|
for the selected connector. See the \fIExamples\fP section below for more
|
|
information.
|
|
.sp
|
|
All valid modes for a connector can be retrieved with a call to
|
|
\fBdrmModeGetConnector\fP(3) You need to select the mode you want to use and save it.
|
|
The first mode in the list is the default mode with the highest resolution
|
|
possible and often a suitable choice.
|
|
.sp
|
|
After you have a working connector+CRTC+mode combination, you need to create a
|
|
framebuffer that is used for scanout. Memory buffer allocation is
|
|
driver\-dependent and described in \fBdrm\-memory\fP(7). You need to create a
|
|
buffer big enough for your selected mode. Now you can create a framebuffer
|
|
object that uses your memory\-buffer as scanout buffer. You can do this with
|
|
\fBdrmModeAddFB\fP(3) and \fBdrmModeAddFB2\fP(3).
|
|
.sp
|
|
As a last step, you want to program your CRTC to drive your selected connector.
|
|
You can do this with a call to \fBdrmModeSetCrtc\fP(3).
|
|
.SS Page\-Flipping
|
|
.sp
|
|
A call to \fBdrmModeSetCrtc\fP(3) is executed immediately and forces the CRTC
|
|
to use the new scanout buffer. If you want smooth\-transitions without tearing,
|
|
you probably use double\-buffering. You need to create one framebuffer object
|
|
for each buffer you use. You can then call \fBdrmModeSetCrtc\fP(3) on the next
|
|
buffer to flip. If you want to synchronize your flips with \fIvertical\-blanks\fP,
|
|
you can use \fBdrmModePageFlip\fP(3) which schedules your page\-flip for the
|
|
next \fIvblank\fP\&.
|
|
.SS Planes
|
|
.sp
|
|
Planes are controlled independently from CRTCs. That is, a call to
|
|
\fBdrmModeSetCrtc\fP(3) does not affect planes. Instead, you need to call
|
|
\fBdrmModeSetPlane\fP(3) to configure a plane. This requires the plane ID, a
|
|
CRTC, a framebuffer and offsets into the plane\-framebuffer and the
|
|
CRTC\-framebuffer. The CRTC then blends the content from the plane over the CRTC
|
|
framebuffer buffer during scanout. As this does not involve any
|
|
software\-blending, it is way faster than traditional blending. However, plane
|
|
resources are limited. See \fBdrmModeGetPlaneResources\fP(3) for more
|
|
information.
|
|
.SS Cursors
|
|
.sp
|
|
Similar to planes, many hardware also supports cursors. A cursor is a very
|
|
small buffer with an image that is blended over the CRTC framebuffer. You can
|
|
set a different cursor for each CRTC with \fBdrmModeSetCursor\fP(3) and move it
|
|
on the screen with \fBdrmModeMoveCursor\fP(3). This allows to move the cursor
|
|
on the screen without rerendering. If no hardware cursors are supported, you
|
|
need to rerender for each frame the cursor is moved.
|
|
.SH EXAMPLES
|
|
.sp
|
|
Some examples of how basic mode\-setting can be done. See the man\-page of each
|
|
DRM function for more information.
|
|
.SS CRTC/Encoder Selection
|
|
.sp
|
|
If you retrieved all display configuration information via
|
|
\fBdrmModeGetResources\fP(3) as \fBdrmModeRes *res\fP, selected a connector from
|
|
the list in \fBres\->connectors\fP and retrieved the connector\-information as
|
|
\fBdrmModeConnector *conn\fP via \fBdrmModeGetConnector\fP(3) then this example
|
|
shows, how you can find a suitable CRTC id to drive this connector. This
|
|
function takes a file\-descriptor to the DRM device (see \fBdrmOpen\fP(3)) as
|
|
\fBfd\fP, a pointer to the retrieved resources as \fBres\fP and a pointer to the
|
|
selected connector as \fBconn\fP\&. It returns an integer smaller than 0 on
|
|
failure, otherwise, a valid CRTC id is returned.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
|
|
{
|
|
drmModeEncoder *enc;
|
|
unsigned int i, j;
|
|
|
|
/* iterate all encoders of this connector */
|
|
for (i = 0; i < conn\->count_encoders; ++i) {
|
|
enc = drmModeGetEncoder(fd, conn\->encoders[i]);
|
|
if (!enc) {
|
|
/* cannot retrieve encoder, ignoring... */
|
|
continue;
|
|
}
|
|
|
|
/* iterate all global CRTCs */
|
|
for (j = 0; j < res\->count_crtcs; ++j) {
|
|
/* check whether this CRTC works with the encoder */
|
|
if (!(enc\->possible_crtcs & (1 << j)))
|
|
continue;
|
|
|
|
|
|
/* Here you need to check that no other connector
|
|
* currently uses the CRTC with id \(dqcrtc\(dq. If you intend
|
|
* to drive one connector only, then you can skip this
|
|
* step. Otherwise, simply scan your list of configured
|
|
* connectors and CRTCs whether this CRTC is already
|
|
* used. If it is, then simply continue the search here. */
|
|
if (res\->crtcs[j] \(dqis unused\(dq) {
|
|
drmModeFreeEncoder(enc);
|
|
return res\->crtcs[j];
|
|
}
|
|
}
|
|
|
|
drmModeFreeEncoder(enc);
|
|
}
|
|
|
|
/* cannot find a suitable CRTC */
|
|
return \-ENOENT;
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH REPORTING BUGS
|
|
.sp
|
|
Bugs in this manual should be reported to
|
|
\fI\%https://gitlab.freedesktop.org/mesa/drm/\-/issues\fP
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fBdrm\fP(7), \fBdrm\-memory\fP(7), \fBdrmModeGetResources\fP(3),
|
|
\fBdrmModeGetConnector\fP(3), \fBdrmModeGetEncoder\fP(3),
|
|
\fBdrmModeGetCrtc\fP(3), \fBdrmModeSetCrtc\fP(3), \fBdrmModeGetFB\fP(3),
|
|
\fBdrmModeAddFB\fP(3), \fBdrmModeAddFB2\fP(3), \fBdrmModeRmFB\fP(3),
|
|
\fBdrmModePageFlip\fP(3), \fBdrmModeGetPlaneResources\fP(3),
|
|
\fBdrmModeGetPlane\fP(3), \fBdrmModeSetPlane\fP(3), \fBdrmModeSetCursor\fP(3),
|
|
\fBdrmModeMoveCursor\fP(3), \fBdrmSetMaster\fP(3), \fBdrmAvailable\fP(3),
|
|
\fBdrmCheckModesettingSupported\fP(3), \fBdrmOpen\fP(3)
|
|
.\" Generated by docutils manpage writer.
|
|
.
|