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
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>
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>
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>
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>
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? :)
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
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!
dri-devel@lists.freedesktop.org
-
David Herrmann -
Jesse Barnes