diff options
| -rw-r--r-- | lib/libdrm/Makefile.bsd-wrapper | 23 | ||||
| -rw-r--r-- | lib/libdrm/man/drm-kms.7 | 296 | ||||
| -rw-r--r-- | lib/libdrm/man/drm-memory.7 | 432 | ||||
| -rw-r--r-- | lib/libdrm/man/drm.7 | 110 | ||||
| -rw-r--r-- | lib/libdrm/man/drmAvailable.3 | 37 | ||||
| -rw-r--r-- | lib/libdrm/man/drmHandleEvent.3 | 68 | ||||
| -rw-r--r-- | lib/libdrm/man/drmModeGetResources.3 | 114 |
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 |