diff options
author | Matt Roper <matthew.d.roper@intel.com> | 2014-04-01 18:22:43 -0400 |
---|---|---|
committer | Rob Clark <robdclark@gmail.com> | 2014-04-01 20:18:29 -0400 |
commit | 6efa1f2f5417e628572a75e667a9d8c63d21bd17 (patch) | |
tree | bd1cc551e326af01d24d474c93b2f80f230093dd /Documentation/DocBook | |
parent | 681e7ec730444b616a1e7278a22a2691094a64e6 (diff) |
drm/doc: Update plane documentation and add plane helper library
Signed-off-by: Matt Roper <matthew.d.roper@intel.com>
Reviewed-by: Rob Clark <robdclark@gmail.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/drm.tmpl | 50 |
1 files changed, 43 insertions, 7 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 9f5457ac0373..702c4474919c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl | |||
@@ -1194,7 +1194,7 @@ int max_width, max_height;</synopsis> | |||
1194 | pointer to CRTC functions. | 1194 | pointer to CRTC functions. |
1195 | </para> | 1195 | </para> |
1196 | </sect3> | 1196 | </sect3> |
1197 | <sect3> | 1197 | <sect3 id="drm-kms-crtcops"> |
1198 | <title>CRTC Operations</title> | 1198 | <title>CRTC Operations</title> |
1199 | <sect4> | 1199 | <sect4> |
1200 | <title>Set Configuration</title> | 1200 | <title>Set Configuration</title> |
@@ -1335,15 +1335,47 @@ int max_width, max_height;</synopsis> | |||
1335 | optionally scale it to a destination size. The result is then blended | 1335 | optionally scale it to a destination size. The result is then blended |
1336 | with or overlayed on top of a CRTC. | 1336 | with or overlayed on top of a CRTC. |
1337 | </para> | 1337 | </para> |
1338 | <para> | ||
1339 | The DRM core recognizes three types of planes: | ||
1340 | <itemizedlist> | ||
1341 | <listitem> | ||
1342 | DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary | ||
1343 | planes are the planes operated upon by by CRTC modesetting and flipping | ||
1344 | operations described in <xref linkend="drm-kms-crtcops"/>. | ||
1345 | </listitem> | ||
1346 | <listitem> | ||
1347 | DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor | ||
1348 | planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and | ||
1349 | DRM_IOCTL_MODE_CURSOR2 ioctls. | ||
1350 | </listitem> | ||
1351 | <listitem> | ||
1352 | DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. | ||
1353 | Some drivers refer to these types of planes as "sprites" internally. | ||
1354 | </listitem> | ||
1355 | </itemizedlist> | ||
1356 | For compatibility with legacy userspace, only overlay planes are made | ||
1357 | available to userspace by default. Userspace clients may set the | ||
1358 | DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that | ||
1359 | they wish to receive a universal plane list containing all plane types. | ||
1360 | </para> | ||
1338 | <sect3> | 1361 | <sect3> |
1339 | <title>Plane Initialization</title> | 1362 | <title>Plane Initialization</title> |
1340 | <para> | 1363 | <para> |
1341 | Planes are optional. To create a plane, a KMS drivers allocates and | 1364 | To create a plane, a KMS drivers allocates and |
1342 | zeroes an instances of struct <structname>drm_plane</structname> | 1365 | zeroes an instances of struct <structname>drm_plane</structname> |
1343 | (possibly as part of a larger structure) and registers it with a call | 1366 | (possibly as part of a larger structure) and registers it with a call |
1344 | to <function>drm_plane_init</function>. The function takes a bitmask | 1367 | to <function>drm_universal_plane_init</function>. The function takes a bitmask |
1345 | of the CRTCs that can be associated with the plane, a pointer to the | 1368 | of the CRTCs that can be associated with the plane, a pointer to the |
1346 | plane functions and a list of format supported formats. | 1369 | plane functions, a list of format supported formats, and the type of |
1370 | plane (primary, cursor, or overlay) being initialized. | ||
1371 | </para> | ||
1372 | <para> | ||
1373 | Cursor and overlay planes are optional. All drivers should provide | ||
1374 | one primary plane per CRTC (although this requirement may change in | ||
1375 | the future); drivers that do not wish to provide special handling for | ||
1376 | primary planes may make use of the helper functions described in | ||
1377 | <xref linkend="drm-kms-planehelpers"/> to create and register a | ||
1378 | primary plane with standard capabilities. | ||
1347 | </para> | 1379 | </para> |
1348 | </sect3> | 1380 | </sect3> |
1349 | <sect3> | 1381 | <sect3> |
@@ -1774,7 +1806,7 @@ void intel_crt_init(struct drm_device *dev) | |||
1774 | <sect1> | 1806 | <sect1> |
1775 | <title>Mode Setting Helper Functions</title> | 1807 | <title>Mode Setting Helper Functions</title> |
1776 | <para> | 1808 | <para> |
1777 | The CRTC, encoder and connector functions provided by the drivers | 1809 | The plane, CRTC, encoder and connector functions provided by the drivers |
1778 | implement the DRM API. They're called by the DRM core and ioctl handlers | 1810 | implement the DRM API. They're called by the DRM core and ioctl handlers |
1779 | to handle device state changes and configuration request. As implementing | 1811 | to handle device state changes and configuration request. As implementing |
1780 | those functions often requires logic not specific to drivers, mid-layer | 1812 | those functions often requires logic not specific to drivers, mid-layer |
@@ -1782,8 +1814,8 @@ void intel_crt_init(struct drm_device *dev) | |||
1782 | </para> | 1814 | </para> |
1783 | <para> | 1815 | <para> |
1784 | The DRM core contains one mid-layer implementation. The mid-layer provides | 1816 | The DRM core contains one mid-layer implementation. The mid-layer provides |
1785 | implementations of several CRTC, encoder and connector functions (called | 1817 | implementations of several plane, CRTC, encoder and connector functions |
1786 | from the top of the mid-layer) that pre-process requests and call | 1818 | (called from the top of the mid-layer) that pre-process requests and call |
1787 | lower-level functions provided by the driver (at the bottom of the | 1819 | lower-level functions provided by the driver (at the bottom of the |
1788 | mid-layer). For instance, the | 1820 | mid-layer). For instance, the |
1789 | <function>drm_crtc_helper_set_config</function> function can be used to | 1821 | <function>drm_crtc_helper_set_config</function> function can be used to |
@@ -2293,6 +2325,10 @@ void intel_crt_init(struct drm_device *dev) | |||
2293 | !Iinclude/linux/hdmi.h | 2325 | !Iinclude/linux/hdmi.h |
2294 | !Edrivers/video/hdmi.c | 2326 | !Edrivers/video/hdmi.c |
2295 | </sect2> | 2327 | </sect2> |
2328 | <sect2> | ||
2329 | <title id="drm-kms-planehelpers">Plane Helper Reference</title> | ||
2330 | !Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers | ||
2331 | </sect2> | ||
2296 | </sect1> | 2332 | </sect1> |
2297 | 2333 | ||
2298 | <!-- Internals: kms properties --> | 2334 | <!-- Internals: kms properties --> |