Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 4c6e2dfe authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: Hide legacy horrors better 



By consolidating them all into one section at the very end. And to
make double-sure that no one gets confused start with a stern warning
against any use of them. And prefix all subsections with "Legacy".

Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent aa4cd910

Documentation/DocBook/drm.tmpl

+34 −22
Original line number Diff line number Diff line
@@ -2579,9 +2579,18 @@ int num_ioctls;</synopsis> 
      </para>

    </sect2>

  </sect1>



  <sect1>

    <title>Suspend/Resume</title>

    <title>Legacy Support Code</title>

    <para>

      The section very brievely covers some of the old legacy support code which

      is only used by old DRM drivers which have done a so-called shadow-attach

      to the underlying device instead of registering as a real driver. This

      also includes some of the old generic buffer mangement and command

      submission code. Do not use any of this in new and modern drivers.

    </para>



    <sect2>

      <title>Legacy Suspend/Resume</title>

      <para>

	The DRM core provides some suspend/resume code, but drivers wanting full

	suspend/resume support should provide save() and restore() functions.
@@ -2592,19 +2601,22 @@ int num_ioctls;</synopsis> 
      <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);

  int (*resume) (struct drm_device *);</synopsis>

      <para>

      Those are legacy suspend and resume methods. New driver should use the

      power management interface provided by their bus type (usually through

	Those are legacy suspend and resume methods which

	<emphasis>only</emphasis> work with the legacy shadow-attach driver

	registration functions. New driver should use the power management

	interface provided by their bus type (usually through

	the struct <structname>device_driver</structname> dev_pm_ops) and set

	these methods to NULL.

      </para>

  </sect1>

    </sect2>



  <sect1>

    <title>DMA services</title>

    <sect2>

      <title>Legacy DMA Services</title>

      <para>

	This should cover how DMA mapping etc. is supported by the core.

	These functions are deprecated and should not be used.

      </para>

    </sect2>

  </sect1>

  </chapter>