From 6e3f797c9ae9bd381247e90907838da43f695306 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 28 Sep 2015 21:46:35 +0200 Subject: drm/doc: Update docs about device instance setup ->load is deprecated, bus functions are deprecated and everyone should use drm_dev_alloc®ister. So update the .tmpl (and pull a bunch of the overview docs into the sourcecode to increase chances that it'll stay in sync in the future) and add notes to functions which are deprecated. I didn't bother to clean up and document the unload sequence similarly since that one is still a bit a mess: drm_dev_unregister does way too much, drm_unplug_dev does what _unregister should be doing but then has the complication of promising something it doesn't actually do (it doesn't unplug existing open fds for instance, only prevents new ones). Motivated since I don't want to hunt every new driver for usage of drm_platform_init any more ;-) v2: Reword the deprecation note for ->load a bit, using Laurent's suggestion as an example (but making the wording a bit stronger even). Fix spelling in commit message. v3: More spelling fixes from Laurent. Cc: Laurent Pinchart Cc: David Herrmann Acked-by: David Herrmann (v2) Signed-off-by: Daniel Vetter Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 99 ++++++++---------------------------------- 1 file changed, 18 insertions(+), 81 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 30401f9..11f5bfb 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -138,14 +138,10 @@ At the core of every DRM driver is a drm_driver structure. Drivers typically statically initialize a drm_driver structure, - and then pass it to one of the drm_*_init() functions - to register it with the DRM subsystem. - - - Newer drivers that no longer require a drm_bus - structure can alternatively use the low-level device initialization and - registration functions such as drm_dev_alloc() and - drm_dev_register() directly. + and then pass it to drm_dev_alloc() to allocate a + device instance. After the device instance is fully initialized it can be + registered (which makes it accessible from userspace) using + drm_dev_register(). The drm_driver structure contains static @@ -296,83 +292,12 @@ char *date; - Device Registration - - A number of functions are provided to help with device registration. - The functions deal with PCI and platform devices, respectively. - -!Edrivers/gpu/drm/drm_pci.c -!Edrivers/gpu/drm/drm_platform.c - - New drivers that no longer rely on the services provided by the - drm_bus structure can call the low-level - device registration functions directly. The - drm_dev_alloc() function can be used to allocate - and initialize a new drm_device structure. - Drivers will typically want to perform some additional setup on this - structure, such as allocating driver-specific data and storing a - pointer to it in the DRM device's dev_private - field. Drivers should also set the device's unique name using the - drm_dev_set_unique() function. After it has been - set up a device can be registered with the DRM subsystem by calling - drm_dev_register(). This will cause the device to - be exposed to userspace and will call the driver's - .load() implementation. When a device is - removed, the DRM device can safely be unregistered and freed by calling - drm_dev_unregister() followed by a call to - drm_dev_unref(). - + Device Instance and Driver Handling +!Pdrivers/gpu/drm/drm_drv.c driver instance overview !Edrivers/gpu/drm/drm_drv.c Driver Load - - The load method is the driver and device - initialization entry point. The method is responsible for allocating and - 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 - vertical blanking handling (), mode - setting () and initial output - configuration (). - - - If compatibility is a concern (e.g. with drivers converted over from - User Mode Setting to Kernel Mode Setting), care must be taken to prevent - device initialization and control that is incompatible with currently - active userspace drivers. For instance, if user level mode setting - drivers are in use, it would be problematic to perform output discovery - & configuration at load time. Likewise, if user-level drivers - unaware of memory management are in use, memory management and command - buffer setup may need to be omitted. These requirements are - driver-specific, and care needs to be taken to keep both old and new - applications and libraries working. - - int (*load) (struct drm_device *, unsigned long flags); - - The method takes two arguments, a pointer to the newly created - drm_device and flags. The flags are used to - pass the driver_data field of the device id - corresponding to the device passed to drm_*_init(). - Only PCI devices currently use this, USB and platform DRM drivers have - their load method called with flags to 0. - - - Driver Private Data - - The driver private hangs off the main - drm_device structure and can be used for - tracking various device-specific bits of information, like register - offsets, command buffer status, register state for suspend/resume, etc. - At load time, a driver may simply allocate one and set - drm_device.dev_priv - appropriately; it should be freed and - drm_device.dev_priv - set to NULL when the driver is unloaded. - - IRQ Registration @@ -465,6 +390,18 @@ char *date; + + Bus-specific Device Registration and PCI Support + + A number of functions are provided to help with device registration. + The functions deal with PCI and platform devices respectively and are + only provided for historical reasons. These are all deprecated and + shouldn't be used in new drivers. Besides that there's a few + helpers for pci drivers. + +!Edrivers/gpu/drm/drm_pci.c +!Edrivers/gpu/drm/drm_platform.c + -- cgit v1.1