Package: libdrm-dev
Version: 2.4.123-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:30: style: .TH missing fourth argument; consider
package/project name and version (e.g., "groff 1.23.0")
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages libdrm-dev depends on:
ii libdrm-amdgpu1 2.4.123-1
ii libdrm-intel1 2.4.123-1
ii libdrm-nouveau2 2.4.123-1
ii libdrm-radeon1 2.4.123-1
ii libdrm2 2.4.123-1
ii libpciaccess-dev 0.17-3+b3
libdrm-dev recommends no packages.
libdrm-dev suggests no packages.
-- no debconf information
Input file is drm-kms.7
Output from "mandoc -T lint drm-kms.7": (shortened list)
1 input text line longer than 80 bytes: A \fICRTC\fP short f...
1 input text line longer than 80 bytes: buffer to flip. If y...
1 input text line longer than 80 bytes: the KMS API. A call ...
1 input text line longer than 80 bytes: understand how KMS w...
5 skipping paragraph macro: sp after SH
5 skipping paragraph macro: sp after SS
1 whitespace at end of input line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Output from "test-groff -mandoc -t -ww -z drm-kms.7": (shortened list)
1 trailing space in the line
Remove trailing space with: sed -e 's/ *$//'
-.-.
Show if generated from reStructuredText
Who is actually generating this man page? Debian or upstream?
Is the generating software out of date?
1:.\" Man page generated from reStructuredText.
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
N.B.
The number of lines affected can be too large to be in a patch.
41:currently used and what frames to be displayed. This task is called \fIKernel
42:Mode\-Setting\fP (KMS). Historically, this was done in user\-space and called
43:\fIUser\-space Mode\-Setting\fP (UMS). Almost all open\-source drivers now
provide the
45:drivers from different vendors still do not support this. You can use
46:\fBdrmModeSettingSupported\fP(3) to check whether your driver supports this.
To
53:the chip that contains a pointer to a scanout buffer. Therefore, the number
55:active at any given time. The CRTC structure contains several fields to
59:of video memory spans multiple CRTCs. A CRTC is the central point where
60:configuration of displays happens. You select which objects to use, which
66:on top of a CRTC during the scanout process. Planes are associated with a
68:scale it to a destination size. The result is then blended with or overlayed
69:on top of a CRTC. Planes are not provided by all hardware and the number of
70:available planes is limited. If planes are not available or if not enough
76:suitable for any attached connectors. On some devices, it may be possible to
77:have a CRTC send data to more than one encoder. In that case, both encoders
84:laptop panel. A connector can only be attached to one encoder at a time. The
92:data to scanout to a CRTC. Applications explicitly request the creation of
93:framebuffers and can control their behavior. Framebuffers rely on the
94:underneath memory manager for low\-level memory operations. When creating a
96:as backing storage. The framebuffer itself is only an abstract object with
97:no data. It just refers to memory buffers that must be created with the
103:\fBdrmSetMaster\fP(3) to become \fIDRM\-Master\fP\&. It then has exclusive
access to
104:the KMS API. A call to \fBdrmModeGetResources\fP(3) returns a list of
\fICRTCs\fP,
108:use. Users are mostly interested in which monitor or display\-panel is
active so
110:the correct ones to use. For each connector, you need to find a CRTC to
drive
111:this connector. If you want to clone output to two or more connectors, you
may
112:use a single CRTC for all cloned connectors (if the hardware supports
this). To
114:available for each connector. Each encoder contains a list of CRTCs that it
can
115:work with and you simply select one of these CRTCs. If you later program the
118:for the selected connector. See the \fIExamples\fP section below for more
127:framebuffer that is used for scanout. Memory buffer allocation is
128:driver\-dependent and described in \fBdrm\-memory\fP(7). You need to create
a
129:buffer big enough for your selected mode. Now you can create a framebuffer
130:object that uses your memory\-buffer as scanout buffer. You can do this with
138:to use the new scanout buffer. If you want smooth\-transitions without
tearing,
139:you probably use double\-buffering. You need to create one framebuffer
object
140:for each buffer you use. You can then call \fBdrmModeSetCrtc\fP(3) on the
next
141:buffer to flip. If you want to synchronize your flips with
\fIvertical\-blanks\fP,
146:Planes are controlled independently from CRTCs. That is, a call to
147:\fBdrmModeSetCrtc\fP(3) does not affect planes. Instead, you need to call
148:\fBdrmModeSetPlane\fP(3) to configure a plane. This requires the plane ID, a
150:CRTC\-framebuffer. The CRTC then blends the content from the plane over the
CRTC
151:framebuffer buffer during scanout. As this does not involve any
152:software\-blending, it is way faster than traditional blending. However,
plane
153:resources are limited. See \fBdrmModeGetPlaneResources\fP(3) for more
157:Similar to planes, many hardware also supports cursors. A cursor is a very
158:small buffer with an image that is blended over the CRTC framebuffer. You
can
160:on the screen with \fBdrmModeMoveCursor\fP(3). This allows to move the
cursor
161:on the screen without rerendering. If no hardware cursors are supported, you
165:Some examples of how basic mode\-setting can be done. See the man\-page of
each
173:shows, how you can find a suitable CRTC id to drive this connector. This
176:selected connector as \fBconn\fP\&. It returns an integer smaller than 0 on
191: /* cannot retrieve encoder, ignoring... */
203: * currently uses the CRTC with id \(dqcrtc\(dq. If you intend
205: * step. Otherwise, simply scan your list of configured
207: * used. If it is, then simply continue the search here. */
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 43, length 86
\fIUser\-space Mode\-Setting\fP (UMS). Almost all open\-source drivers now
provide the
Line 47, length 84
understand how KMS works, we need to introduce 5 objects: \fICRTCs\fP,
\fIPlanes\fP,
Line 52, length 84
A \fICRTC\fP short for \fICRT Controller\fP is an abstraction representing a
part of
Line 103, length 84
\fBdrmSetMaster\fP(3) to become \fIDRM\-Master\fP\&. It then has exclusive
access to
Line 104, length 82
the KMS API. A call to \fBdrmModeGetResources\fP(3) returns a list of
\fICRTCs\fP,
Line 122, length 85
\fBdrmModeGetConnector\fP(3) You need to select the mode you want to use and
save it.
Line 141, length 82
buffer to flip. If you want to synchronize your flips with
\fIvertical\-blanks\fP,
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
drm-kms.7:57:object), a list of driven connectors, a display mode and an (x, y)
offset
drm-kms.7:112:use a single CRTC for all cloned connectors (if the hardware
supports this). To
drm-kms.7:174:function takes a file\-descriptor to the DRM device (see
\fBdrmOpen\fP(3)) as
-.-.
No need for "\&" to be in front of a period (.),
if there is a character in front of it
48:\fIEncoders\fP, \fIConnectors\fP and \fIFramebuffers\fP\&.
103:\fBdrmSetMaster\fP(3) to become \fIDRM\-Master\fP\&. It then has exclusive
access to
105:\fIConnectors\fP, \fIEncoders\fP and \fIPlanes\fP\&.
143:next \fIvblank\fP\&.
176:selected connector as \fBconn\fP\&. It returns an integer smaller than 0 on
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
30:.TH "DRM-KMS" "7" "September 2012" "" "Direct Rendering Manager"
-.-.
Remove excessive "\&" when it has no functional purpose.
48:\fIEncoders\fP, \fIConnectors\fP and \fIFramebuffers\fP\&.
103:\fBdrmSetMaster\fP(3) to become \fIDRM\-Master\fP\&. It then has exclusive
access to
105:\fIConnectors\fP, \fIEncoders\fP and \fIPlanes\fP\&.
143:next \fIvblank\fP\&.
176:selected connector as \fBconn\fP\&. It returns an integer smaller than 0 on
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:30: style: .TH missing fourth argument; consider
package/project name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:226: style: 1 leading space(s) on input line
troff:<stdin>:226: warning: trailing space in the line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:30: style: .TH missing fourth argument; consider
package/project name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:226: style: 1 leading space(s) on input line
troff:<stdin>:226: warning: trailing space in the line
-.-.
Spelling (codespel):
overlayed ==> overlaid
respresents ==> represents
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- drm-kms.7 2025-02-20 20:56:20.183616499 +0000
+++ drm-kms.7.new 2025-02-20 21:34:21.443617831 +0000
@@ -27,34 +27,38 @@ level margin: \\n[rst2man-indent\\n[rst2
.\" 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"
+.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
+\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\&.
+\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
+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
+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
@@ -62,11 +66,12 @@ modes and which parameters and then conf
\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
+A \fIplane\fP represents an image source that can be blended with or overlaid
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
+scale it to a destination size. The result is then blended with or overlaid
+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).
@@ -98,19 +103,20 @@ no data. It just refers to memory buffer
\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\&.
+\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
+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.
@@ -119,7 +125,8 @@ for the selected connector. See the \fIE
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.
+\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
@@ -133,16 +140,15 @@ object that uses your memory\-buffer as
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,
+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\&.
+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
@@ -153,7 +159,6 @@ software\-blending, it is way faster tha
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
@@ -161,19 +166,19 @@ on the screen with \fBdrmModeMoveCursor\
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
+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
@@ -221,11 +226,10 @@ static int modeset_find_crtc(int fd, drm
.UNINDENT
.UNINDENT
.SH REPORTING BUGS
-.sp
Bugs in this manual should be reported to
- <https://gitlab.freedesktop.org/mesa/drm/\-/issues>
+.ti \n(INu+2m
+<https://gitlab.freedesktop.org/mesa/drm/\-/issues>
.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),
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
