[PATCH] i915: document DRM_I915_KMS option

[Jesse Barnes <jbarnes@virtuousgeek.org>]

On Friday, January 9, 2009 6:03 pm Dave Airlie wrote:
> > Also while testing this with xorg-server 1.4* I found out the 'pain'
> > means an broken X and a broken box since it broke the kernel as well and
> > the only way to get the box to live again was an hard reset. Please
> > clarify the 'pain' part too.
>
> There is no new enough userspace yet, so I can't say what version will
> have it, maybe I should mark enabled by default as experimental or
> something.
>
> If pain doesn't equate to doing something that will hurt, then I'm not
> sure what will, it actually will work for some people, so I can't say
> it will always be broken.
>
> I'll see if Jesse can provide some nicer wordings...

How about something like this?  It's deliberately vague about the exact
userspace requirements (basically saying you have to do your homework first)
but is otherwise pretty clear I think.

This patch adds more documentation for the DRM_I915_KMS option, warning
users to be sure any existing software they want to use with the i915 driver
is capable of using the new interfaces provided.

Signed-off-by: Jesse Barnes <jbarnes@virtuousgeek.org>

diff --git a/drivers/gpu/drm/Kconfig b/drivers/gpu/drm/Kconfig
index 5130b72..57edf29 100644
--- a/drivers/gpu/drm/Kconfig
+++ b/drivers/gpu/drm/Kconfig
@@ -83,15 +83,21 @@ config DRM_I915
 endchoice
 
 config DRM_I915_KMS
-	bool "Enable modesetting on intel by default"
+	bool "Enable kernel mode setting by default"
 	depends on DRM_I915
 	help
-	Choose this option if you want kernel modesetting enabled by default,
-	and you have a new enough userspace to support this. Running old
-	userspaces with this enabled will cause pain.  Note that this causes
-	the driver to bind to PCI devices, which precludes loading things
-	like intelfb.
+	Choose this option if you want kernel based mode setting enabled by
+	default (normally you have to pass "modeset=1" as a module parameter
+	to enable this feature).  When kernel mode setting is enabled, the
+	driver will support the mode setting ioctls defined in drm_mode.h
+	(which should be used through libdrm's xf86drmMode.h interface).
 
+	Note that when this option is enabled, it will conflict with other
+	drivers of this hardware such as intelfb or a non-kernel mode setting
+	enabled xf86-video-intel (which include all versions prior to 2.6),
+	and so could lead to bad behavior like memory corruption, non-functional
+	video output, and machine hangs.  So if you plan to use this feature
+	be sure your installed userspace software is compatible.
 
 config DRM_MGA
 	tristate "Matrox g200/g400"