install libdrm manual pages; feedback and OK jsg@ matthieu@

7 files changed, 1079 insertions, 1 deletions

diff --git a/lib/libdrm/Makefile.bsd-wrapper b/lib/libdrm/Makefile.bsd-wrapper
index 3fb0b53bb..e1de6c40f 100644
--- a/lib/libdrm/Makefile.bsd-wrapper
+++ b/lib/libdrm/Makefile.bsd-wrapper
@@ -1,6 +1,27 @@
-# $OpenBSD: Makefile.bsd-wrapper,v 1.18 2019/04/26 07:45:37 jsg Exp $
+# $OpenBSD: Makefile.bsd-wrapper,v 1.19 2019/04/28 20:47:20 schwarze Exp $
 
 SHARED_LIBS=	drm 7.7 drm_radeon 4.0 drm_intel 5.4 \
 		drm_amdgpu 1.8 drm_nouveau 3.0
 
+MDOCS=		drmAvailable 3 drmHandleEvent 3 drmModeGetResources 3 \
+		drm 7 drm-kms 7 drm-memory 7
+
+beforeinstall:
+.for n s in ${MDOCS}
+	${INSTALL} ${INSTALL_COPY} -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} \
+		${.CURDIR}/man/${n}.${s} ${MANDIR}${s}
+.endfor
+
+# maintainer target, not used duing build or install
+mdoc:
+.for n s in ${MDOCS}
+	{ \
+		echo ".\\\" automatically generated with"; \
+		echo ".\\\" docbook2mdoc ${n}.xml > ${n}.${s}"; \
+		docbook2mdoc ${.CURDIR}/man/${n}.xml; \
+	} > ${.CURDIR}/man/${n}.${s}
+.endfor
+
+.PHONY: mdoc
+
 .include <bsd.xorg.mk>
