[PATCH 2/2] drm/doc: Update docs about device instance setup

[Daniel Vetter]

On Mon, Aug 10, 2015 at 02:34:18PM +0200, Thierry Reding wrote:
> On Mon, Aug 10, 2015 at 02:07:49PM +0200, Daniel Vetter wrote:
> > On Mon, Aug 10, 2015 at 01:59:07PM +0200, Thierry Reding wrote:
> > > On Mon, Aug 10, 2015 at 11:55:38AM +0200, Daniel Vetter wrote:
> > > > ->load is depracated, bus functionst are deprecated and everyone
> > > > should use drm_dev_alloc&register.
> > > 
> > > Why would you want to deprecated ->load()? Even if you use
> > > drm_dev_alloc() and drm_dev_register(), there's still use for ->load()
> > > because it gives you the subsystem-level initialization entry point.
> > 
> > ->load is called after the drm /dev node is registered and hence you can't
> > really do any driver setup in there without risking races. We paper over
> > that using drm_global_mutex, but that doesn't work for any other
> > driver/userspace interface like sysfs/debugfs because of deadlocks.
> > 
> > And we can't just reorder ->load to happen before the /dev nodes are
> > registered because a lot of drivers would fall over if we do that.
> > 
> > This is typical midlayer fail where the core calls into the driver instead
> > of the other way round.
> 
> Okay, but then if we're going to deprecate ->load(), I think we should
> also come up with an upgrade plan. As it is, this just says that users
> shouldn't do ->load(), but it doesn't tell them what to do instead.
> 
> Would the proper procedure be to fix drivers so that ->load() can be
> called between drm_dev_alloc() and drm_dev_register()? I suppose we
> could add some sort of (temporary) flag for drivers to signal this and
> then have drm_dev_register() call ->load() at the right time. If drivers
> don't support it, we can keep what we have.
> 
> That, of course, doesn't get rid of the midlayer, so perhaps a better
> way forward would be to tell driver writers that they should be doing
> subsystem-level setup between drm_dev_alloc() and drm_dev_register().

That's exactly what this patch tries to accomplish by updating the
kerneldoc and docbook. New sequence should be

device_probe_callback_or_whatever()
{
	drm_dev_alloc();

	... driver init code ...

	drm_dev_register();

	return 0;
}

Unfortunately the kerneldoc markdown isn't merged yet, otherwise I'd have
added this code snippet to the docs too.

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch