[PATCH -fixes 0/3] Documentation updates

[PATCH -fixes 0/3] Documentation updates

[Thomas Hellstrom]

A couple of updates to various interface docs

In-Reply-To: 

[PATCH 1/3] drm: Update the DRM_IOCTL_MODE_CURSOR documentation

[Thomas Hellstrom]

Document that DRM_IOCTL_MODE_CURSOR needs to be called in order to
guarantee that the cursor bo contents is updated to the screen.
This was agreed upon on the DRI mailing list.

Signed-off-by: Thomas Hellstrom <thellstrom@vmware.com>
---
 include/drm/drm_mode.h |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/include/drm/drm_mode.h b/include/drm/drm_mode.h
index d30bedf..9006b93 100644
--- a/include/drm/drm_mode.h
+++ b/include/drm/drm_mode.h
@@ -291,6 +291,11 @@ struct drm_mode_mode_cmd {
  *    crtc
  *    x
  *    y
+ *
+ * The DRM_IOCTL_MODE_CURSOR ioctl needs to be called with the CURSOR_BO flag
+ * in order to guarantee that the cursor image is updated. The implementation
+ * is free to either update the cursor image when the bo contents change, or
+ * when the DRM_IOCTL_MODE_CURSOR ioctl is called.
  */
 struct drm_mode_cursor {
 	__u32 flags;
-- 
1.7.4.4

[PATCH 2/3] drm: Update the pageflip ioctl documentation

[Thomas Hellstrom]

The pageflip semantics documentation was tailored to Intel hardware, where
pageflips are done by banging on registers. Many GPUs have the possibilities
to send pageflips down the command stream, and the driver command submission
mechanism does not have to block in order to order page-flip and command
execution. Also remove the sync-to-vblank requirement. Some hardware doesn't
support it, and it might not be desired in all situations either.
I think all this was brought up on the DRI-devel email list on the pageflip
ioctl design discussion.

Signed-off-by: Thomas Hellstrom <thellstrom@vmware.com>
---
 include/drm/drm_mode.h |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/drm/drm_mode.h b/include/drm/drm_mode.h
index 9006b93..d88ef35 100644
--- a/include/drm/drm_mode.h
+++ b/include/drm/drm_mode.h
@@ -327,9 +327,9 @@ struct drm_mode_crtc_lut {
  * This ioctl will ask KMS to schedule a page flip for the specified
  * crtc.  Once any pending rendering targeting the specified fb (as of
  * ioctl time) has completed, the crtc will be reprogrammed to display
- * that fb after the next vertical refresh.  The ioctl returns
- * immediately, but subsequent rendering to the current fb will block
- * in the execbuffer ioctl until the page flip happens.  If a page
+ * that fb. The ioctl returns immediately, and subsequently queued rendering
+ * to any of the involved fbs will be ordered with the page flip so that it
+ * occurs after the page-flip is ececuted by the hardware. If a page
  * flip is already pending as the ioctl is called, EBUSY will be
  * returned.
  *
-- 
1.7.4.4

[PATCH 3/3] ttm: Update move_notify and swap_notify documentation.

[Thomas Hellstrom]

Update the documentation of these callbacks to reflect the TTM supported
way of setting up driver-private GPU maps, hoping to avoid the Radeon way
leaking into new drivers.

Signed-off-by: Thomas Hellstrom <thellstrom@vmware.com>
---
 include/drm/ttm/ttm_bo_driver.h |   14 ++++++++++++--
 1 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/include/drm/ttm/ttm_bo_driver.h b/include/drm/ttm/ttm_bo_driver.h
index 94eb143..42c3e64 100644
--- a/include/drm/ttm/ttm_bo_driver.h
+++ b/include/drm/ttm/ttm_bo_driver.h
@@ -439,7 +439,15 @@ struct ttm_bo_driver {
 	void *(*sync_obj_ref) (void *sync_obj);
 
 	/* hook to notify driver about a driver move so it
-	 * can do tiling things */
+	 * can do tiling things. This hook can be used to tear
+	 * down driver private GPU mappings from the BO. It should not,
+	 * however be used to set up such mappings, since TTM will not
+	 * call this hook when SYSTEM placed bos are populated with pages.
+	 * It's recommended that populating driver private GPU maps is
+	 * done from the command-submission code, where the driver has
+	 * a more detailed knowledge of exactly what GPU maps need
+	 * populating.
+	 */
 	void (*move_notify)(struct ttm_buffer_object *bo,
 			    struct ttm_mem_reg *new_mem);
 	/* notify the driver we are taking a fault on this BO
@@ -447,7 +455,9 @@ struct ttm_bo_driver {
 	int (*fault_reserve_notify)(struct ttm_buffer_object *bo);
 
 	/**
-	 * notify the driver that we're about to swap out this bo
+	 * notify the driver that we're about to swap out this bo.
+	 * Any driver private GPU maps pointing to the bo should be
+	 * teared down at this point.
 	 */
 	void (*swap_notify) (struct ttm_buffer_object *bo);
 
-- 
1.7.4.4

Re: [PATCH -fixes 0/3][RESEND] Documentation updates

[Thomas Hellstrom]

Dave,

Please pull this series into drm-fixes for 3.2.

Thanks,
Thomas


On 11/21/2011 01:08 PM, Thomas Hellstrom wrote:
> A couple of updates to various interface docs
>
> In-Reply-To:
>
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/dri-devel
>