summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2015-09-28 21:46:35 +0200
committerDaniel Vetter <daniel.vetter@ffwll.ch>2015-09-30 10:06:06 +0200
commit6e3f797c9ae9bd381247e90907838da43f695306 (patch)
treed978ec4c7719c6b430b7e7ca175cd615625f0f9b /Documentation/DocBook
parent2d4df13c0f9ef56452b1d9a9016cb3946e17bfe5 (diff)
drm/doc: Update docs about device instance setup
->load is deprecated, bus functions are deprecated and everyone should use drm_dev_alloc&register. 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 <laurent.pinchart@ideasonboard.com> Cc: David Herrmann <dh.herrmann@gmail.com> Acked-by: David Herrmann <dh.herrmann@gmail.com> (v2) Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/drm.tmpl99
1 files changed, 18 insertions, 81 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 30401f927156..11f5bfb68ecb 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -138,14 +138,10 @@
<para>
At the core of every DRM driver is a <structname>drm_driver</structname>
structure. Drivers typically statically initialize a drm_driver structure,
- and then pass it to one of the <function>drm_*_init()</function> functions
- to register it with the DRM subsystem.
- </para>
- <para>
- Newer drivers that no longer require a <structname>drm_bus</structname>
- structure can alternatively use the low-level device initialization and
- registration functions such as <function>drm_dev_alloc()</function> and
- <function>drm_dev_register()</function> directly.
+ and then pass it to <function>drm_dev_alloc()</function> to allocate a
+ device instance. After the device instance is fully initialized it can be
+ registered (which makes it accessible from userspace) using
+ <function>drm_dev_register()</function>.
</para>
<para>
The <structname>drm_driver</structname> structure contains static
@@ -296,83 +292,12 @@ char *date;</synopsis>
</sect3>
</sect2>
<sect2>
- <title>Device Registration</title>
- <para>
- A number of functions are provided to help with device registration.
- The functions deal with PCI and platform devices, respectively.
- </para>
-!Edrivers/gpu/drm/drm_pci.c
-!Edrivers/gpu/drm/drm_platform.c
- <para>
- New drivers that no longer rely on the services provided by the
- <structname>drm_bus</structname> structure can call the low-level
- device registration functions directly. The
- <function>drm_dev_alloc()</function> function can be used to allocate
- and initialize a new <structname>drm_device</structname> 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 <structfield>dev_private</structfield>
- field. Drivers should also set the device's unique name using the
- <function>drm_dev_set_unique()</function> function. After it has been
- set up a device can be registered with the DRM subsystem by calling
- <function>drm_dev_register()</function>. This will cause the device to
- be exposed to userspace and will call the driver's
- <structfield>.load()</structfield> implementation. When a device is
- removed, the DRM device can safely be unregistered and freed by calling
- <function>drm_dev_unregister()</function> followed by a call to
- <function>drm_dev_unref()</function>.
- </para>
+ <title>Device Instance and Driver Handling</title>
+!Pdrivers/gpu/drm/drm_drv.c driver instance overview
!Edrivers/gpu/drm/drm_drv.c
</sect2>
<sect2>
<title>Driver Load</title>
- <para>
- The <methodname>load</methodname> 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 (<xref linkend="drm-memory-management"/>), installing
- the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up
- vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode
- setting (<xref linkend="drm-mode-setting"/>) and initial output
- configuration (<xref linkend="drm-kms-init"/>).
- </para>
- <note><para>
- 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
- &amp; 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.
- </para></note>
- <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis>
- <para>
- The method takes two arguments, a pointer to the newly created
- <structname>drm_device</structname> and flags. The flags are used to
- pass the <structfield>driver_data</structfield> field of the device id
- corresponding to the device passed to <function>drm_*_init()</function>.
- Only PCI devices currently use this, USB and platform DRM drivers have
- their <methodname>load</methodname> method called with flags to 0.
- </para>
- <sect3>
- <title>Driver Private Data</title>
- <para>
- The driver private hangs off the main
- <structname>drm_device</structname> 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
- <structname>drm_device</structname>.<structfield>dev_priv</structfield>
- appropriately; it should be freed and
- <structname>drm_device</structname>.<structfield>dev_priv</structfield>
- set to NULL when the driver is unloaded.
- </para>
- </sect3>
<sect3 id="drm-irq-registration">
<title>IRQ Registration</title>
<para>
@@ -465,6 +390,18 @@ char *date;</synopsis>
</para>
</sect3>
</sect2>
+ <sect2>
+ <title>Bus-specific Device Registration and PCI Support</title>
+ <para>
+ 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.
+ </para>
+!Edrivers/gpu/drm/drm_pci.c
+!Edrivers/gpu/drm/drm_platform.c
+ </sect2>
</sect1>
<!-- Internals: memory management -->