From 065a50ed3ef75cb265e12e3e1b615db0835150bc Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Sun, 2 Dec 2012 00:09:18 +0100 Subject: drm/doc: integrate drm_crtc.c kerneldoc And do a quick pass to adjust them to the last few (years?) of changes ... This time actually compile-tested ;-) Reviewed-by: Rob Clark 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 4ee2304f82f9..caab791b0a6c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1609,6 +1609,10 @@ void intel_crt_init(struct drm_device *dev) make its properties available to applications. + + KMS API Functions +!Edrivers/gpu/drm/drm_crtc.c + -- cgit v1.2.1 From 5d7a951537927555fa1286a338e1b91c3b8b7445 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 4 Jan 2013 22:31:20 +0100 Subject: drm/doc: updates for new framebuffer lifetime rules Now that framebuffer are reference-counted for all use-sites, update the documentation accordingly to stress the new rules for initialization and teardown. Also add a short paragraph about the implications for drivers of the new locking rules. Reviewed-by: Rob Clark Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 59 ++++++++++++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 14 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index caab791b0a6c..6c11d77c8d02 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -978,10 +978,25 @@ int max_width, max_height; If the parameters are deemed valid, drivers then create, initialize and return an instance of struct drm_framebuffer. If desired the instance can be embedded in a larger driver-specific - structure. The new instance is initialized with a call to - drm_framebuffer_init which takes a pointer to DRM - frame buffer operations (struct - drm_framebuffer_funcs). Frame buffer operations are + structure. Drivers must fill its width, + height, pitches, + offsets, depth, + bits_per_pixel and + pixel_format fields from the values passed + through the drm_mode_fb_cmd2 argument. They + should call the drm_helper_mode_fill_fb_struct + helper function to do so. + + + + The initailization 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 + publishes the framebuffer and so from this point on it can be accessed + concurrently from other threads. Hence it must be the last step in the + driver's framebuffer initialization sequence. Frame buffer operations + are int (*create_handle)(struct drm_framebuffer *fb, @@ -1022,16 +1037,16 @@ int max_width, max_height; - After initializing the drm_framebuffer - instance drivers must fill its width, - height, pitches, - offsets, depth, - bits_per_pixel and - pixel_format fields from the values passed - through the drm_mode_fb_cmd2 argument. They - should call the drm_helper_mode_fill_fb_struct - helper function to do so. - + The lifetime of a drm framebuffer is controlled with a reference count, + drivers can grab additional references with + drm_framebuffer_reference and 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 + drm_framebuffer is embedded into the fbdev + helper struct) drivers can manually clean up a framebuffer at module + unload time with + drm_framebuffer_unregister_private. Output Polling @@ -1043,6 +1058,22 @@ int max_width, max_height; operation. + + Locking + + Beside some lookup structures with their own locking (which is hidden + behind the interface functions) most of the modeset state is protected + by the dev-<mode_config.lock mutex and additionally + per-crtc locks to allow cursor updates, pageflips and similar operations + to occur concurrently with background tasks like output detection. + Operations which cross domains like a full modeset always grab all + locks. Drivers there need to protect resources shared between crtcs with + additional locking. They also need to be careful to always grab the + relevant crtc locks if a modset functions touches crtc state, e.g. for + load detection (which does only grab the mode_config.lock + to allow concurrent screen updates on live crtcs). + + -- cgit v1.2.1 From 89177644a7b6306e6084a89eab7e290f4bfef397 Mon Sep 17 00:00:00 2001 From: Aaron Plattner Date: Tue, 15 Jan 2013 20:47:42 +0000 Subject: drm: add prime helpers Instead of reimplementing all of the dma_buf functionality in every driver, create helpers drm_prime_import and drm_prime_export that implement them in terms of new, lower-level hook functions: gem_prime_pin: callback when a buffer is created, used to pin buffers into GTT gem_prime_get_sg_table: convert a drm_gem_object to an sg_table for export gem_prime_import_sg_table: convert an sg_table into a drm_gem_object gem_prime_vmap, gem_prime_vunmap: map and unmap an object These hooks are optional; drivers can opt in by using drm_gem_prime_import and drm_gem_prime_export as the .gem_prime_import and .gem_prime_export fields of struct drm_driver. v2: - Drop .begin_cpu_access. None of the drivers this code replaces implemented it. Having it here was a leftover from when I was trying to include i915 in this rework. - Use mutex_lock instead of mutex_lock_interruptible, as these three drivers did. This patch series shouldn't change that behavior. - Rename helpers to gem_prime_get_sg_table and gem_prime_import_sg_table. Rename struct sg_table* variables to 'sgt' for clarity. - Update drm.tmpl for these new hooks. v3: - Pass the vaddr down to the driver. This lets drivers that just call vunmap on the pointer avoid having to store the pointer in their GEM private structures. - Move documentation into a /** DOC */ comment in drm_prime.c and include it in drm.tmpl with a !P line. I tried to use !F lines to include documentation of the individual functions from drmP.h, but the docproc / kernel-doc scripts barf on that file, so hopefully this is good enough for now. - apply refcount fix from commit be8a42ae60addd8b6092535c11b42d099d6470ec ("drm/prime: drop reference on imported dma-buf come from gem") Signed-off-by: Aaron Plattner Cc: Daniel Vetter Cc: David Airlie Signed-off-by: Dave Airlie --- 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 6c11d77c8d02..b26de523ab70 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -743,6 +743,10 @@ char *date; 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 Objects Mapping -- cgit v1.2.1 From 207fd32970b1def91b11ae28f6bebffc792db714 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Sun, 20 Jan 2013 22:13:14 +0100 Subject: drm/fb-helper: improve kerneldoc Now that the fbdev helper interface for drivers is trimmed down, update the kerneldoc for all the remaining exported functions. I've tried to beat the DocBook a bit by reordering the function references a bit into a more sensible ordering. But that didn't work out at all. Hence just extend the in-code DOC: section a bit. Also remove the LOCKING: sections - especially for the setup functions they're totally bogus. But that's not a documentation problem, but simply an artifact of the current rather hazardous locking around drm init and even more so around fbdev setup ... v2: Some further improvements: - Also add documentation for drm_fb_helper_single_add_all_connectors, Dave Airlie didn't want me to kill this one from the fb helper interface. - Update docs for drm_fb_helper_fill_var/fix - they should be used from the driver's ->fb_probe callback to setup the fbdev info structure. - Clarify what the ->fb_probe callback should all do - it needs to setup both the fbdev info and allocate the drm framebuffer used as backing storage. - Add basic documentaation for the drm_fb_helper_funcs driver callback vfunc. v3: Implement clarifications Laurent Pinchart suggested in his review. v4: Fix another mispelling Laurent spotted. Cc: Laurent Pinchart Acked-by: Laurent Pinchart 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 b26de523ab70..51e1904ac4c7 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2143,6 +2143,7 @@ void intel_crt_init(struct drm_device *dev) fbdev Helper Functions Reference !Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers !Edrivers/gpu/drm/drm_fb_helper.c +!Iinclude/drm/drm_fb_helper.h Display Port Helper Functions Reference -- cgit v1.2.1 From 5e308591a887604ed4fca7e7fcd8fb18d8bdc459 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Mon, 14 Jan 2013 09:00:31 +0100 Subject: drm: Add EDID helper documentation Add a reference section about the EDID helper functions to the DRM documentation. Signed-off-by: Thierry Reding Reviewed-by: Alex Deucher --- 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 51e1904ac4c7..003c18a01fb6 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -2151,6 +2151,10 @@ void intel_crt_init(struct drm_device *dev) !Iinclude/drm/drm_dp_helper.h !Edrivers/gpu/drm/drm_dp_helper.c + + EDID Helper Functions Reference +!Edrivers/gpu/drm/drm_edid.c + -- cgit v1.2.1 From 8cf1e9811471f2910fa38dc1b28e1789080ba961 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Wed, 13 Feb 2013 16:08:33 +0100 Subject: drm: Add consistency check for page-flipping Driver implementations of the drm_crtc's .page_flip() function are required to update the crtc->fb field on success to reflect that the new framebuffer is now in use. This is important to keep reference counting on the framebuffers balanced. While at it, document this requirement to keep others from falling into the same trap. Suggested-by: Daniel Vetter Signed-off-by: Thierry Reding Reviewed-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 51e1904ac4c7..a6428ddfcfc2 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -1160,6 +1160,12 @@ int max_width, max_height; without waiting for rendering or page flip to complete and must block any new rendering to the frame buffer until the page flip completes. + + If a page flip can be successfully scheduled the driver must set the + drm_crtc-<fb field to the new framebuffer pointed to + by fb. This is important so that the reference counting + on framebuffers stays balanced. + If a page flip is already pending, the page_flip operation must return -- cgit v1.2.1