From 065a5027dca8e9383ac308de4310e8e850b0cafb Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 21 Jan 2014 12:01:41 +0100 Subject: drm/doc: Clarify the dumb object interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - This is _not_ a generic interface to create gem objects, but just an interface to make early boot services (like boot splash) with a generic KMS userspace driver possible. Hence it's better to move the documentation for this from the GEM section to the KMS section, next to the creation of framebuffer objects. - Make it really clear that the returned handle isn't necessarily a GEM object (it can also be e.g. a TTM handle when running on top of vmwgfx). - Add a paragraph to make it clear that this is just for unaccelarated userspace - gpu drivers need to have their own buffer object creation ioctl which is hardware specific. v2: Clarify that the documentation doesn't just apply to GEM-based drivers only but is now generally valid, as suggested by David. v3: Polish the intro sentence a bit and one s/objects/handles/ for clarification, both suggested by Laurent. v4: More text polish from Laurent's review. v5: More typo fixes from Dieter. Cc: Dieter Nützel Cc: David Herrmann Cc: Laurent Pinchart Acked-by: Laurent Pinchart Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 133 ++++++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 61 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d289022..f2d0f5b89194 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -829,62 +829,6 @@ char *date; faults can implement their own mmap file operation handler. - - Dumb GEM Objects - - The GEM API doesn't standardize GEM objects creation and leaves it to - driver-specific ioctls. While not an issue for full-fledged graphics - stacks that include device-specific userspace components (in libdrm for - instance), this limit makes DRM-based early boot graphics unnecessarily - complex. - - - Dumb GEM objects partly alleviate the problem by providing a standard - API to create dumb buffers suitable for scanout, which can then be used - to create KMS frame buffers. - - - To support dumb GEM objects drivers must implement the - dumb_create, - dumb_destroy and - dumb_map_offset operations. - - - - int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, - struct drm_mode_create_dumb *args); - - The dumb_create operation creates a GEM - object suitable for scanout based on the width, height and depth - from the struct drm_mode_create_dumb - argument. It fills the argument's handle, - pitch and size - fields with a handle for the newly created GEM object and its line - pitch and size in bytes. - - - - int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle); - - The dumb_destroy operation destroys a dumb - GEM object created by dumb_create. - - - - int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle, uint64_t *offset); - - The dumb_map_offset operation associates an - mmap fake offset with the GEM object given by the handle and returns - it. Drivers must use the - drm_gem_create_mmap_offset function to - associate the fake offset as described in - . - - - - Memory Coherency @@ -968,9 +912,11 @@ int max_width, max_height; Frame buffers rely on the underneath memory manager for low-level memory operations. When creating a frame buffer applications pass a memory handle (or a list of memory handles for multi-planar formats) through - the drm_mode_fb_cmd2 argument. This document - assumes that the driver uses GEM, those handles thus reference GEM - objects. + the drm_mode_fb_cmd2 argument. For drivers using + GEM as their userspace buffer management interface this would be a GEM + handle. Drivers are however free to use their own backing storage object + handles, e.g. vmwgfx directly exposes special TTM handles to userspace + and so expects TTM handles in the create ioctl and not GEM handles. Drivers must first validate the requested frame buffer parameters passed @@ -992,7 +938,7 @@ int max_width, max_height; - The initailization of the new framebuffer instance is finalized with a + The initialization of the new framebuffer instance is finalized with a call to drm_framebuffer_init which takes a pointer to DRM frame buffer operations (struct drm_framebuffer_funcs). Note that this function @@ -1051,6 +997,71 @@ int max_width, max_height; unload time with drm_framebuffer_unregister_private. + + Dumb Buffer Objects + + The KMS API doesn't standardize backing storage object creation and + leaves it to driver-specific ioctls. Furthermore actually creating a + buffer object even for GEM-based drivers is done through a + driver-specific ioctl - GEM only has a common userspace interface for + sharing and destroying objects. While not an issue for full-fledged + graphics stacks that include device-specific userspace components (in + libdrm for instance), this limit makes DRM-based early boot graphics + unnecessarily complex. + + + Dumb objects partly alleviate the problem by providing a standard + API to create dumb buffers suitable for scanout, which can then be used + to create KMS frame buffers. + + + To support dumb objects drivers must implement the + dumb_create, + dumb_destroy and + dumb_map_offset operations. + + + + int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args); + + The dumb_create operation creates a driver + object (GEM or TTM handle) suitable for scanout based on the + width, height and depth from the struct + drm_mode_create_dumb argument. It fills the + argument's handle, + pitch and size + fields with a handle for the newly created object and its line + pitch and size in bytes. + + + + int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle); + + The dumb_destroy operation destroys a dumb + object created by dumb_create. + + + + int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset); + + The dumb_map_offset operation associates an + mmap fake offset with the object given by the handle and returns + it. Drivers must use the + drm_gem_create_mmap_offset function to + associate the fake offset as described in + . + + + + + Note that dumb objects may not be used for gpu acceleration, as has been + attempted on some ARM embedded platforms. Such drivers really must have + a hardware-specific ioctl to allocate suitable buffer objects. + + Output Polling void (*output_poll_changed)(struct drm_device *dev); @@ -2134,7 +2145,7 @@ void intel_crt_init(struct drm_device *dev) set the display_info width_mm and height_mm fields if they haven't been set - already (for instance at initilization time when a fixed-size panel is + already (for instance at initialization time when a fixed-size panel is attached to the connector). The mode width_mm and height_mm fields are only used internally during EDID parsing and should not be set when creating modes manually. -- cgit v1.2.3 From 89d61fc0f5d384f07f3e93af2bb52009ce26283a Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 21 Jan 2014 12:39:00 +0100 Subject: drm/doc: Clean up and integrate kerneldoc for drm_gem.c Fairly incomplete, but at least a start. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index f2d0f5b89194..1cdca9ad8844 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -868,7 +868,11 @@ char *date; abstracted from the client in libdrm. - + + GEM Function Reference +!Edrivers/gpu/drm/drm_gem.c + + -- cgit v1.2.3 From 00153aebc22b8120ab18012e383c98e97fb509e4 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 21 Jan 2014 12:51:43 +0100 Subject: drm/doc: Remove from rendernode docs The stylesheet doesn't allow this in normal paragraphs. Cc: David Herrmann Acked-by: David Herrmann Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 1cdca9ad8844..0d2adf9825e9 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2673,8 +2673,8 @@ int (*resume) (struct drm_device *); DRM core provides multiple character-devices for user-space to use. Depending on which device is opened, user-space can perform a different set of operations (mainly ioctls). The primary node is always created - and called card<num>. Additionally, a currently - unused control node, called controlD<num> is also + and called card<num>. Additionally, a currently + unused control node, called controlD<num> is also created. The primary node provides all legacy operations and historically was the only interface used by userspace. With KMS, the control node was introduced. However, the planned KMS control interface @@ -2689,21 +2689,21 @@ int (*resume) (struct drm_device *); nodes were introduced. Render nodes solely serve render clients, that is, no modesetting or privileged ioctls can be issued on render nodes. Only non-global rendering commands are allowed. If a driver supports - render nodes, it must advertise it via the DRIVER_RENDER + render nodes, it must advertise it via the DRIVER_RENDER DRM driver capability. If not supported, the primary node must be used for render clients together with the legacy drmAuth authentication procedure. If a driver advertises render node support, DRM core will create a - separate render node called renderD<num>. There will + separate render node called renderD<num>. There will be one render node per device. No ioctls except PRIME-related ioctls - will be allowed on this node. Especially GEM_OPEN will be + will be allowed on this node. Especially GEM_OPEN will be explicitly prohibited. Render nodes are designed to avoid the buffer-leaks, which occur if clients guess the flink names or mmap offsets on the legacy interface. Additionally to this basic interface, drivers must mark their driver-dependent render-only ioctls as - DRM_RENDER_ALLOW so render clients can use them. Driver + DRM_RENDER_ALLOW so render clients can use them. Driver authors must be careful not to allow any privileged ioctls on render nodes. -- cgit v1.2.3 From 3519f70ee7c1d786ef08a977c241128efc291227 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 12:21:16 +0100 Subject: drm/doc: Reorganize driver documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split up the DocBook into the core drm part and a 2nd part for driver documentation. As an example add a very (very!) basic skeleton for i915. v1: Typo fixes from Dieter. Cc: Dieter Nützel Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 80 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 73 insertions(+), 7 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 0d2adf9825e9..e377b88304ef 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -60,7 +60,15 @@ - + + DRM Core + + + This first part of the DRM Developer's Guide documents core DRM code, + helper libraries for writting drivers and generic userspace interfaces + exposed by DRM drivers. + + Introduction @@ -2764,15 +2772,73 @@ int (*resume) (struct drm_device *); + + + DRM Drivers - + + + This second part of the DRM Developer's Guide documents driver code, + implementation details and also all the driver-specific userspace + interfaces. Especially since all hardware-acceleration interfaces to + userspace are driver specific for efficiency and other reasons these + interfaces can be rather substantial. Hence every driver has its own + chapter. + + - - DRM Driver API + + drm/i915 Intel GFX Driver - Include auto-generated API reference here (need to reference it - from paragraphs above too). + The drm/i915 driver supports all (with the exception of some very early + models) integrated GFX chipsets with both Intel display and rendering + blocks. This excludes a set of SoC platforms with an SGX rendering unit, + those have basic support through the gma500 drm driver. - + + Display Hardware Handling + + This section covers everything related to the display hardware including + the mode setting infrastructure, plane, sprite and cursor handling and + display, output probing and related topics. + + + Mode Setting Infrastructure + + The i915 driver is thus far the only DRM driver which doesn't use the + common DRM helper code to implement mode setting sequences. Thus it + has its own tailor-made infrastructure for executing a display + configuration change. + + + + Plane Configuration + + This section covers plane configuration and composition with the + primary plane, sprites, cursors and overlays. This includes the + infrastructure to do atomic vsync'ed updates of all this state and + also tightly coupled topics like watermark setup and computation, + framebuffer compression and panel self refresh. + + + + Output Probing + + This section covers output probing and related infrastructure like the + hotplug interrupt storm detection and mitigation code. Note that the + i915 driver still uses most of the common DRM helper code for output + probing, so those sections fully apply. + + + + + Memory Management and Command Submission + + This sections covers all things related to the GEM implementation in the + i915 driver. + + + + -- cgit v1.2.3 From 4c5acf3cc8423c90f620e578f14181a56fa7fb4e Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 12:28:42 +0100 Subject: drm/doc: Move the vma offset manager to the right spot Currently it's sitting in the mode setting helper section, which isn't quite right. Looks much better in the memory management section next to TTM and GEM. Cc: David Herrmann Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index e377b88304ef..2def6f3a9061 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -881,6 +881,12 @@ char *date; !Edrivers/gpu/drm/drm_gem.c + + VMA Offset Manager +!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager +!Edrivers/gpu/drm/drm_vma_manager.c +!Iinclude/drm/drm_vma_manager.h + @@ -2218,12 +2224,6 @@ void intel_crt_init(struct drm_device *dev) !Iinclude/drm/drm_flip_work.h !Edrivers/gpu/drm/drm_flip_work.c - - VMA Offset Manager -!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager -!Edrivers/gpu/drm/drm_vma_manager.c -!Iinclude/drm/drm_vma_manager.h - -- cgit v1.2.3 From 1aa12258d6056e47cfe49eb13cc7b652f7dab956 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 12:33:22 +0100 Subject: drm/doc: Remove the "command submissin and fencing" section This should be done in the driver chapter instead. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 2def6f3a9061..750ba8fb496a 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2585,16 +2585,6 @@ int num_ioctls; - - Command submission & fencing - - This should cover a few device-specific command submission - implementations. - - - - - Suspend/Resume -- cgit v1.2.3 From e1f8ebdcc230a9ff9e9e17707c22a5f0a5a885ee Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 16:32:47 +0100 Subject: drm/doc: No more drm perf counters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Those all died with commit 0111be42186fc5461b9e9d579014c70869ab3152 Author: Ville Syrjälä Date: Fri Oct 4 14:53:41 2013 +0300 drm: Kill drm perf counter leftovers Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 750ba8fb496a..26539ee3c63e 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -272,8 +272,8 @@ char *date; The load method is the driver and device initialization entry point. The method is responsible for allocating and - initializing driver private data, specifying supported performance - counters, performing resource allocation and mapping (e.g. acquiring + initializing driver private data, performing resource allocation and + mapping (e.g. acquiring clocks, mapping registers or allocating command buffers), initializing the memory manager (), installing the IRQ handler (), setting up @@ -303,7 +303,7 @@ char *date; their load method called with flags to 0. - Driver Private & Performance Counters + Driver Private Data The driver private hangs off the main drm_device structure and can be used for @@ -315,14 +315,6 @@ char *date; drm_device.dev_priv set to NULL when the driver is unloaded. - - DRM supports several counters which were used for rough performance - characterization. This stat counter system is deprecated and should not - be used. If performance monitoring is desired, the developer should - investigate and potentially enhance the kernel perf and tracing - infrastructure to export GPU related performance information for - consumption by performance monitoring tools and applications. - IRQ Registration -- cgit v1.2.3 From aa4cd9100e0709ea0bc6f85090188ace895e51fe Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 16:42:02 +0100 Subject: drm/doc: Document drm_helper_resume_force_mode Stumbled over while reviewing all occurences in the DRM doc talking about suspend/resume. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 26539ee3c63e..8e1052434bab 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1151,8 +1151,11 @@ int max_width, max_height; This operation is called with the mode config lock held. - FIXME: How should set_config interact with DPMS? If the CRTC is - suspended, should it be resumed? + Note that the drm core has no notion of restoring the mode setting + state after resume, since all resume handling is in the full + responsibility of the driver. The common mode setting helper library + though provides a helper which can be used for this: + drm_helper_resume_force_mode. -- cgit v1.2.3 From 4c6e2dfe08987b1e5d884939967037d68412d829 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 16:46:44 +0100 Subject: drm/doc: Hide legacy horrors better By consolidating them all into one section at the very end. And to make double-sure that no one gets confused start with a stern warning against any use of them. And prefix all subsections with "Legacy". Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 56 +++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 22 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 8e1052434bab..0a9407ae4025 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2579,32 +2579,44 @@ int num_ioctls; - - Suspend/Resume - - The DRM core provides some suspend/resume code, but drivers wanting full - suspend/resume support should provide save() and restore() functions. - These are called at suspend, hibernate, or resume time, and should perform - any state save or restore required by your device across suspend or - hibernate states. - - int (*suspend) (struct drm_device *, pm_message_t state); -int (*resume) (struct drm_device *); + Legacy Support Code - Those are legacy suspend and resume methods. New driver should use the - power management interface provided by their bus type (usually through - the struct device_driver dev_pm_ops) and set - these methods to NULL. + The section very brievely covers some of the old legacy support code which + is only used by old DRM drivers which have done a so-called shadow-attach + to the underlying device instead of registering as a real driver. This + also includes some of the old generic buffer mangement and command + submission code. Do not use any of this in new and modern drivers. - - - DMA services - - This should cover how DMA mapping etc. is supported by the core. - These functions are deprecated and should not be used. - + + Legacy Suspend/Resume + + The DRM core provides some suspend/resume code, but drivers wanting full + suspend/resume support should provide save() and restore() functions. + These are called at suspend, hibernate, or resume time, and should perform + any state save or restore required by your device across suspend or + hibernate states. + + int (*suspend) (struct drm_device *, pm_message_t state); + int (*resume) (struct drm_device *); + + Those are legacy suspend and resume methods which + only work with the legacy shadow-attach driver + registration functions. New driver should use the power management + interface provided by their bus type (usually through + the struct device_driver dev_pm_ops) and set + these methods to NULL. + + + + + Legacy DMA Services + + This should cover how DMA mapping etc. is supported by the core. + These functions are deprecated and should not be used. + + -- cgit v1.2.3 From 2d123f463669cb7b84b56aa00e073ce07fe7aff2 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 18:26:16 +0100 Subject: drm/docs: Include hdmi infoframe helper reference Thierry created such nice kerneldocs, it's a shame we've left them lingering! For the fun of it also add a bit of kerneldoc to the header so that we can also include that. Just in case someone adds kerneldoc in there. Cc: Thierry Reding Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 0a9407ae4025..0e0390ece122 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2219,6 +2219,17 @@ void intel_crt_init(struct drm_device *dev) !Iinclude/drm/drm_flip_work.h !Edrivers/gpu/drm/drm_flip_work.c + + HDMI Infoframes Helper Reference + + Strictly speaking this is not a DRM helper library but generally useable + by any driver interfacing with HDMI outputs like v4l or alsa drivers. + But it nicely fits into the overall topic of mode setting helper + libraries and hence is also included here. + +!Iinclude/linux/hdmi.h +!Edrivers/video/hdmi.c + -- cgit v1.2.3 From 251261db7f71829968a8fe80ae3f296fc96851cd Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 18:46:33 +0100 Subject: drm/doc: Clarify PRIME documentation PRIME fds aren't actually GEM fds but are (like the modeset API) independent of the underlying buffer manager, as long as that one uses uint32_t as handles. So move that entire section out of the GEM section and reword it a bit to clarify which parts of PRIME are generic, and which are the mandatory pieces for GEM drivers to correctly implement the GEM lifetime rules. The rewording mostly consists of not mixing up GEM, PRIME and DRM. I've considered adding some blurbs to the GEM object lifetime section about interactions with dma-bufs, but then dropped that. As long as drivers use the right helpers they should have this all implemented correctly and hence can be regarded as an implementation detail of the PRIME/GEM helpers. So no need to confuse driver writers with those tricky interactions. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 125 ++++++++++++++++++++++++----------------- 1 file changed, 74 insertions(+), 51 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 0e0390ece122..641db5cb656c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -697,55 +697,16 @@ char *date; respectively. The conversion is handled by the DRM core without any driver-specific support. - - Similar to global names, GEM file descriptors are also used to share GEM - objects across processes. They offer additional security: as file - descriptors must be explicitly sent over UNIX domain sockets to be shared - between applications, they can't be guessed like the globally unique GEM - names. - - - Drivers that support GEM file descriptors, also known as the DRM PRIME - API, must set the DRIVER_PRIME bit in the struct - drm_driver - driver_features field, and implement the - prime_handle_to_fd and - prime_fd_to_handle operations. - - - int (*prime_handle_to_fd)(struct drm_device *dev, - struct drm_file *file_priv, uint32_t handle, - uint32_t flags, int *prime_fd); - int (*prime_fd_to_handle)(struct drm_device *dev, - struct drm_file *file_priv, int prime_fd, - uint32_t *handle); - Those two operations convert a handle to a PRIME file descriptor and - vice versa. Drivers must use the kernel dma-buf buffer sharing framework - to manage the PRIME file descriptors. - - - While non-GEM drivers must implement the operations themselves, GEM - drivers must use the drm_gem_prime_handle_to_fd - and drm_gem_prime_fd_to_handle helper functions. - Those helpers rely on the driver - gem_prime_export and - gem_prime_import operations to create a dma-buf - instance from a GEM object (dma-buf exporter role) and to create a GEM - object from a dma-buf instance (dma-buf importer role). - - - struct dma_buf * (*gem_prime_export)(struct drm_device *dev, - struct drm_gem_object *obj, - int flags); - struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - struct dma_buf *dma_buf); - These two operations are mandatory for GEM drivers that support DRM - PRIME. - - - DRM PRIME Helper Functions Reference -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers - + + GEM also supports buffer sharing with dma-buf file descriptors through + PRIME. GEM-based drivers must use the provided helpers functions to + implement the exporting and importing correctly. See . + Since sharing file descriptors is inherently more secure than the + easily guessable and global GEM names it is the preferred buffer + sharing mechanism. Sharing buffers through GEM names is only supported + for legacy userspace. Furthermore PRIME also allows cross-device + buffer sharing since it is based on dma-bufs. + GEM Objects Mapping @@ -868,10 +829,10 @@ char *date; abstracted from the client in libdrm. - + GEM Function Reference !Edrivers/gpu/drm/drm_gem.c - + VMA Offset Manager @@ -879,6 +840,68 @@ char *date; !Edrivers/gpu/drm/drm_vma_manager.c !Iinclude/drm/drm_vma_manager.h + + PRIME Buffer Sharing + + PRIME is the cross device buffer sharing framework in drm, originally + created for the OPTIMUS range of multi-gpu platforms. To userspace + PRIME buffers are dma-buf based file descriptors. + + + Overview and Driver Interface + + Similar to GEM global names, PRIME file descriptors are + also used to share buffer objects across processes. They offer + additional security: as file descriptors must be explicitly sent over + UNIX domain sockets to be shared between applications, they can't be + guessed like the globally unique GEM names. + + + Drivers that support the PRIME + API must set the DRIVER_PRIME bit in the struct + drm_driver + driver_features field, and implement the + prime_handle_to_fd and + prime_fd_to_handle operations. + + + int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd); +int (*prime_fd_to_handle)(struct drm_device *dev, + struct drm_file *file_priv, int prime_fd, + uint32_t *handle); + Those two operations convert a handle to a PRIME file descriptor and + vice versa. Drivers must use the kernel dma-buf buffer sharing framework + to manage the PRIME file descriptors. Similar to the mode setting + API PRIME is agnostic to the underlying buffer object manager, as + long as handles are 32bit unsinged integers. + + + While non-GEM drivers must implement the operations themselves, GEM + drivers must use the drm_gem_prime_handle_to_fd + and drm_gem_prime_fd_to_handle helper functions. + Those helpers rely on the driver + gem_prime_export and + gem_prime_import operations to create a dma-buf + instance from a GEM object (dma-buf exporter role) and to create a GEM + object from a dma-buf instance (dma-buf importer role). + + + struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags); +struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, + struct dma_buf *dma_buf); + These two operations are mandatory for GEM drivers that support + PRIME. + + + + PRIME Helper Functions Reference +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + + -- cgit v1.2.3 From 39cc344acd414eda231f612325cf824b976025e5 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 19:16:30 +0100 Subject: drm/doc: Add PRIME function references For giant hilarity the DocBook reference overview is only generated when in a level 2 section, not in a level 3 section. So we need to move this up a bit as a side-by-side section to the main PRIME documentation. Whatever. To have a complete set of references add the missing kerneldoc for all functions exported to modules with the exception of the file private init/destroy functions - drivers have no business calling those, so let's just drop the EXPORT_SYMBOL instead. Also reflow the function parameters to align correctly and break at 80 chars - my OCD couldn't stand them while writing the kerneldoc ;-) Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 641db5cb656c..f83622ebda9d 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -898,10 +898,14 @@ struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, - PRIME Helper Functions Reference + PRIME Helper Functions !Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + + PRIME Function References +!Edrivers/gpu/drm/drm_prime.c + -- cgit v1.2.3 From 3a05700dc874f377b13e4368550e8c7228826ab4 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 22 Jan 2014 22:38:57 +0100 Subject: drm/doc: Update copyright I've done quite a bit of cleanups, clarifications and mostly integrating kerneldoc. So I guess I should add myself. Also split up the copyright notices per holder to make it clear which year ranges are covered. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index f83622ebda9d..dd2a955031a7 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -29,12 +29,26 @@ + + Daniel + Vetter + Contributions all over the place + + Intel Corporation +
+ daniel.vetter@ffwll.ch +
+ + 2008-2009 - 2012 + 2013-2014 Intel Corporation + + + 2012 Laurent Pinchart -- cgit v1.2.3 From 93110be69616df7dcd9cc3611e94400287fc26fb Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 23 Jan 2014 00:31:48 +0100 Subject: drm/doc: Overview documentation for drm_mm.c kerneldoc polish will follow in the next patch. Hopefully documenting the lru scan support a bit better spurs someone to give this a shot in the ttm eviction code. At least in i915 it helped quite a lot with memory thrashing on platforms where eviction was (we've fixed that too meanwhile) fairly expensive. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index dd2a955031a7..2ac018bfbddf 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -920,6 +920,17 @@ struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, PRIME Function References !Edrivers/gpu/drm/drm_prime.c + + DRM MM Range Allocator + + Overview +!Pdrivers/gpu/drm/drm_mm.c Overview + + + LRU Scan/Eviction Support +!Pdrivers/gpu/drm/drm_mm.c lru scan roaster + + -- cgit v1.2.3 From e18c04128faa2aa08547f8b73b9ecbf8fd6936af Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 23 Jan 2014 00:39:13 +0100 Subject: drm/doc: Add function reference documentation for drm_mm.c While at it do a tiny bit of interface cleanup and convert boolean return values to bool. With this patch all exported functions and inline helpers which are part of the drm_mm public interface are documented. Also drop superflous extern function modifiers since most of drm_mm.h doesn't use them - more consistent that way. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 2ac018bfbddf..d68bb0a2dc06 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -931,6 +931,11 @@ struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, !Pdrivers/gpu/drm/drm_mm.c lru scan roaster + + DRM MM Range Allocator Function References +!Edrivers/gpu/drm/drm_mm.c +!Iinclude/drm/drm_mm.h + -- cgit v1.2.3 From 3ec0db819315c765b3c7bbf7e9dee2fe1f186f47 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 23 Jan 2014 15:06:15 +0100 Subject: drm/doc: Integrate drm_modes.c kerneldoc And clean it up so that there's no kerneldoc warnings. There's still a lot to do with this one here. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index d68bb0a2dc06..50af3298ac1f 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -963,6 +963,10 @@ int max_width, max_height; Mode setting functions. + + Display Modes Function Reference +!Edrivers/gpu/drm/drm_modes.c + Frame Buffer Creation struct drm_framebuffer *(*fb_create)(struct drm_device *dev, -- cgit v1.2.3 From f5aabb978d1dcd850d329bcce6dc782bb8621984 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 23 Jan 2014 20:05:00 +0100 Subject: drm: polish function kerneldoc for drm_modes.[hc] - Tune down yelling RETURNS. - OCD align all the parameters the same. - Add missing kerneldoc, which also means that we need to include the kerneldoc from the drm_modes.h header now. - Add missing Returns: sections. - General polish and clarification - especially the kerneldoc for the mode creation helpers seems to have been some good specimen of copypasta gone wrong. All actual code changes have all been extracted into prep patches since there was simply too much to polish. v2: More polish for the command line modeline functions. Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 50af3298ac1f..4268cbe6f95c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -965,6 +965,7 @@ int max_width, max_height; Display Modes Function Reference +!Iinclude/drm/drm_modes.h !Edrivers/gpu/drm/drm_modes.c -- cgit v1.2.3 From 9ee984a5f735d6afc6f889e179b2e4b1f2ec335f Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 23 Jan 2014 21:57:37 +0100 Subject: drm/doc: Fix misplaced Oops. This is a regression from commit 5d7a951537927555fa1286a338e1b91c3b8b7445 Author: Daniel Vetter Date: Fri Jan 4 22:31:20 2013 +0100 drm/doc: updates for new framebuffer lifetime rules Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 4268cbe6f95c..9f5457ac0373 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1060,7 +1060,7 @@ int max_width, max_height; The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with - drm_framebuffer_reference and drop them + drm_framebuffer_referenceand drop them again with drm_framebuffer_unreference. For driver-private framebuffers for which the last reference is never dropped (e.g. for the fbdev framebuffer when the struct @@ -1068,6 +1068,7 @@ int max_width, max_height; helper struct) drivers can manually clean up a framebuffer at module unload time with drm_framebuffer_unregister_private. + Dumb Buffer Objects -- cgit v1.2.3 From 6efa1f2f5417e628572a75e667a9d8c63d21bd17 Mon Sep 17 00:00:00 2001 From: Matt Roper Date: Tue, 1 Apr 2014 15:22:43 -0700 Subject: drm/doc: Update plane documentation and add plane helper library Signed-off-by: Matt Roper Reviewed-by: Rob Clark --- Documentation/DocBook/drm.tmpl | 50 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 7 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 9f5457ac0373..702c4474919c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1194,7 +1194,7 @@ int max_width, max_height; pointer to CRTC functions. - + CRTC Operations Set Configuration @@ -1335,15 +1335,47 @@ int max_width, max_height; optionally scale it to a destination size. The result is then blended with or overlayed on top of a CRTC. + + The DRM core recognizes three types of planes: + + + DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary + planes are the planes operated upon by by CRTC modesetting and flipping + operations described in . + + + DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor + planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and + DRM_IOCTL_MODE_CURSOR2 ioctls. + + + DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. + Some drivers refer to these types of planes as "sprites" internally. + + + For compatibility with legacy userspace, only overlay planes are made + available to userspace by default. Userspace clients may set the + DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that + they wish to receive a universal plane list containing all plane types. + Plane Initialization - Planes are optional. To create a plane, a KMS drivers allocates and + To create a plane, a KMS drivers allocates and zeroes an instances of struct drm_plane (possibly as part of a larger structure) and registers it with a call - to drm_plane_init. The function takes a bitmask + to drm_universal_plane_init. The function takes a bitmask of the CRTCs that can be associated with the plane, a pointer to the - plane functions and a list of format supported formats. + plane functions, a list of format supported formats, and the type of + plane (primary, cursor, or overlay) being initialized. + + + Cursor and overlay planes are optional. All drivers should provide + one primary plane per CRTC (although this requirement may change in + the future); drivers that do not wish to provide special handling for + primary planes may make use of the helper functions described in + to create and register a + primary plane with standard capabilities. @@ -1774,7 +1806,7 @@ void intel_crt_init(struct drm_device *dev) Mode Setting Helper Functions - The CRTC, encoder and connector functions provided by the drivers + The plane, CRTC, encoder and connector functions provided by the drivers implement the DRM API. They're called by the DRM core and ioctl handlers to handle device state changes and configuration request. As implementing those functions often requires logic not specific to drivers, mid-layer @@ -1782,8 +1814,8 @@ void intel_crt_init(struct drm_device *dev) The DRM core contains one mid-layer implementation. The mid-layer provides - implementations of several CRTC, encoder and connector functions (called - from the top of the mid-layer) that pre-process requests and call + implementations of several plane, CRTC, encoder and connector functions + (called from the top of the mid-layer) that pre-process requests and call lower-level functions provided by the driver (at the bottom of the mid-layer). For instance, the drm_crtc_helper_set_config function can be used to @@ -2293,6 +2325,10 @@ void intel_crt_init(struct drm_device *dev) !Iinclude/linux/hdmi.h !Edrivers/video/hdmi.c + + Plane Helper Reference +!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers + -- cgit v1.2.3