* [PATCH libdrm 0/4] Manpages for libdrm
@ 2012-09-28 21:44 David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 1/4] man: convert manpages to XML instead of plain troff David Herrmann
` (4 more replies)
0 siblings, 5 replies; 8+ messages in thread
From: David Herrmann @ 2012-09-28 21:44 UTC (permalink / raw)
To: dri-devel
Hi
This is revision 2 of the manpages for libdrm. I converted everything to docbook
XML. This makes it easier to write them (troff is really hard to read) and
allows us to integrate it into other documentation.
Other than that I only fixed typos and the small corrections you guys mentioned.
Thanks for reviewing!
Regards
David
David Herrmann (4):
man: convert manpages to XML instead of plain troff
man: add drm.7 overview page
man: add drm-kms overview page
man: add drm-memory overview page
.gitignore | 4 +
configure.ac | 24 +--
man/Makefile.am | 65 +++++--
man/drm-kms.xml | 342 +++++++++++++++++++++++++++++++++++
man/drm-memory.xml | 430 ++++++++++++++++++++++++++++++++++++++++++++
man/drm.xml | 137 ++++++++++++++
man/drmAvailable.man | 25 ---
man/drmAvailable.xml | 75 ++++++++
man/drmHandleEvent.man | 45 -----
man/drmHandleEvent.xml | 102 +++++++++++
man/drmModeGetResources.man | 79 --------
man/drmModeGetResources.xml | 139 ++++++++++++++
12 files changed, 1286 insertions(+), 181 deletions(-)
create mode 100644 man/drm-kms.xml
create mode 100644 man/drm-memory.xml
create mode 100644 man/drm.xml
delete mode 100644 man/drmAvailable.man
create mode 100644 man/drmAvailable.xml
delete mode 100644 man/drmHandleEvent.man
create mode 100644 man/drmHandleEvent.xml
delete mode 100644 man/drmModeGetResources.man
create mode 100644 man/drmModeGetResources.xml
--
1.7.12.1
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH libdrm 1/4] man: convert manpages to XML instead of plain troff
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
@ 2012-09-28 21:44 ` David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 2/4] man: add drm.7 overview page David Herrmann
` (3 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: David Herrmann @ 2012-09-28 21:44 UTC (permalink / raw)
To: dri-devel
If we want to use the manpages in external documentation other than normal
manpages, we should rather use XML. Furthermore, almost no-one knows troff
today, anyway, and XML allows others to easily add more pages without
having to learn troff.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
---
.gitignore | 4 ++
configure.ac | 24 +-------
man/Makefile.am | 58 ++++++++++++++----
man/drmAvailable.man | 25 --------
man/drmAvailable.xml | 75 ++++++++++++++++++++++++
man/drmHandleEvent.man | 45 --------------
man/drmHandleEvent.xml | 102 ++++++++++++++++++++++++++++++++
man/drmModeGetResources.man | 79 -------------------------
man/drmModeGetResources.xml | 139 ++++++++++++++++++++++++++++++++++++++++++++
9 files changed, 370 insertions(+), 181 deletions(-)
delete mode 100644 man/drmAvailable.man
create mode 100644 man/drmAvailable.xml
delete mode 100644 man/drmHandleEvent.man
create mode 100644 man/drmHandleEvent.xml
delete mode 100644 man/drmModeGetResources.man
create mode 100644 man/drmModeGetResources.xml
diff --git a/.gitignore b/.gitignore
index 243457e..d297f94 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,9 @@
bsd-core/*/@
bsd-core/*/machine
+*.1
+*.3
+*.5
+*.7
*.flags
*.ko
*.ko.cmd
diff --git a/configure.ac b/configure.ac
index 290362c..7fd7f11 100644
--- a/configure.ac
+++ b/configure.ac
@@ -35,27 +35,6 @@ AM_MAINTAINER_MODE([enable])
# Enable quiet compiles on automake 1.11.
m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
-if test x$LIB_MAN_SUFFIX = x ; then
- LIB_MAN_SUFFIX=3
-fi
-if test x$LIB_MAN_DIR = x ; then
- LIB_MAN_DIR='$(mandir)/man$(LIB_MAN_SUFFIX)'
-fi
-AC_SUBST([LIB_MAN_SUFFIX])
-AC_SUBST([LIB_MAN_DIR])
-
-MAN_SUBSTS="\
- -e 's|__vendorversion__|\"\$(PACKAGE_STRING)\" |' \
- -e 's|__projectroot__|\$(prefix)|g' \
- -e 's|__apploaddir__|\$(appdefaultdir)|g' \
- -e 's|__appmansuffix__|\$(APP_MAN_SUFFIX)|g' \
- -e 's|__drivermansuffix__|\$(DRIVER_MAN_SUFFIX)|g' \
- -e 's|__adminmansuffix__|\$(ADMIN_MAN_SUFFIX)|g' \
- -e 's|__libmansuffix__|\$(LIB_MAN_SUFFIX)|g' \
- -e 's|__miscmansuffix__|\$(MISC_MAN_SUFFIX)|g' \
- -e 's|__filemansuffix__|\$(FILE_MAN_SUFFIX)|g'"
-AC_SUBST([MAN_SUBSTS])
-
# Check for programs
AC_PROG_CC
@@ -235,6 +214,9 @@ if test "x$HAVE_LIBUDEV" = xyes; then
fi
AM_CONDITIONAL(HAVE_LIBUDEV, [test "x$HAVE_LIBUDEV" = xyes])
+AC_PATH_PROG(XSLTPROC, xsltproc)
+AM_CONDITIONAL([HAVE_XSLTPROC], [test "x$XSLTPROC" != "x"])
+
if test "x$INTEL" != "xno" -o "x$RADEON" != "xno" -o "x$NOUVEAU" != "xno" -o "x$OMAP" != "xno"; then
# Check for atomic intrinsics
AC_CACHE_CHECK([for native atomic primitives], drm_cv_atomic_primitives,
diff --git a/man/Makefile.am b/man/Makefile.am
index 73068e6..3030e5f 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,11 +1,47 @@
-libmandir = $(LIB_MAN_DIR)
-libman_PRE = drmAvailable.man \
- drmHandleEvent.man \
- drmModeGetResources.man
-libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@)
-EXTRA_DIST = $(libman_PRE)
-CLEANFILE = $(libman_DATA)
-SUFFIXES = .$(LIB_MAN_SUFFIX) .man
-
-.man.$(LIB_MAN_SUFFIX):
- $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
+#
+# This generates man-pages out of the Docbook XML files. Simply add your files
+# to the $MANPAGES array. If aliases are created, please add them to the
+# MANPAGES_ALIASES array so they get installed correctly.
+#
+
+MANPAGES = \
+ drmAvailable.3 \
+ drmHandleEvent.3 \
+ drmModeGetResources.3
+MANPAGES_ALIASES =
+
+XML_FILES = \
+ ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,$(MANPAGES)}}}}
+CLEANFILES =
+EXTRA_DIST =
+man_MANS =
+
+if HAVE_XSLTPROC
+
+CLEANFILES += $(MANPAGES) $(MANPAGES_ALIASES)
+EXTRA_DIST += $(MANPAGES) $(MANPAGES_ALIASES) $(XML_FILES)
+man_MANS += $(MANPAGES) $(MANPAGES_ALIASES)
+
+XSLTPROC_FLAGS = \
+ --stringparam man.authors.section.enabled 0 \
+ --stringparam man.copyright.section.enabled 0 \
+ --stringparam funcsynopsis.style ansi \
+ --stringparam man.output.quietly 1
+
+XSLTPROC_PROCESS_MAN = \
+ $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
+ $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+%.1: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.3: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.5: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.7: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+endif # HAVE_XSLTPROC
diff --git a/man/drmAvailable.man b/man/drmAvailable.man
deleted file mode 100644
index e1bb8dc..0000000
--- a/man/drmAvailable.man
+++ /dev/null
@@ -1,25 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmAvailable __drivermansuffix__ __vendorversion__
-.SH NAME
-drmAvailable \- determine whether a DRM kernel driver has been loaded
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drm.h>"
-
-.B "int drmAvailable(void);"
-.fi
-.SH DESCRIPTION
-This function allows the caller to determine whether a kernel DRM driver is
-loaded.
-
-.SH RETURN VALUE
-If a DRM driver is currently loaded, this function returns 1. Otherwise 0
-is returned.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmOpen(__libmansuffix__)
diff --git a/man/drmAvailable.xml b/man/drmAvailable.xml
new file mode 100644
index 0000000..55bef94
--- /dev/null
+++ b/man/drmAvailable.xml
@@ -0,0 +1,75 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmAvailable">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmAvailable</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmAvailable</refname>
+ <refpurpose>determine whether a DRM kernel driver has been
+ loaded</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>drmAvailable</function></funcdef>
+ <paramdef>void</paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmAvailable</function> allows the caller to determine
+ whether a kernel DRM driver is loaded.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmAvailable</function> returns 1 if a DRM driver is
+ currently loaded. Otherwise 0 is returned.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/man/drmHandleEvent.man b/man/drmHandleEvent.man
deleted file mode 100644
index b98f417..0000000
--- a/man/drmHandleEvent.man
+++ /dev/null
@@ -1,45 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmHandleEvent __drivermansuffix__ __vendorversion__
-.SH NAME
-drmHandleEvent \- read and process pending DRM events
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drm.h>"
-
-.B "typedef struct _drmEventContext {"
-.BI " int version;"
-.BI " void (*vblank_handler)(int fd,"
-.BI " unsigned int sequence,"
-.BI " unsigned int tv_sec,"
-.BI " unsigned int tv_usec,"
-.BI " void *user_data);"
-.BI " void (*page_flip_handler)(int fd,"
-.BI " unsigned int sequence,"
-.BI " unsigned int tv_sec,"
-.BI " unsigned int tv_usec,"
-.BI " void *user_data);"
-.B "} drmEventContext, *drmEventContextPtr;"
-
-.B "int drmHandleEvent(int fd, drmEventContextPtr evctx);"
-.fi
-.SH DESCRIPTION
-This function will process outstanding DRM events on
-.I fd
-, which must be an open DRM device. This function should be called after
-the DRM file descriptor has polled readable; it will read the events and
-use the passed-in
-.I evctx
-structure to call function pointers with the parameters noted above.
-
-.SH RETURN VALUE
-Returns 0 on success, or if there is no data to read from the file descriptor.
-Returns -1 if the read on the file descriptor fails or returns less than a
-full event record.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmModePageFlip(__libmansuffix__), drmWaitVBlank(__libmansuffix__)
diff --git a/man/drmHandleEvent.xml b/man/drmHandleEvent.xml
new file mode 100644
index 0000000..b1006e5
--- /dev/null
+++ b/man/drmHandleEvent.xml
@@ -0,0 +1,102 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmHandleEvent">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmHandleEvent</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmHandleEvent</refname>
+ <refpurpose>read and process pending DRM events</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>drmHandleEvent</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>drmEventContextPtr <parameter>evctx</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmHandleEvent</function> processes outstanding DRM events
+ on the DRM file-descriptor passed as <parameter>fd</parameter>. This
+ function should be called after the DRM file-descriptor has polled
+ readable; it will read the events and use the passed-in
+ <parameter>evctx</parameter> structure to call function pointers
+ with the parameters noted below:
+
+<programlisting>
+typedef struct _drmEventContext {
+ int version;
+ void (*vblank_handler) (int fd,
+ unsigned int sequence,
+ unsigned int tv_sec,
+ unsigned int tv_usec,
+ void *user_data)
+ void (*page_flip_handler) (int fd,
+ unsigned int sequence,
+ unsigned int tv_sec,
+ unsigned int tv_usec,
+ void *user_data)
+} drmEventContext, *drmEventContextPtr;
+</programlisting>
+
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmHandleEvent</function> returns <literal>0</literal> on
+ success, or if there is no data to read from the file-descriptor.
+ Returns <literal>-1</literal> if the read on the file-descriptor fails
+ or returns less than a full event record.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmWaitVBlank</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/man/drmModeGetResources.man b/man/drmModeGetResources.man
deleted file mode 100644
index 369bf7d..0000000
--- a/man/drmModeGetResources.man
+++ /dev/null
@@ -1,79 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmModeGetResources __drivermansuffix__ __vendorversion__
-.SH NAME
-drmModeGetResources \- retrieve current display configuration information
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drmMode.h>"
-
-.BI "typedef struct _drmModeRes {"
-
-.BI " int count_fbs;"
-.BI " uint32_t *fbs;"
-
-.BI " int count_crtcs;"
-.BI " uint32_t *crtcs;"
-
-.BI " int count_connectors;"
-.BI " uint32_t *connectors;"
-
-.BI " int count_encoders;"
-.BI " uint32_t *encoders;"
-
-.BI " uint32_t min_width, max_width;"
-.BI " uint32_t min_height, max_height;"
-.B "} drmModeRes, *drmModeResPtr;"
-
-.B "drmModeResPtr drmModeGetResources(int fd);"
-.fi
-.SH DESCRIPTION
-This function will allocate, populate, and return a drmModeRes structure
-containing information about the current display configuration.
-
-The
-.I count_fbs
-and
-.I fbs
-fields indicate the number of currently allocated framebuffer objects (i.e.
-objects that can be attached to a given CRTC or sprite for display).
-
-The
-.I count_crtcs
-and
-.I crtcs
-fields list the available CRTCs in the configuration. A CRTC is simply
-an object that can scan out a framebuffer to a display sink, and contains
-mode timing and relative position information. CRTCs drive encoders, which
-are responsible for converting the pixel stream into a specific display
-protocol (e.g. MIPI or HDMI).
-
-The
-.I count_connectors
-and
-.I connectors
-fields list the available physical connectors on the system. Note that
-some of these may not be exposed from the chassis (e.g. LVDS or eDP).
-Connectors are attached to encoders and contain information about the
-attached display sink (e.g. width and height in mm, subpixel ordering, and
-various other properties).
-
-The
-.I count_encoders
-and
-.I encoders
-fields list the available encoders on the device. Each encoder may be
-associated with a CRTC, and may be used to drive a particular encoder.
-
-The min and max height fields indicate the maximum size of a framebuffer
-for this device (i.e. the scanout size limit).
-
-.SH RETURN VALUE
-Returns a drmModeRes structure pointer on success, 0 on failure.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmModeGetFB(__libmansuffix__), drmModeAddFB(__libmansuffix__), drmModeAddFB2(__libmansuffix__), drmModeRmFB(__libmansuffix__), drmModeDirtyFB(__libmansuffix__), drmModeGetCrtc(__libmansuffix__), drmModeSetCrtc(__libmansuffix__), drmModeGetEncoder(__libmansuffix__), drmModeGetConnector(__libmansuffix__)
diff --git a/man/drmModeGetResources.xml b/man/drmModeGetResources.xml
new file mode 100644
index 0000000..2f5e8c2
--- /dev/null
+++ b/man/drmModeGetResources.xml
@@ -0,0 +1,139 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmModeGetResources">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmModeGetResources</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmModeGetResources</refname>
+ <refpurpose>retrieve current display configuration information</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <xf86drmMode.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>drmModeResPtr <function>drmModeGetResources</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmModeGetResources</function> allocates, populates, and
+ returns a <structname>drmModeRes</structname> structure containing
+ information about the current display configuration. The structure
+ contains the following fields:
+
+<programlisting>
+typedef struct _drmModeRes {
+ int count_fbs;
+ uint32_t *fbs;
+
+ int count_crtcs;
+ uint32_t *crtcs;
+
+ int count_connectors;
+ uint32_t *connectors;
+
+ int count_encoders;
+ uint32_t *encoders;
+
+ uint32_t min_width, max_width;
+ uint32_t min_height, max_height;
+} drmModeRes, *drmModeResPtr;
+</programlisting>
+
+ </para>
+
+ <para>The <structfield>count_fbs</structfield> and
+ <structfield>fbs</structfield> fields indicate the number of currently
+ allocated framebuffer objects (i.e., objects that can be attached to
+ a given CRTC or sprite for display).</para>
+
+ <para>The <structfield>count_crtcs</structfield> and
+ <structfield>crtcs</structfield> fields list the available CRTCs in
+ the configuration. A CRTC is simply an object that can scan out a
+ framebuffer to a display sink, and contains mode timing and relative
+ position information. CRTCs drive encoders, which are responsible for
+ converting the pixel stream into a specific display protocol (e.g.,
+ MIPI or HDMI).</para>
+
+ <para>The <structfield>count_connectors</structfield> and
+ <structfield>connectors</structfield> fields list the available
+ physical connectors on the system. Note that some of these may not be
+ exposed from the chassis (e.g., LVDS or eDP). Connectors are attached
+ to encoders and contain information about the attached display sink
+ (e.g., width and height in mm, subpixel ordering, and various other
+ properties).</para>
+
+ <para>The <structfield>count_encoders</structfield> and
+ <structfield>encoders</structfield> fields list the available encoders
+ on the device. Each encoder may be associated with a CRTC, and may be
+ used to drive a particular encoder.</para>
+
+ <para>The <structfield>min*</structfield> and
+ <structfield>max*</structfield> fields indicate the maximum size of a
+ framebuffer for this device (i.e., the scanout size limit).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmModeGetResources</function> returns a drmModeRes
+ structure pointer on success, <literal>NULL</literal> on failure. The
+ returned structure must be freed with
+ <citerefentry><refentrytitle>drmModeFreeResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeRmFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeDirtyFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetEncoder</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
--
1.7.12.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH libdrm 2/4] man: add drm.7 overview page
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 1/4] man: convert manpages to XML instead of plain troff David Herrmann
@ 2012-09-28 21:44 ` David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 3/4] man: add drm-kms " David Herrmann
` (2 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: David Herrmann @ 2012-09-28 21:44 UTC (permalink / raw)
To: dri-devel
The drm.xml file compiles to drm.7 and is meant as a global overview page
for libdrm. It is targeted to new users of libdrm and redirects to all
other main man-pages.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
Reviewed-by: Jesse Barnes <jbarnes@virtuousgeek.org>
---
man/Makefile.am | 1 +
man/drm.xml | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 138 insertions(+)
create mode 100644 man/drm.xml
diff --git a/man/Makefile.am b/man/Makefile.am
index 3030e5f..d55f444 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -5,6 +5,7 @@
#
MANPAGES = \
+ drm.7 \
drmAvailable.3 \
drmHandleEvent.3 \
drmModeGetResources.3
diff --git a/man/drm.xml b/man/drm.xml
new file mode 100644
index 0000000..5a49fe1
--- /dev/null
+++ b/man/drm.xml
@@ -0,0 +1,137 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drm">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drm</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drm</refname>
+ <refpurpose>Direct Rendering Manager</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>The <emphasis>Direct Rendering Manager</emphasis> (DRM) is a framework
+ to manage <emphasis>Graphics Processing Units</emphasis> (GPUs). It is
+ designed to support the needs of complex graphics devices, usually
+ containing programmable pipelines well suited to 3D graphics
+ acceleration. Furthermore, it is responsible for memory management,
+ interrupt handling and DMA to provide a uniform interface to
+ applications.</para>
+
+ <para>In earlier days, the kernel framework was solely used to provide raw
+ hardware access to priviledged user-space processes which implement
+ all the hardware abstraction layers. But more and more tasks where
+ moved into the kernel. All these interfaces are based on
+ <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ commands on the DRM character device. The <emphasis>libdrm</emphasis>
+ library provides wrappers for these system-calls and many helpers to
+ simplify the API.</para>
+
+ <para>When a GPU is detected, the DRM system loads a driver for the detected
+ hardware type. Each connected GPU is then presented to user-space via
+ a character-device that is usually available as
+ <filename>/dev/dri/card0</filename> and can be accessed with
+ <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+ However, it still depends on the grapics driver which interfaces are
+ available on these devices. If an interface is not available, the
+ syscalls will fail with <literal>EINVAL</literal>.</para>
+
+ <refsect2>
+ <title>Authentication</title>
+ <para>All DRM devices provide authentication mechanisms. Only a DRM-Master
+ is allowed to perform mode-setting or modify core state and only one
+ user can be DRM-Master at a time. See
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for information on how to become DRM-Master and what the limitations
+ are. Other DRM users can be authenticated to the DRM-Master via
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ so they can perform buffer allocations and rendering.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Mode-Setting</title>
+ <para>Managing connected monitors and displays and changing the current
+ modes is called <emphasis>Mode-Setting</emphasis>. This is
+ restricted to the current DRM-Master. Historically, this was
+ implemented in user-space, but new DRM drivers implement a kernel
+ interface to perform mode-setting called
+ <emphasis>Kernel Mode Setting</emphasis> (KMS). If your
+ hardware-driver supports it, you can use the KMS API provided by
+ DRM. This includes allocating framebuffers, selecting modes and
+ managing CRTCs and encoders. See
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Memory Management</title>
+ <para>The most sophisticated tasks for GPUs today is managing memory
+ objects. Textures, framebuffers, command-buffers and all other kinds
+ of commands for the GPU have to be stored in memory. The DRM driver
+ takes care of managing all memory objects, flushing caches,
+ synchronizing access and providing CPU access to GPU memory. All
+ memory management is hardware driver dependent. However, two generic
+ frameworks are available that are used by most DRM drivers. These
+ are the <emphasis>Translation Table Manager</emphasis> (TTM) and the
+ <emphasis>Graphics Execution Manager</emphasis> (GEM). They provide
+ generic APIs to create, destroy and access buffers from user-space.
+ However, there are still many differences between the drivers so
+ driver-depedent code is still needed. Many helpers are provided in
+ <emphasis>libgbm</emphasis> (Graphics Buffer Manager) from the
+ <emphasis>mesa-project</emphasis>. For more information on DRM
+ memory-management, see
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this manual should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
--
1.7.12.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH libdrm 3/4] man: add drm-kms overview page
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 1/4] man: convert manpages to XML instead of plain troff David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 2/4] man: add drm.7 overview page David Herrmann
@ 2012-09-28 21:44 ` David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 4/4] man: add drm-memory " David Herrmann
2013-01-10 0:22 ` [PATCH libdrm 0/4] Manpages for libdrm Jesse Barnes
4 siblings, 0 replies; 8+ messages in thread
From: David Herrmann @ 2012-09-28 21:44 UTC (permalink / raw)
To: dri-devel
This is an overview page for KMS. It is again targeted at novice users
that need redirection to the correct function man-pages.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
Reviewed-by: Jesse Barnes <jbarnes@virtuousgeek.org>
---
man/Makefile.am | 1 +
man/drm-kms.xml | 342 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 343 insertions(+)
create mode 100644 man/drm-kms.xml
diff --git a/man/Makefile.am b/man/Makefile.am
index d55f444..ae02728 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -6,6 +6,7 @@
MANPAGES = \
drm.7 \
+ drm-kms.7 \
drmAvailable.3 \
drmHandleEvent.3 \
drmModeGetResources.3
diff --git a/man/drm-kms.xml b/man/drm-kms.xml
new file mode 100644
index 0000000..5f04157
--- /dev/null
+++ b/man/drm-kms.xml
@@ -0,0 +1,342 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drm-kms">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drm-kms</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drm-kms</refname>
+ <refpurpose>Kernel Mode-Setting</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <xf86drmMode.h></funcsynopsisinfo>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>Each DRM device provides access to manage which monitors and displays
+ are currently used and what frames to be displayed. This task is
+ called <emphasis>Kernel Mode-Setting</emphasis> (KMS). Historically,
+ this was done in user-space and called
+ <emphasis>User-space Mode-Setting</emphasis> (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
+ <citerefentry><refentrytitle>drmModeSettingSupported</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ to check whether your driver supports this. To understand how KMS
+ works, we need to introduce 5 objects: <emphasis>CRTCs</emphasis>,
+ <emphasis>Planes</emphasis>, <emphasis>Encoders</emphasis>,
+ <emphasis>Connectors</emphasis> and
+ <emphasis>Framebuffers</emphasis>.
+
+ <variablelist>
+ <varlistentry>
+ <term>CRTCs</term>
+ <listitem>
+ <para>A <emphasis>CRTC</emphasis> short for
+ <emphasis>CRT Controller</emphasis> 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
+ <citerefentry><refentrytitle>drmModeCrtcSet</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ to drive the display devices.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Planes</term>
+ <listitem>
+ <para>A <emphasis>plane</emphasis> 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).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Encoders</term>
+ <listitem>
+ <para>An <emphasis>encoder</emphasis> 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 <emphasis>cloned</emphasis> display
+ configuration across the connectors attached to each
+ encoder.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Connectors</term>
+ <listitem>
+ <para>A <emphasis>connector</emphasis> 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, <emphasis>EDID</emphasis> data,
+ <emphasis>DPMS</emphasis> and
+ <emphasis>connection status</emphasis>, and information about
+ modes supported on the attached displays.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Framebuffers</term>
+ <listitem>
+ <para><emphasis>Framebuffers</emphasis> are abstract memory objects
+ that provide a source of pixel data to scanout to a CRTC.
+ Applications explicitely 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
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ API.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <refsect2>
+ <title>Mode-Setting</title>
+ <para>Before mode-setting can be performed, an application needs to call
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ to become <emphasis>DRM-Master</emphasis>. It then has exclusive
+ access to the KMS API. A call to
+ <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ returns a list of <emphasis>CRTCs</emphasis>,
+ <emphasis>Connectors</emphasis>, <emphasis>Encoders</emphasis> and
+ <emphasis>Planes</emphasis>.</para>
+
+ <para>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 <emphasis>Examples</emphasis>
+ section below for more information.</para>
+
+ <para>All valid modes for a connector can be retrieved with a call to
+ <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ 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.</para>
+
+ <para>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-depedent and described in
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ 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
+ <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+ <para>As a last step, you want to program your CRTC to drive your selected
+ connector. You can do this with a call to
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Page-Flipping</title>
+ <para>A call to
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ 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
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ on the next buffer to flip. If you want to synchronize your flips
+ with <emphasis>vertical-blanks</emphasis>, you can use
+ <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ which schedules your page-flip for the next
+ <emphasis>vblank</emphasis>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Planes</title>
+ <para>Planes are controlled independently from CRTCs. That is, a call to
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ does not affect planes. Instead, you need to call
+ <citerefentry><refentrytitle>drmModeSetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ 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
+ <citerefentry><refentrytitle>drmModeGetPlaneResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for more information.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Cursors</title>
+ <para>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
+ <citerefentry><refentrytitle>drmModeSetCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and move it on the screen with
+ <citerefentry><refentrytitle>drmModeMoveCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ 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.</para>
+ </refsect2>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <para>Some examples of how basic mode-setting can be done. See the man-page
+ of each DRM function for more information.</para>
+
+ <refsect2>
+ <title>CRTC/Encoder Selection</title>
+ <para>If you retrieved all display configuration information via
+ <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ as <structname>drmModeRes</structname> *<varname>res</varname>,
+ selected a connector from the list in
+ <varname>res</varname>-><structfield>connectors</structfield>
+ and retrieved the connector-information as
+ <structname>drmModeConnector</structname> *<varname>conn</varname>
+ via
+ <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ 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
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
+ as <varname>fd</varname>, a pointer to the retrieved resources as
+ <varname>res</varname> and a pointer to the selected connector as
+ <varname>conn</varname>. It returns an integer smaller than 0 on
+ failure, otherwise, a valid CRTC id is returned.</para>
+
+<programlisting>
+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 "crtc". 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] "is unused") {
+ drmModeFreeEncoder(enc);
+ return res->crtcs[j];
+ }
+ }
+
+ drmModeFreeEncoder(enc);
+ }
+
+ /* cannot find a suitable CRTC */
+ return -ENOENT;
+}
+</programlisting>
+
+ </refsect2>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this manual should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetEncoder</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeRmFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetPlaneResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeSetPlane</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeSetCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeMoveCursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmCheckModesettingSupported</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
--
1.7.12.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH libdrm 4/4] man: add drm-memory overview page
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
` (2 preceding siblings ...)
2012-09-28 21:44 ` [PATCH libdrm 3/4] man: add drm-kms " David Herrmann
@ 2012-09-28 21:44 ` David Herrmann
2013-01-10 0:22 ` [PATCH libdrm 0/4] Manpages for libdrm Jesse Barnes
4 siblings, 0 replies; 8+ messages in thread
From: David Herrmann @ 2012-09-28 21:44 UTC (permalink / raw)
To: dri-devel
This adds an overview page that describes Dumb-Buffers, TTM and GEM. It
does not describe chipset-specific features. You should do that in the
driver-manpages.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
Reviewed-by: Jesse Barnes <jbarnes@virtuousgeek.org>
---
man/Makefile.am | 9 +-
man/drm-memory.xml | 430 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 437 insertions(+), 2 deletions(-)
create mode 100644 man/drm-memory.xml
diff --git a/man/Makefile.am b/man/Makefile.am
index ae02728..fb69c45 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -7,10 +7,14 @@
MANPAGES = \
drm.7 \
drm-kms.7 \
+ drm-memory.7 \
drmAvailable.3 \
drmHandleEvent.3 \
drmModeGetResources.3
-MANPAGES_ALIASES =
+MANPAGES_ALIASES = \
+ drm-mm.7 \
+ drm-gem.7 \
+ drm-ttm.7
XML_FILES = \
${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,$(MANPAGES)}}}}
@@ -32,7 +36,8 @@ XSLTPROC_FLAGS = \
XSLTPROC_PROCESS_MAN = \
$(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
- $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< && \
+ $(SED) -i -e 's/^\.so \(.*\)\.\(.\)$$/\.so man\2\/\1\.\2/' $(MANPAGES_ALIASES)
%.1: %.xml
$(XSLTPROC_PROCESS_MAN)
diff --git a/man/drm-memory.xml b/man/drm-memory.xml
new file mode 100644
index 0000000..6b4f075
--- /dev/null
+++ b/man/drm-memory.xml
@@ -0,0 +1,430 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drm-memory">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drm-memory</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drm-memory</refname>
+ <refname>drm-mm</refname>
+ <refname>drm-gem</refname>
+ <refname>drm-ttm</refname>
+ <refpurpose>DRM Memory Management</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <refsect2>
+ <title>Dumb-Buffers</title>
+ <para>Almost all in-kernel DRM hardware drivers support an API called
+ <emphasis>Dumb-Buffers</emphasis>. This API allows to create buffers
+ of arbitrary size that can be used for scanout. These buffers can be
+ memory mapped via
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ 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.</para>
+
+ <para>The <constant>DRM_IOCTL_MODE_CREATE_DUMB</constant> ioctl can be
+ used to create a dumb buffer. The kernel will return a 32bit handle
+ that can be used to manage the buffer with the DRM API. You can
+ create framebuffers with
+ <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and use it for mode-setting and scanout. To access the buffer, you
+ first need to retrieve the offset of the buffer. The
+ <constant>DRM_IOCTL_MODE_MAP_DUMB</constant> ioctl requests the DRM
+ subsystem to prepare the buffer for memory-mapping and returns a
+ fake-offset that can be used with
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
+
+ <para>The <constant>DRM_IOCTL_MODE_CREATE_DUMB</constant> ioctl takes as
+ argument a structure of type
+ <structname>struct drm_mode_create_dumb</structname>:
+
+<programlisting>
+struct drm_mode_create_dumb {
+ __u32 height;
+ __u32 width;
+ __u32 bpp;
+ __u32 flags;
+
+ __u32 handle;
+ __u32 pitch;
+ __u64 size;
+};
+</programlisting>
+
+ The fields <structfield>height</structfield>,
+ <structfield>width</structfield>, <structfield>bpp</structfield> and
+ <structfield>flags</structfield> have to be provided by the caller.
+ The other fields are filled by the kernel with the return values.
+ <structfield>height</structfield> and
+ <structfield>width</structfield> are the dimensions of the
+ rectangular buffer that is created. <structfield>bpp</structfield>
+ is the number of bits-per-pixel and must be a multiple of
+ <literal>8</literal>. You most commonly want to pass
+ <literal>32</literal> here. The <structfield>flags</structfield>
+ 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 <structfield>handle</structfield>,
+ <structfield>pitch</structfield> and <structfield>size</structfield>
+ fields are filled by the kernel. <structfield>handle</structfield>
+ is a 32bit gem handle that identifies the buffer. This is used by
+ several other calls that take a gem-handle or memory-buffer as
+ argument. The <structfield>pitch</structfield> field is the
+ pitch (or stride) of the new buffer. Most drivers use 32bit or 64bit
+ aligned stride-values. The <structfield>size</structfield> field
+ contains the absolute size in bytes of the buffer. This can normally
+ also be computed with
+ <emphasis>(height * pitch + width) * bpp / 4</emphasis>.</para>
+
+ <para>To prepare the buffer for
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ you need to use the <constant>DRM_IOCTL_MODE_MAP_DUMB</constant>
+ ioctl. It takes as argument a structure of type
+ <structname>struct drm_mode_map_dumb</structname>:
+
+<programlisting>
+struct drm_mode_map_dumb {
+ __u32 handle;
+ __u32 pad;
+
+ __u64 offset;
+};
+</programlisting>
+
+ You need to put the gem-handle that was previously retrieved via
+ <constant>DRM_IOCTL_MODE_CREATE_DUMB</constant> into the
+ <structfield>handle</structfield> field. The
+ <structfield>pad</structfield> field is unused padding and must be
+ zeroed. After completion, the <structfield>offset</structfield>
+ field will contain an offset that can be used with
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on the DRM file-descriptor.</para>
+
+ <para>If you don't need your dumb-buffer, anymore, you have to destroy it
+ with <constant>DRM_IOCTL_MODE_DESTROY_DUMB</constant>. If you close
+ the DRM file-descriptor, all open dumb-buffers are automatically
+ destroyed. This ioctl takes as argument a structure of type
+ <structname>struct drm_mode_destroy_dumb</structname>:
+
+<programlisting>
+struct drm_mode_destroy_dumb {
+ __u32 handle;
+};
+</programlisting>
+
+ You only need to put your handle into the
+ <structfield>handle</structfield> field. After this call, the handle
+ is invalid and may be reused for new buffers by the dumb-API.</para>
+
+ </refsect2>
+
+ <refsect2>
+ <title>TTM</title>
+ <para><emphasis>TTM</emphasis> stands for
+ <emphasis>Translation Table Manager</emphasis> 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 manpages for more
+ information on memory-management with radeon and TTM.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>GEM</title>
+ <para><emphasis>GEM</emphasis> stands for
+ <emphasis>Graphics Execution Manager</emphasis> 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.</para>
+
+ <para>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.</para>
+
+ <para>All GEM APIs are defined as
+ <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on the DRM file descriptor. An application must be authorized via
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ to the current DRM-Master to access the GEM subsystem. A driver that
+ does not support gem will return <constant>ENODEV</constant> for all
+ these ioctls. Invalid object handles return
+ <constant>EINVAL</constant> and invalid object names return
+ <constant>ENOENT</constant>.</para>
+
+ <para>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.</para>
+
+ <para>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
+ <citerefentry><refentrytitle>drm-prime</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ 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.</para>
+
+ <para>Gem-buffers cannot be created with a generic API. Each driver
+ provides its own API to create gem-buffers. See for example
+ <constant>DRM_I915_GEM_CREATE</constant>,
+ <constant>DRM_NOUVEAU_GEM_NEW</constant> or
+ <constant>DRM_RADEON_GEM_CREATE</constant>. Each of these ioctls
+ returns a gem-handle that can be passed to different generic ioctls.
+ The <emphasis>libgbm</emphasis> library from the
+ <emphasis>mesa3D</emphasis> 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
+ <citerefentry><refentrytitle>drm-intel</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ or
+ <citerefentry><refentrytitle>drm-radeon</refentrytitle><manvolnum>7</manvolnum></citerefentry>).</para>
+
+ <para>Gem-buffers can be closed with the
+ <constant>DRM_IOCTL_GEM_CLOSE</constant> ioctl. It takes as argument
+ a structure of type <structname>struct drm_gem_close</structname>:
+
+<programlisting>
+struct drm_gem_close {
+ __u32 handle;
+ __u32 pad;
+};
+</programlisting>
+
+ The <structfield>handle</structfield> field is the gem-handle to be
+ closed. The <structfield>pad</structfield> field is unused padding.
+ It must be zeroed. 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.</para>
+
+ <para>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 32bit
+ 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
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ to the current DRM-Master, can <emphasis>guess</emphasis> the name
+ and open or access the gem-object. If you want more fine-grained
+ access control, you can use the new
+ <citerefentry><refentrytitle>drm-prime</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ API to retrieve file-descriptors for gem-handles. To create a name
+ for a gem-handle, you use the
+ <constant>DRM_IOCTL_GEM_FLINK</constant> ioctl. It takes as argument
+ a structure of type <structname>struct drm_gem_flink</structname>:
+
+<programlisting>
+struct drm_gem_flink {
+ __u32 handle;
+ __u32 name;
+};
+</programlisting>
+
+ You have to put your handle into the
+ <structfield>handle</structfield> field. After completion, the
+ kernel has put the new unique name into the
+ <structfield>name</structfield> field. You can now pass this name to
+ other processes which can then import the name with the
+ <constant>DRM_IOCTL_GEM_OPEN</constant> ioctl. It takes as argument
+ a structure of type <structname>struct drm_gem_open</structname>:
+
+<programlisting>
+struct drm_gem_open {
+ __u32 name;
+
+ __u32 handle;
+ __u32 size;
+};
+</programlisting>
+
+ You have to fill in the <structfield>name</structfield> field with
+ the name of the gem-object that you want to open. The kernel will
+ fill in the <structfield>handle</structfield> and
+ <structfield>size</structfield> 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.</para>
+
+ <para>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 <emphasis>OpenGL</emphasis>. So if you want to
+ use more GPU features, you should use the
+ <emphasis>mesa3D</emphasis> library to create OpenGL contexts on DRM
+ devices. This does <emphasis>not</emphasis> 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 manpages, 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
+ <citerefentry><refentrytitle>drm-intel</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-radeon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>drm-nouveau</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ However, the
+ <citerefentry><refentrytitle>drm-prime</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ 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.</para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+ <para>This section includes examples for basic memory-management
+ tasks.</para>
+
+ <refsect2>
+ <title>Dumb-Buffers</title>
+ <para>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
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>).</para>
+
+<programlisting>
+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);
+</programlisting>
+
+ </refsect2>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this manual should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-prime</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-intel</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-radeon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-nouveau</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
--
1.7.12.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH libdrm 0/4] Manpages for libdrm
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
` (3 preceding siblings ...)
2012-09-28 21:44 ` [PATCH libdrm 4/4] man: add drm-memory " David Herrmann
@ 2013-01-10 0:22 ` Jesse Barnes
2013-01-10 21:00 ` David Herrmann
4 siblings, 1 reply; 8+ messages in thread
From: Jesse Barnes @ 2013-01-10 0:22 UTC (permalink / raw)
To: David Herrmann; +Cc: dri-devel
On Fri, 28 Sep 2012 23:44:18 +0200
David Herrmann <dh.herrmann@googlemail.com> wrote:
> Hi
>
> This is revision 2 of the manpages for libdrm. I converted everything to docbook
> XML. This makes it easier to write them (troff is really hard to read) and
> allows us to integrate it into other documentation.
>
> Other than that I only fixed typos and the small corrections you guys mentioned.
> Thanks for reviewing!
I went ahead and pushed these finally.
Can you just apply for an fdo account though so we can let you push
things in the future? :)
--
Jesse Barnes, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH libdrm 0/4] Manpages for libdrm
2013-01-10 0:22 ` [PATCH libdrm 0/4] Manpages for libdrm Jesse Barnes
@ 2013-01-10 21:00 ` David Herrmann
2013-01-10 21:19 ` Jesse Barnes
0 siblings, 1 reply; 8+ messages in thread
From: David Herrmann @ 2013-01-10 21:00 UTC (permalink / raw)
To: Jesse Barnes; +Cc: dri-devel
Hi Jesse
On Thu, Jan 10, 2013 at 1:22 AM, Jesse Barnes <jbarnes@virtuousgeek.org> wrote:
> On Fri, 28 Sep 2012 23:44:18 +0200
> David Herrmann <dh.herrmann@googlemail.com> wrote:
>
>> Hi
>>
>> This is revision 2 of the manpages for libdrm. I converted everything to docbook
>> XML. This makes it easier to write them (troff is really hard to read) and
>> allows us to integrate it into other documentation.
>>
>> Other than that I only fixed typos and the small corrections you guys mentioned.
>> Thanks for reviewing!
>
> I went ahead and pushed these finally.
Thanks!
> Can you just apply for an fdo account though so we can let you push
> things in the future? :)
I don't have a signed ssh key but I guess I can get it signed by some
people at FOSDEM13. I will then apply for an account afterwards.
I also have some cleanup patches for the man-page build here that
should be applied. I actually don't know why it fails on your machine
but my rework should build them properly. I will send them shortly.
Thanks
David
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH libdrm 0/4] Manpages for libdrm
2013-01-10 21:00 ` David Herrmann
@ 2013-01-10 21:19 ` Jesse Barnes
0 siblings, 0 replies; 8+ messages in thread
From: Jesse Barnes @ 2013-01-10 21:19 UTC (permalink / raw)
To: David Herrmann; +Cc: dri-devel
On Thu, 10 Jan 2013 22:00:20 +0100
David Herrmann <dh.herrmann@googlemail.com> wrote:
> Hi Jesse
>
> On Thu, Jan 10, 2013 at 1:22 AM, Jesse Barnes <jbarnes@virtuousgeek.org> wrote:
> > On Fri, 28 Sep 2012 23:44:18 +0200
> > David Herrmann <dh.herrmann@googlemail.com> wrote:
> >
> >> Hi
> >>
> >> This is revision 2 of the manpages for libdrm. I converted everything to docbook
> >> XML. This makes it easier to write them (troff is really hard to read) and
> >> allows us to integrate it into other documentation.
> >>
> >> Other than that I only fixed typos and the small corrections you guys mentioned.
> >> Thanks for reviewing!
> >
> > I went ahead and pushed these finally.
>
> Thanks!
>
> > Can you just apply for an fdo account though so we can let you push
> > things in the future? :)
>
> I don't have a signed ssh key but I guess I can get it signed by some
> people at FOSDEM13. I will then apply for an account afterwards.
>
> I also have some cleanup patches for the man-page build here that
> should be applied. I actually don't know why it fails on your machine
> but my rework should build them properly. I will send them shortly.
Great, thanks. See you there!
--
Jesse Barnes, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2013-01-10 21:25 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-09-28 21:44 [PATCH libdrm 0/4] Manpages for libdrm David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 1/4] man: convert manpages to XML instead of plain troff David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 2/4] man: add drm.7 overview page David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 3/4] man: add drm-kms " David Herrmann
2012-09-28 21:44 ` [PATCH libdrm 4/4] man: add drm-memory " David Herrmann
2013-01-10 0:22 ` [PATCH libdrm 0/4] Manpages for libdrm Jesse Barnes
2013-01-10 21:00 ` David Herrmann
2013-01-10 21:19 ` Jesse Barnes
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).