diff --git a/lib/libdrm/man/drm-kms.7 b/lib/libdrm/man/drm-kms.7
new file mode 100644
index 000000000..d3000b7d1
--- /dev/null
+++ b/lib/libdrm/man/drm-kms.7
@@ -0,0 +1,296 @@
+.\" automatically generated with
+.\" docbook2mdoc drm-kms.xml > drm-kms.7
+.Dd September 2012
+.Dt DRM-KMS 7
+.Os
+.Sh NAME
+.Nm drm-kms
+.Nd Kernel Mode-Setting
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Fd #include <xf86drmMode.h>
+.Sh DESCRIPTION
+Each DRM device provides access to manage which monitors and displays
+are currently used and what frames to be displayed. This task is
+called
+.Em Kernel Mode-Setting
+(KMS). Historically,
+this was done in user-space and called
+.Em User-space Mode-Setting
+(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
+.Xr drmModeSettingSupported 3
+to check whether your driver supports this. To understand how KMS
+works, we need to introduce 5 objects:
+.Em CRTCs ,
+.Em Planes ,
+.Em Encoders ,
+.Em Connectors
+and
+.Em Framebuffers .
+.Bl -tag -width Ds
+.It CRTCs
+A
+.Em CRTC
+short for
+.Em CRT Controller
+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
+.Xr drmModeCrtcSet 3
+to drive the display devices.
+.It Planes
+A
+.Em plane
+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).
+.It Encoders
+An
+.Em encoder
+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
+.Em cloned
+display
+configuration across the connectors attached to each
+encoder.
+.It Connectors
+A
+.Em connector
+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,
+.Em EDID
+data,
+.Em DPMS
+and
+.Em connection status ,
+and information about
+modes supported on the attached displays.
+.It Framebuffers
+.Em Framebuffers
+are abstract memory objects
+that provide a source of pixel data to scanout to a CRTC.
+Applications explicitly request the creation of framebuffers
+and can control their behavior. Framebuffers rely on the
+underneath memory manager for low-level memory operations.
+When creating a framebuffer, applications pass a memory handle
+through the API which is used as backing storage. The
+framebuffer itself is only an abstract object with no data. It
+just refers to memory buffers that must be created with the
+.Xr drm-memory 7
+API.
+.El
+.Ss Mode-Setting
+Before mode-setting can be performed, an application needs to call
+.Xr drmSetMaster 3
+to become
+.Em DRM-Master .
+It then has exclusive
+access to the KMS API. A call to
+.Xr drmModeGetResources 3
+returns a list of
+.Em CRTCs ,
+.Em Connectors ,
+.Em Encoders
+and
+.Em Planes .
+.Pp
+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
+.Em Examples
+section below for more information.
+.Pp
+All valid modes for a connector can be retrieved with a call to
+.Xr drmModeGetConnector 3
+You need to select the mode you want to use and save it. The first
+mode in the list is the default mode with the highest resolution
+possible and often a suitable choice.
+.Pp
+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
+.Xr drm-memory 7 .
+You need to create a buffer big enough for your selected mode. Now
+you can create a framebuffer object that uses your memory-buffer as
+scanout buffer. You can do this with
+.Xr drmModeAddFB 3
+and
+.Xr drmModeAddFB2 3 .
+.Pp
+As a last step, you want to program your CRTC to drive your selected
+connector. You can do this with a call to
+.Xr drmModeSetCrtc 3 .
+.Ss Page-Flipping
+A call to
+.Xr drmModeSetCrtc 3
+is executed immediately and forces the CRTC to use the new scanout
+buffer. If you want smooth-transitions without tearing, you probably
+use double-buffering. You need to create one framebuffer object for
+each buffer you use. You can then call
+.Xr drmModeSetCrtc 3
+on the next buffer to flip. If you want to synchronize your flips
+with
+.Em vertical-blanks ,
+you can use
+.Xr drmModePageFlip 3
+which schedules your page-flip for the next
+.Em vblank .
+.Ss Planes
+Planes are controlled independently from CRTCs. That is, a call to
+.Xr drmModeSetCrtc 3
+does not affect planes. Instead, you need to call
+.Xr drmModeSetPlane 3
+to configure a plane. This requires the plane ID, a CRTC, a
+framebuffer and offsets into the plane-framebuffer and the
+CRTC-framebuffer. The CRTC then blends the content from the plane
+over the CRTC framebuffer buffer during scanout. As this does not
+involve any software-blending, it is way faster than traditional
+blending. However, plane resources are limited. See
+.Xr drmModeGetPlaneResources 3
+for more information.
+.Ss Cursors
+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
+.Xr drmModeSetCursor 3
+and move it on the screen with
+.Xr drmModeMoveCursor 3 .
+This allows to move the cursor on the screen without rerendering. If
+no hardware cursors are supported, you need to rerender for each
+frame the cursor is moved.
+.Sh EXAMPLES
+Some examples of how basic mode-setting can be done. See the man-page
+of each DRM function for more information.
+.Ss CRTC/Encoder Selection
+If you retrieved all display configuration information via
+.Xr drmModeGetResources 3
+as
+.Vt drmModeRes
+.Pf * Va res ,
+selected a connector from the list in
+.Va res Ns -> Ns Fa connectors
+and retrieved the connector-information as
+.Vt drmModeConnector
+.Pf * Va conn
+via
+.Xr drmModeGetConnector 3
+then this example shows, how you can find a suitable CRTC id to
+drive this connector. This function takes a file-descriptor to the
+DRM device (see
+.Xr drmOpen 3 )
+as
+.Va fd ,
+a pointer to the retrieved resources as
+.Va res
+and a pointer to the selected connector as
+.Va conn .
+It returns an integer smaller than 0 on
+failure, otherwise, a valid CRTC id is returned.
+.Bd -literal
+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;
+}
+.Ed
+.Sh REPORTING BUGS
+Bugs in this manual should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm 7 ,
+.Xr drm-memory 7 ,
+.Xr drmModeGetResources 3 ,
+.Xr drmModeGetConnector 3 ,
+.Xr drmModeGetEncoder 3 ,
+.Xr drmModeGetCrtc 3 ,
+.Xr drmModeSetCrtc 3 ,
+.Xr drmModeGetFB 3 ,
+.Xr drmModeAddFB 3 ,
+.Xr drmModeAddFB2 3 ,
+.Xr drmModeRmFB 3 ,
+.Xr drmModePageFlip 3 ,
+.Xr drmModeGetPlaneResources 3 ,
+.Xr drmModeGetPlane 3 ,
+.Xr drmModeSetPlane 3 ,
+.Xr drmModeSetCursor 3 ,
+.Xr drmModeMoveCursor 3 ,
+.Xr drmSetMaster 3 ,
+.Xr drmAvailable 3 ,
+.Xr drmCheckModesettingSupported 3 ,
+.Xr drmOpen 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com
diff --git a/lib/libdrm/man/drm-memory.7 b/lib/libdrm/man/drm-memory.7
new file mode 100644
index 000000000..c5167308f
--- /dev/null
+++ b/lib/libdrm/man/drm-memory.7
@@ -0,0 +1,432 @@
+.\" automatically generated with
+.\" docbook2mdoc drm-memory.xml > drm-memory.7
+.Dd September 2012
+.Dt DRM-MEMORY 7
+.Os
+.Sh NAME
+.Nm drm-memory ,
+.Nm drm-mm ,
+.Nm drm-gem ,
+.Nm drm-ttm
+.Nd DRM Memory Management
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Sh DESCRIPTION
+Many modern high-end GPUs come with their own memory managers. They
+even include several different caches that need to be synchronized
+during access. Textures, framebuffers, command buffers and more need
+to be stored in memory that can be accessed quickly by the GPU.
+Therefore, memory management on GPUs is highly driver- and
+hardware-dependent.
+.Pp
+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.
+.Ss Dumb-Buffers
+Almost all in-kernel DRM hardware drivers support an API called
+.Em Dumb-Buffers .
+This API allows to create buffers
+of arbitrary size that can be used for scanout. These buffers can be
+memory mapped via
+.Xr mmap 2
+so you can render into them on the CPU. However, GPU access to these
+buffers is often not possible. Therefore, they are fine for simple
+tasks but not suitable for complex compositions and
+renderings.
+.Pp
+The
+.Dv DRM_IOCTL_MODE_CREATE_DUMB
+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
+.Xr drmModeAddFB 3
+and use it for mode-setting and scanout. To access the buffer, you
+first need to retrieve the offset of the buffer. The
+.Dv DRM_IOCTL_MODE_MAP_DUMB
+ioctl requests the DRM
+subsystem to prepare the buffer for memory-mapping and returns a
+fake-offset that can be used with
+.Xr mmap 2 .
+.Pp
+The
+.Dv DRM_IOCTL_MODE_CREATE_DUMB
+ioctl takes as
+argument a structure of type
+.Vt struct drm_mode_create_dumb :
+.Bd -literal
+struct drm_mode_create_dumb {
+	__u32 height;
+	__u32 width;
+	__u32 bpp;
+	__u32 flags;
+	__u32 handle;
+	__u32 pitch;
+	__u64 size;
+};
+.Ed
+.Pp
+The fields
+.Fa height ,
+.Fa width ,
+.Fa bpp
+and
+.Fa flags
+have to be provided by the caller.
+The other fields are filled by the kernel with the return values.
+.Fa height
+and
+.Fa width
+are the dimensions of the
+rectangular buffer that is created.
+.Fa bpp
+is the number of bits-per-pixel and must be a multiple of
+.Ql 8 .
+You most commonly want to pass
+.Ql 32
+here. The
+.Fa flags
+field is currently unused and must be zeroed. Different flags to
+modify the behavior may be added in the future. After calling the
+ioctl, the
+.Fa handle ,
+.Fa pitch
+and
+.Fa size
+fields are filled by the kernel.
+.Fa handle
+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
+.Fa pitch
+field is the
+pitch (or stride) of the new buffer. Most drivers use 32bit or 64bit
+aligned stride-values. The
+.Fa size
+field
+contains the absolute size in bytes of the buffer. This can normally
+also be computed with
+.Em (height * pitch + width) * bpp / 4 .
+.Pp
+To prepare the buffer for
+.Xr mmap 2
+you need to use the
+.Dv DRM_IOCTL_MODE_MAP_DUMB
+ioctl. It takes as argument a structure of type
+.Vt struct drm_mode_map_dumb :
+.Bd -literal
+struct drm_mode_map_dumb {
+	__u32 handle;
+	__u32 pad;
+	__u64 offset;
+};
+.Ed
+.Pp
+You need to put the gem-handle that was previously retrieved via
+.Dv DRM_IOCTL_MODE_CREATE_DUMB
+into the
+.Fa handle
+field. The
+.Fa pad
+field is unused padding and must be
+zeroed. After completion, the
+.Fa offset
+field will contain an offset that can be used with
+.Xr mmap 2
+on the DRM file-descriptor.
+.Pp
+If you don't need your dumb-buffer, anymore, you have to destroy it
+with
+.Dv DRM_IOCTL_MODE_DESTROY_DUMB .
+If you close
+the DRM file-descriptor, all open dumb-buffers are automatically
+destroyed. This ioctl takes as argument a structure of type
+.Vt struct drm_mode_destroy_dumb :
+.Bd -literal
+struct drm_mode_destroy_dumb {
+	__u32 handle;
+};
+.Ed
+.Pp
+You only need to put your handle into the
+.Fa handle
+field. After this call, the handle
+is invalid and may be reused for new buffers by the dumb-API.
+.Ss TTM
+.Em TTM
+stands for
+.Em Translation Table Manager
+and is a generic
+memory-manager provided by the kernel. It does not provide a common
+user-space API so you need to look at each driver interface if you
+want to use it. See for instance the radeon manpages for more
+information on memory-management with radeon and TTM.
+.Ss GEM
+.Em GEM
+stands for
+.Em Graphics Execution Manager
+and is a generic DRM
+memory-management framework in the kernel, that is used by many
+different drivers. Gem is designed to manage graphics memory,
+control access to the graphics device execution context and handle
+essentially NUMA environment unique to modern graphics hardware. Gem
+allows multiple applications to share graphics device resources
+without the need to constantly reload the entire graphics card. Data
+may be shared between multiple applications with gem ensuring that
+the correct memory synchronization occurs.
+.Pp
+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.
+.Pp
+All GEM APIs are defined as
+.Xr ioctl 2
+on the DRM file descriptor. An application must be authorized via
+.Xr drmAuthMagic 3
+to the current DRM-Master to access the GEM subsystem. A driver that
+does not support gem will return
+.Dv ENODEV
+for all
+these ioctls. Invalid object handles return
+.Dv EINVAL
+and invalid object names return
+.Dv ENOENT .
+.Pp
+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.
+.Pp
+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
+.Xr drm-prime 7
+infrastructure which can return real file-descriptor for gem-handles
+using the linux dma-buf API. Objects may be published with a name so
+that other applications and processes can access them. The name
+remains valid as long as the object exists. Gem-objects are
+reference counted in the kernel. The object is only destroyed when
+all handles from user-space were closed.
+.Pp
+Gem-buffers cannot be created with a generic API. Each driver
+provides its own API to create gem-buffers. See for example
+.Dv DRM_I915_GEM_CREATE ,
+.Dv DRM_NOUVEAU_GEM_NEW
+or
+.Dv DRM_RADEON_GEM_CREATE .
+Each of these ioctls
+returns a gem-handle that can be passed to different generic ioctls.
+The
+.Em libgbm
+library from the
+.Em mesa3D
+distribution tries to provide a
+driver-independent API to create gbm buffers and retrieve a
+gbm-handle to them. It allows to create buffers for different
+use-cases including scanout, rendering, cursors and CPU-access. See
+the libgbm library for more information or look at the
+driver-dependent man-pages (for example
+.Xr drm-intel 7
+or
+.Xr drm-radeon 7 ) .
+.Pp
+Gem-buffers can be closed with the
+.Dv DRM_IOCTL_GEM_CLOSE
+ioctl. It takes as argument
+a structure of type
+.Vt struct drm_gem_close :
+.Bd -literal
+struct drm_gem_close {
+	__u32 handle;
+	__u32 pad;
+};
+.Ed
+.Pp
+The
+.Fa handle
+field is the gem-handle to be
+closed. The
+.Fa pad
+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.
+.Pp
+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
+.Xr drmAuthMagic 3
+to the current DRM-Master, can
+.Em guess
+the name
+and open or access the gem-object. If you want more fine-grained
+access control, you can use the new
+.Xr drm-prime 7
+API to retrieve file-descriptors for gem-handles. To create a name
+for a gem-handle, you use the
+.Dv DRM_IOCTL_GEM_FLINK
+ioctl. It takes as argument
+a structure of type
+.Vt struct drm_gem_flink :
+.Bd -literal
+struct drm_gem_flink {
+	__u32 handle;
+	__u32 name;
+};
+.Ed
+.Pp
+You have to put your handle into the
+.Fa handle
+field. After completion, the
+kernel has put the new unique name into the
+.Fa name
+field. You can now pass this name to
+other processes which can then import the name with the
+.Dv DRM_IOCTL_GEM_OPEN
+ioctl. It takes as argument
+a structure of type
+.Vt struct drm_gem_open :
+.Bd -literal
+struct drm_gem_open {
+	__u32 name;
+	__u32 handle;
+	__u32 size;
+};
+.Ed
+.Pp
+You have to fill in the
+.Fa name
+field with
+the name of the gem-object that you want to open. The kernel will
+fill in the
+.Fa handle
+and
+.Fa size
+fields with the new handle and size
+of the gem-object. You can now access the gem-object via the handle
+as if you created it with the gem API.
+.Pp
+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
+.Em OpenGL .
+So if you want to
+use more GPU features, you should use the
+.Em mesa3D
+library to create OpenGL contexts on DRM
+devices. This does
+.Em not
+require any
+windowing-system like X11, but can also be done on raw DRM devices.
+However, this is beyond the scope of this man-page. You may have a
+look at other mesa3D 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
+.Xr drm-intel 7 ,
+.Xr drm-radeon 7
+and
+.Xr drm-nouveau 7 .
+However, the
+.Xr drm-prime 7
+infrastructure and the generic gem API as described here allow
+display-managers to handle graphics-buffers and render-clients
+without any deeper knowledge of the GPU that is used. Moreover, it
+allows to move objects between GPUs and implement complex
+display-servers that don't do any rendering on their own. See its
+man-page for more information.
+.Sh EXAMPLES
+This section includes examples for basic memory-management
+tasks.
+.Ss Dumb-Buffers
+This examples shows how to create a dumb-buffer via the generic
+DRM API. This is driver-independent (as long as the driver
+supports dumb-buffers) and provides memory-mapped buffers that can
+be used for scanout. This example creates a full-HD 1920x1080
+buffer with 32 bits-per-pixel and a color-depth of 24 bits. The
+buffer is then bound to a framebuffer which can be used for
+scanout with the KMS API (see
+.Xr drm-kms 7 ) .
+.Bd -literal
+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);
+.Ed
+.Sh REPORTING BUGS
+Bugs in this manual should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm 7 ,
+.Xr drm-kms 7 ,
+.Xr drm-prime 7 ,
+.Xr drmAvailable 3 ,
+.Xr drmOpen 3 ,
+.Xr drm-intel 7 ,
+.Xr drm-radeon 7 ,
+.Xr drm-nouveau 7
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com
diff --git a/lib/libdrm/man/drm.7 b/lib/libdrm/man/drm.7
new file mode 100644
index 000000000..bbd3b40ef
--- /dev/null
+++ b/lib/libdrm/man/drm.7
@@ -0,0 +1,110 @@
+.\" automatically generated with
+.\" docbook2mdoc drm.xml > drm.7
+.Dd September 2012
+.Dt DRM 7
+.Os
+.Sh NAME
+.Nm drm
+.Nd Direct Rendering Manager
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Sh DESCRIPTION
+The
+.Em Direct Rendering Manager
+(DRM) is a framework
+to manage
+.Em Graphics Processing Units
+(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.
+.Pp
+In earlier days, the kernel framework was solely used to provide raw
+hardware access to privileged user-space processes which implement
+all the hardware abstraction layers. But more and more tasks were
+moved into the kernel. All these interfaces are based on
+.Xr ioctl 2
+commands on the DRM character device. The
+.Em libdrm
+library provides wrappers for these system-calls and many helpers to
+simplify the API.
+.Pp
+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
+.Pa /dev/dri/card0
+and can be accessed with
+.Xr open 2
+and
+.Xr close 2 .
+However, it still depends on the graphics driver which interfaces are
+available on these devices. If an interface is not available, the
+syscalls will fail with
+.Ql EINVAL .
+.Ss Authentication
+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
+.Xr drmSetMaster 3
+for information on how to become DRM-Master and what the limitations
+are. Other DRM users can be authenticated to the DRM-Master via
+.Xr drmAuthMagic 3
+so they can perform buffer allocations and rendering.
+.Ss Mode-Setting
+Managing connected monitors and displays and changing the current
+modes is called
+.Em Mode-Setting .
+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
+.Em Kernel Mode Setting
+(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
+.Xr drm-kms 7
+for more.
+.Ss Memory Management
+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
+.Em Translation Table Manager
+(TTM) and the
+.Em Graphics Execution Manager
+(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
+.Em libgbm
+(Graphics Buffer Manager) from the
+.Em mesa-project .
+For more information on DRM
+memory-management, see
+.Xr drm-memory 7 .
+.Sh REPORTING BUGS
+Bugs in this manual should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm-kms 7 ,
+.Xr drm-memory 7 ,
+.Xr drmSetMaster 3 ,
+.Xr drmAuthMagic 3 ,
+.Xr drmAvailable 3 ,
+.Xr drmOpen 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com
diff --git a/lib/libdrm/man/drmAvailable.3 b/lib/libdrm/man/drmAvailable.3
new file mode 100644
index 000000000..ae08cb91b
--- /dev/null
+++ b/lib/libdrm/man/drmAvailable.3
@@ -0,0 +1,37 @@
+.\" automatically generated with
+.\" docbook2mdoc drmAvailable.xml > drmAvailable.3
+.Dd September 2012
+.Dt DRMAVAILABLE 3
+.Os
+.Sh NAME
+.Nm drmAvailable
+.Nd determine whether a DRM kernel driver has been loaded
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Ft int
+.Fo drmAvailable
+.Fa void
+.Fc
+.Sh DESCRIPTION
+.Fn drmAvailable
+allows the caller to determine
+whether a kernel DRM driver is loaded.
+.Sh RETURN VALUE
+.Fn drmAvailable
+returns 1 if a DRM driver is
+currently loaded. Otherwise 0 is returned.
+.Sh REPORTING BUGS
+Bugs in this function should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm 7 ,
+.Xr drmOpen 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com
diff --git a/lib/libdrm/man/drmHandleEvent.3 b/lib/libdrm/man/drmHandleEvent.3
new file mode 100644
index 000000000..da32723b7
--- /dev/null
+++ b/lib/libdrm/man/drmHandleEvent.3
@@ -0,0 +1,68 @@
+.\" automatically generated with
+.\" docbook2mdoc drmHandleEvent.xml > drmHandleEvent.3
+.Dd September 2012
+.Dt DRMHANDLEEVENT 3
+.Os
+.Sh NAME
+.Nm drmHandleEvent
+.Nd read and process pending DRM events
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Ft int
+.Fo drmHandleEvent
+.Fa "int fd"
+.Fa "drmEventContextPtr evctx"
+.Fc
+.Sh DESCRIPTION
+.Fn drmHandleEvent
+processes outstanding DRM events
+on the DRM file-descriptor passed as
+.Fa fd .
+This
+function should be called after the DRM file-descriptor has polled
+readable; it will read the events and use the passed-in
+.Fa evctx
+structure to call function pointers
+with the parameters noted below:
+.Bd -literal
+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;
+.Ed
+.Sh RETURN VALUE
+.Fn drmHandleEvent
+returns
+.Ql 0
+on
+success, or if there is no data to read from the file-descriptor.
+Returns
+.Ql -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
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm 7 ,
+.Xr drm-kms 7 ,
+.Xr drmModePageFlip 3 ,
+.Xr drmWaitVBlank 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com
diff --git a/lib/libdrm/man/drmModeGetResources.3 b/lib/libdrm/man/drmModeGetResources.3
new file mode 100644
index 000000000..03a74956c
--- /dev/null
+++ b/lib/libdrm/man/drmModeGetResources.3
@@ -0,0 +1,114 @@
+.\" automatically generated with
+.\" docbook2mdoc drmModeGetResources.xml > drmModeGetResources.3
+.Dd September 2012
+.Dt DRMMODEGETRESOURCES 3
+.Os
+.Sh NAME
+.Nm drmModeGetResources
+.Nd retrieve current display configuration information
+.Sh SYNOPSIS
+.Fd #include <xf86drm.h>
+.Fd #include <xf86drmMode.h>
+.Ft drmModeResPtr
+.Fo drmModeGetResources
+.Fa "int fd"
+.Fc
+.Sh DESCRIPTION
+.Fn drmModeGetResources
+allocates, populates, and
+returns a
+.Vt drmModeRes
+structure containing
+information about the current display configuration. The structure
+contains the following fields:
+.Bd -literal
+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;
+.Ed
+.Pp
+The
+.Fa count_fbs
+and
+.Fa 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).
+.Pp
+The
+.Fa count_crtcs
+and
+.Fa 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).
+.Pp
+The
+.Fa count_connectors
+and
+.Fa 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).
+.Pp
+The
+.Fa count_encoders
+and
+.Fa 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.
+.Pp
+The
+.Fa min*
+and
+.Fa max*
+fields indicate the maximum size of a
+framebuffer for this device (i.e., the scanout size limit).
+.Sh RETURN VALUE
+.Fn drmModeGetResources
+returns a drmModeRes
+structure pointer on success,
+.Ql NULL
+on failure. The
+returned structure must be freed with
+.Xr drmModeFreeResources 3 .
+.Sh REPORTING BUGS
+Bugs in this function should be reported to
+https://bugs.freedesktop.org/enter_bug.cgi?product=DRI&component=libdrm
+under the "DRI" product, component "libdrm"
+.Sh SEE ALSO
+.Xr drm 7 ,
+.Xr drm-kms 7 ,
+.Xr drmModeGetFB 3 ,
+.Xr drmModeAddFB 3 ,
+.Xr drmModeAddFB2 3 ,
+.Xr drmModeRmFB 3 ,
+.Xr drmModeDirtyFB 3 ,
+.Xr drmModeGetCrtc 3 ,
+.Xr drmModeSetCrtc 3 ,
+.Xr drmModeGetEncoder 3 ,
+.Xr drmModeGetConnector 3
+.Sh AUTHORS
+.An -nosplit
+.Sy Direct Rendering Manager
+.Pp
+.Sy libdrm
+.An -split
+Developer:
+.An David Herrmann Aq Mt dh.herrmann@googlemail.com