diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2014-04-08 12:52:16 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2014-04-08 12:52:16 -0400 |
commit | e9f37d3a8d126e73f5737ef548cdf6f618e295e4 (patch) | |
tree | 831eb4952637828a7bbafa361185e0ca57aa86ed /Documentation/DocBook | |
parent | 5fb6b953bb7aa86a9c8ea760934982cedc45c52b (diff) | |
parent | c39b06951f1dc2e384650288676c5b7dcc0ec92c (diff) |
Merge branch 'drm-next' of git://people.freedesktop.org/~airlied/linux
Pull drm updates from Dave Airlie:
"Highlights:
- drm:
Generic display port aux features, primary plane support, drm
master management fixes, logging cleanups, enforced locking checks
(instead of docs), documentation improvements, minor number
handling cleanup, pseudofs for shared inodes.
- ttm:
add ability to allocate from both ends
- i915:
broadwell features, power domain and runtime pm, per-process
address space infrastructure (not enabled)
- msm:
power management, hdmi audio support
- nouveau:
ongoing GPU fault recovery, initial maxwell support, random fixes
- exynos:
refactored driver to clean up a lot of abstraction, DP support
moved into drm, LVDS bridge support added, parallel panel support
- gma500:
SGX MMU support, SGX irq handling, asle irq work fixes
- radeon:
video engine bringup, ring handling fixes, use dp aux helpers
- vmwgfx:
add rendernode support"
* 'drm-next' of git://people.freedesktop.org/~airlied/linux: (849 commits)
DRM: armada: fix corruption while loading cursors
drm/dp_helper: don't return EPROTO for defers (v2)
drm/bridge: export ptn3460_init function
drm/exynos: remove MODULE_DEVICE_TABLE definitions
ARM: dts: exynos4412-trats2: enable exynos/fimd node
ARM: dts: exynos4210-trats: enable exynos/fimd node
ARM: dts: exynos4412-trats2: add panel node
ARM: dts: exynos4210-trats: add panel node
ARM: dts: exynos4: add MIPI DSI Master node
drm/panel: add S6E8AA0 driver
ARM: dts: exynos4210-universal_c210: add proper panel node
drm/panel: add ld9040 driver
panel/ld9040: add DT bindings
panel/s6e8aa0: add DT bindings
drm/exynos: add DSIM driver
exynos/dsim: add DT bindings
drm/exynos: disallow fbdev initialization if no device is connected
drm/mipi_dsi: create dsi devices only for nodes with reg property
drm/mipi_dsi: add flags to DSI messages
Skip intel_crt_init for Dell XPS 8700
...
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/drm.tmpl | 550 |
1 files changed, 369 insertions, 181 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d289022..702c4474919c 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl | |||
@@ -29,12 +29,26 @@ | |||
29 | </address> | 29 | </address> |
30 | </affiliation> | 30 | </affiliation> |
31 | </author> | 31 | </author> |
32 | <author> | ||
33 | <firstname>Daniel</firstname> | ||
34 | <surname>Vetter</surname> | ||
35 | <contrib>Contributions all over the place</contrib> | ||
36 | <affiliation> | ||
37 | <orgname>Intel Corporation</orgname> | ||
38 | <address> | ||
39 | <email>daniel.vetter@ffwll.ch</email> | ||
40 | </address> | ||
41 | </affiliation> | ||
42 | </author> | ||
32 | </authorgroup> | 43 | </authorgroup> |
33 | 44 | ||
34 | <copyright> | 45 | <copyright> |
35 | <year>2008-2009</year> | 46 | <year>2008-2009</year> |
36 | <year>2012</year> | 47 | <year>2013-2014</year> |
37 | <holder>Intel Corporation</holder> | 48 | <holder>Intel Corporation</holder> |
49 | </copyright> | ||
50 | <copyright> | ||
51 | <year>2012</year> | ||
38 | <holder>Laurent Pinchart</holder> | 52 | <holder>Laurent Pinchart</holder> |
39 | </copyright> | 53 | </copyright> |
40 | 54 | ||
@@ -60,7 +74,15 @@ | |||
60 | 74 | ||
61 | <toc></toc> | 75 | <toc></toc> |
62 | 76 | ||
63 | <!-- Introduction --> | 77 | <part id="drmCore"> |
78 | <title>DRM Core</title> | ||
79 | <partintro> | ||
80 | <para> | ||
81 | This first part of the DRM Developer's Guide documents core DRM code, | ||
82 | helper libraries for writting drivers and generic userspace interfaces | ||
83 | exposed by DRM drivers. | ||
84 | </para> | ||
85 | </partintro> | ||
64 | 86 | ||
65 | <chapter id="drmIntroduction"> | 87 | <chapter id="drmIntroduction"> |
66 | <title>Introduction</title> | 88 | <title>Introduction</title> |
@@ -264,8 +286,8 @@ char *date;</synopsis> | |||
264 | <para> | 286 | <para> |
265 | The <methodname>load</methodname> method is the driver and device | 287 | The <methodname>load</methodname> method is the driver and device |
266 | initialization entry point. The method is responsible for allocating and | 288 | initialization entry point. The method is responsible for allocating and |
267 | initializing driver private data, specifying supported performance | 289 | initializing driver private data, performing resource allocation and |
268 | counters, performing resource allocation and mapping (e.g. acquiring | 290 | mapping (e.g. acquiring |
269 | clocks, mapping registers or allocating command buffers), initializing | 291 | clocks, mapping registers or allocating command buffers), initializing |
270 | the memory manager (<xref linkend="drm-memory-management"/>), installing | 292 | the memory manager (<xref linkend="drm-memory-management"/>), installing |
271 | the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up | 293 | the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up |
@@ -295,7 +317,7 @@ char *date;</synopsis> | |||
295 | their <methodname>load</methodname> method called with flags to 0. | 317 | their <methodname>load</methodname> method called with flags to 0. |
296 | </para> | 318 | </para> |
297 | <sect3> | 319 | <sect3> |
298 | <title>Driver Private & Performance Counters</title> | 320 | <title>Driver Private Data</title> |
299 | <para> | 321 | <para> |
300 | The driver private hangs off the main | 322 | The driver private hangs off the main |
301 | <structname>drm_device</structname> structure and can be used for | 323 | <structname>drm_device</structname> structure and can be used for |
@@ -307,14 +329,6 @@ char *date;</synopsis> | |||
307 | <structname>drm_device</structname>.<structfield>dev_priv</structfield> | 329 | <structname>drm_device</structname>.<structfield>dev_priv</structfield> |
308 | set to NULL when the driver is unloaded. | 330 | set to NULL when the driver is unloaded. |
309 | </para> | 331 | </para> |
310 | <para> | ||
311 | DRM supports several counters which were used for rough performance | ||
312 | characterization. This stat counter system is deprecated and should not | ||
313 | be used. If performance monitoring is desired, the developer should | ||
314 | investigate and potentially enhance the kernel perf and tracing | ||
315 | infrastructure to export GPU related performance information for | ||
316 | consumption by performance monitoring tools and applications. | ||
317 | </para> | ||
318 | </sect3> | 332 | </sect3> |
319 | <sect3 id="drm-irq-registration"> | 333 | <sect3 id="drm-irq-registration"> |
320 | <title>IRQ Registration</title> | 334 | <title>IRQ Registration</title> |
@@ -697,55 +711,16 @@ char *date;</synopsis> | |||
697 | respectively. The conversion is handled by the DRM core without any | 711 | respectively. The conversion is handled by the DRM core without any |
698 | driver-specific support. | 712 | driver-specific support. |
699 | </para> | 713 | </para> |
700 | <para> | 714 | <para> |
701 | Similar to global names, GEM file descriptors are also used to share GEM | 715 | GEM also supports buffer sharing with dma-buf file descriptors through |
702 | objects across processes. They offer additional security: as file | 716 | PRIME. GEM-based drivers must use the provided helpers functions to |
703 | descriptors must be explicitly sent over UNIX domain sockets to be shared | 717 | implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. |
704 | between applications, they can't be guessed like the globally unique GEM | 718 | Since sharing file descriptors is inherently more secure than the |
705 | names. | 719 | easily guessable and global GEM names it is the preferred buffer |
706 | </para> | 720 | sharing mechanism. Sharing buffers through GEM names is only supported |
707 | <para> | 721 | for legacy userspace. Furthermore PRIME also allows cross-device |
708 | Drivers that support GEM file descriptors, also known as the DRM PRIME | 722 | buffer sharing since it is based on dma-bufs. |
709 | API, must set the DRIVER_PRIME bit in the struct | 723 | </para> |
710 | <structname>drm_driver</structname> | ||
711 | <structfield>driver_features</structfield> field, and implement the | ||
712 | <methodname>prime_handle_to_fd</methodname> and | ||
713 | <methodname>prime_fd_to_handle</methodname> operations. | ||
714 | </para> | ||
715 | <para> | ||
716 | <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, | ||
717 | struct drm_file *file_priv, uint32_t handle, | ||
718 | uint32_t flags, int *prime_fd); | ||
719 | int (*prime_fd_to_handle)(struct drm_device *dev, | ||
720 | struct drm_file *file_priv, int prime_fd, | ||
721 | uint32_t *handle);</synopsis> | ||
722 | Those two operations convert a handle to a PRIME file descriptor and | ||
723 | vice versa. Drivers must use the kernel dma-buf buffer sharing framework | ||
724 | to manage the PRIME file descriptors. | ||
725 | </para> | ||
726 | <para> | ||
727 | While non-GEM drivers must implement the operations themselves, GEM | ||
728 | drivers must use the <function>drm_gem_prime_handle_to_fd</function> | ||
729 | and <function>drm_gem_prime_fd_to_handle</function> helper functions. | ||
730 | Those helpers rely on the driver | ||
731 | <methodname>gem_prime_export</methodname> and | ||
732 | <methodname>gem_prime_import</methodname> operations to create a dma-buf | ||
733 | instance from a GEM object (dma-buf exporter role) and to create a GEM | ||
734 | object from a dma-buf instance (dma-buf importer role). | ||
735 | </para> | ||
736 | <para> | ||
737 | <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, | ||
738 | struct drm_gem_object *obj, | ||
739 | int flags); | ||
740 | struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, | ||
741 | struct dma_buf *dma_buf);</synopsis> | ||
742 | These two operations are mandatory for GEM drivers that support DRM | ||
743 | PRIME. | ||
744 | </para> | ||
745 | <sect4> | ||
746 | <title>DRM PRIME Helper Functions Reference</title> | ||
747 | !Pdrivers/gpu/drm/drm_prime.c PRIME Helpers | ||
748 | </sect4> | ||
749 | </sect3> | 724 | </sect3> |
750 | <sect3 id="drm-gem-objects-mapping"> | 725 | <sect3 id="drm-gem-objects-mapping"> |
751 | <title>GEM Objects Mapping</title> | 726 | <title>GEM Objects Mapping</title> |
@@ -830,62 +805,6 @@ char *date;</synopsis> | |||
830 | </para> | 805 | </para> |
831 | </sect3> | 806 | </sect3> |
832 | <sect3> | 807 | <sect3> |
833 | <title>Dumb GEM Objects</title> | ||
834 | <para> | ||
835 | The GEM API doesn't standardize GEM objects creation and leaves it to | ||
836 | driver-specific ioctls. While not an issue for full-fledged graphics | ||
837 | stacks that include device-specific userspace components (in libdrm for | ||
838 | instance), this limit makes DRM-based early boot graphics unnecessarily | ||
839 | complex. | ||
840 | </para> | ||
841 | <para> | ||
842 | Dumb GEM objects partly alleviate the problem by providing a standard | ||
843 | API to create dumb buffers suitable for scanout, which can then be used | ||
844 | to create KMS frame buffers. | ||
845 | </para> | ||
846 | <para> | ||
847 | To support dumb GEM objects drivers must implement the | ||
848 | <methodname>dumb_create</methodname>, | ||
849 | <methodname>dumb_destroy</methodname> and | ||
850 | <methodname>dumb_map_offset</methodname> operations. | ||
851 | </para> | ||
852 | <itemizedlist> | ||
853 | <listitem> | ||
854 | <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, | ||
855 | struct drm_mode_create_dumb *args);</synopsis> | ||
856 | <para> | ||
857 | The <methodname>dumb_create</methodname> operation creates a GEM | ||
858 | object suitable for scanout based on the width, height and depth | ||
859 | from the struct <structname>drm_mode_create_dumb</structname> | ||
860 | argument. It fills the argument's <structfield>handle</structfield>, | ||
861 | <structfield>pitch</structfield> and <structfield>size</structfield> | ||
862 | fields with a handle for the newly created GEM object and its line | ||
863 | pitch and size in bytes. | ||
864 | </para> | ||
865 | </listitem> | ||
866 | <listitem> | ||
867 | <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, | ||
868 | uint32_t handle);</synopsis> | ||
869 | <para> | ||
870 | The <methodname>dumb_destroy</methodname> operation destroys a dumb | ||
871 | GEM object created by <methodname>dumb_create</methodname>. | ||
872 | </para> | ||
873 | </listitem> | ||
874 | <listitem> | ||
875 | <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, | ||
876 | uint32_t handle, uint64_t *offset);</synopsis> | ||
877 | <para> | ||
878 | The <methodname>dumb_map_offset</methodname> operation associates an | ||
879 | mmap fake offset with the GEM object given by the handle and returns | ||
880 | it. Drivers must use the | ||
881 | <function>drm_gem_create_mmap_offset</function> function to | ||
882 | associate the fake offset as described in | ||
883 | <xref linkend="drm-gem-objects-mapping"/>. | ||
884 | </para> | ||
885 | </listitem> | ||
886 | </itemizedlist> | ||
887 | </sect3> | ||
888 | <sect3> | ||
889 | <title>Memory Coherency</title> | 808 | <title>Memory Coherency</title> |
890 | <para> | 809 | <para> |
891 | When mapped to the device or used in a command buffer, backing pages | 810 | When mapped to the device or used in a command buffer, backing pages |
@@ -924,7 +843,99 @@ char *date;</synopsis> | |||
924 | abstracted from the client in libdrm. | 843 | abstracted from the client in libdrm. |
925 | </para> | 844 | </para> |
926 | </sect3> | 845 | </sect3> |
927 | </sect2> | 846 | <sect3> |
847 | <title>GEM Function Reference</title> | ||
848 | !Edrivers/gpu/drm/drm_gem.c | ||
849 | </sect3> | ||
850 | </sect2> | ||
851 | <sect2> | ||
852 | <title>VMA Offset Manager</title> | ||
853 | !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager | ||
854 | !Edrivers/gpu/drm/drm_vma_manager.c | ||
855 | !Iinclude/drm/drm_vma_manager.h | ||
856 | </sect2> | ||
857 | <sect2 id="drm-prime-support"> | ||
858 | <title>PRIME Buffer Sharing</title> | ||
859 | <para> | ||
860 | PRIME is the cross device buffer sharing framework in drm, originally | ||
861 | created for the OPTIMUS range of multi-gpu platforms. To userspace | ||
862 | PRIME buffers are dma-buf based file descriptors. | ||
863 | </para> | ||
864 | <sect3> | ||
865 | <title>Overview and Driver Interface</title> | ||
866 | <para> | ||
867 | Similar to GEM global names, PRIME file descriptors are | ||
868 | also used to share buffer objects across processes. They offer | ||
869 | additional security: as file descriptors must be explicitly sent over | ||
870 | UNIX domain sockets to be shared between applications, they can't be | ||
871 | guessed like the globally unique GEM names. | ||
872 | </para> | ||
873 | <para> | ||
874 | Drivers that support the PRIME | ||
875 | API must set the DRIVER_PRIME bit in the struct | ||
876 | <structname>drm_driver</structname> | ||
877 | <structfield>driver_features</structfield> field, and implement the | ||
878 | <methodname>prime_handle_to_fd</methodname> and | ||
879 | <methodname>prime_fd_to_handle</methodname> operations. | ||
880 | </para> | ||
881 | <para> | ||
882 | <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, | ||
883 | struct drm_file *file_priv, uint32_t handle, | ||
884 | uint32_t flags, int *prime_fd); | ||
885 | int (*prime_fd_to_handle)(struct drm_device *dev, | ||
886 | struct drm_file *file_priv, int prime_fd, | ||
887 | uint32_t *handle);</synopsis> | ||
888 | Those two operations convert a handle to a PRIME file descriptor and | ||
889 | vice versa. Drivers must use the kernel dma-buf buffer sharing framework | ||
890 | to manage the PRIME file descriptors. Similar to the mode setting | ||
891 | API PRIME is agnostic to the underlying buffer object manager, as | ||
892 | long as handles are 32bit unsinged integers. | ||
893 | </para> | ||
894 | <para> | ||
895 | While non-GEM drivers must implement the operations themselves, GEM | ||
896 | drivers must use the <function>drm_gem_prime_handle_to_fd</function> | ||
897 | and <function>drm_gem_prime_fd_to_handle</function> helper functions. | ||
898 | Those helpers rely on the driver | ||
899 | <methodname>gem_prime_export</methodname> and | ||
900 | <methodname>gem_prime_import</methodname> operations to create a dma-buf | ||
901 | instance from a GEM object (dma-buf exporter role) and to create a GEM | ||
902 | object from a dma-buf instance (dma-buf importer role). | ||
903 | </para> | ||
904 | <para> | ||
905 | <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, | ||
906 | struct drm_gem_object *obj, | ||
907 | int flags); | ||
908 | struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, | ||
909 | struct dma_buf *dma_buf);</synopsis> | ||
910 | These two operations are mandatory for GEM drivers that support | ||
911 | PRIME. | ||
912 | </para> | ||
913 | </sect3> | ||
914 | <sect3> | ||
915 | <title>PRIME Helper Functions</title> | ||
916 | !Pdrivers/gpu/drm/drm_prime.c PRIME Helpers | ||
917 | </sect3> | ||
918 | </sect2> | ||
919 | <sect2> | ||
920 | <title>PRIME Function References</title> | ||
921 | !Edrivers/gpu/drm/drm_prime.c | ||
922 | </sect2> | ||
923 | <sect2> | ||
924 | <title>DRM MM Range Allocator</title> | ||
925 | <sect3> | ||
926 | <title>Overview</title> | ||
927 | !Pdrivers/gpu/drm/drm_mm.c Overview | ||
928 | </sect3> | ||
929 | <sect3> | ||
930 | <title>LRU Scan/Eviction Support</title> | ||
931 | !Pdrivers/gpu/drm/drm_mm.c lru scan roaster | ||
932 | </sect3> | ||
933 | </sect2> | ||
934 | <sect2> | ||
935 | <title>DRM MM Range Allocator Function References</title> | ||
936 | !Edrivers/gpu/drm/drm_mm.c | ||
937 | !Iinclude/drm/drm_mm.h | ||
938 | </sect2> | ||
928 | </sect1> | 939 | </sect1> |
929 | 940 | ||
930 | <!-- Internals: mode setting --> | 941 | <!-- Internals: mode setting --> |
@@ -953,6 +964,11 @@ int max_width, max_height;</synopsis> | |||
953 | </listitem> | 964 | </listitem> |
954 | </itemizedlist> | 965 | </itemizedlist> |
955 | <sect2> | 966 | <sect2> |
967 | <title>Display Modes Function Reference</title> | ||
968 | !Iinclude/drm/drm_modes.h | ||
969 | !Edrivers/gpu/drm/drm_modes.c | ||
970 | </sect2> | ||
971 | <sect2> | ||
956 | <title>Frame Buffer Creation</title> | 972 | <title>Frame Buffer Creation</title> |
957 | <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, | 973 | <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, |
958 | struct drm_file *file_priv, | 974 | struct drm_file *file_priv, |
@@ -968,9 +984,11 @@ int max_width, max_height;</synopsis> | |||
968 | Frame buffers rely on the underneath memory manager for low-level memory | 984 | Frame buffers rely on the underneath memory manager for low-level memory |
969 | operations. When creating a frame buffer applications pass a memory | 985 | operations. When creating a frame buffer applications pass a memory |
970 | handle (or a list of memory handles for multi-planar formats) through | 986 | handle (or a list of memory handles for multi-planar formats) through |
971 | the <parameter>drm_mode_fb_cmd2</parameter> argument. This document | 987 | the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using |
972 | assumes that the driver uses GEM, those handles thus reference GEM | 988 | GEM as their userspace buffer management interface this would be a GEM |
973 | objects. | 989 | handle. Drivers are however free to use their own backing storage object |
990 | handles, e.g. vmwgfx directly exposes special TTM handles to userspace | ||
991 | and so expects TTM handles in the create ioctl and not GEM handles. | ||
974 | </para> | 992 | </para> |
975 | <para> | 993 | <para> |
976 | Drivers must first validate the requested frame buffer parameters passed | 994 | Drivers must first validate the requested frame buffer parameters passed |
@@ -992,7 +1010,7 @@ int max_width, max_height;</synopsis> | |||
992 | </para> | 1010 | </para> |
993 | 1011 | ||
994 | <para> | 1012 | <para> |
995 | The initailization of the new framebuffer instance is finalized with a | 1013 | The initialization of the new framebuffer instance is finalized with a |
996 | call to <function>drm_framebuffer_init</function> which takes a pointer | 1014 | call to <function>drm_framebuffer_init</function> which takes a pointer |
997 | to DRM frame buffer operations (struct | 1015 | to DRM frame buffer operations (struct |
998 | <structname>drm_framebuffer_funcs</structname>). Note that this function | 1016 | <structname>drm_framebuffer_funcs</structname>). Note that this function |
@@ -1042,7 +1060,7 @@ int max_width, max_height;</synopsis> | |||
1042 | <para> | 1060 | <para> |
1043 | The lifetime of a drm framebuffer is controlled with a reference count, | 1061 | The lifetime of a drm framebuffer is controlled with a reference count, |
1044 | drivers can grab additional references with | 1062 | drivers can grab additional references with |
1045 | <function>drm_framebuffer_reference</function> </para> and drop them | 1063 | <function>drm_framebuffer_reference</function>and drop them |
1046 | again with <function>drm_framebuffer_unreference</function>. For | 1064 | again with <function>drm_framebuffer_unreference</function>. For |
1047 | driver-private framebuffers for which the last reference is never | 1065 | driver-private framebuffers for which the last reference is never |
1048 | dropped (e.g. for the fbdev framebuffer when the struct | 1066 | dropped (e.g. for the fbdev framebuffer when the struct |
@@ -1050,6 +1068,72 @@ int max_width, max_height;</synopsis> | |||
1050 | helper struct) drivers can manually clean up a framebuffer at module | 1068 | helper struct) drivers can manually clean up a framebuffer at module |
1051 | unload time with | 1069 | unload time with |
1052 | <function>drm_framebuffer_unregister_private</function>. | 1070 | <function>drm_framebuffer_unregister_private</function>. |
1071 | </para> | ||
1072 | </sect2> | ||
1073 | <sect2> | ||
1074 | <title>Dumb Buffer Objects</title> | ||
1075 | <para> | ||
1076 | The KMS API doesn't standardize backing storage object creation and | ||
1077 | leaves it to driver-specific ioctls. Furthermore actually creating a | ||
1078 | buffer object even for GEM-based drivers is done through a | ||
1079 | driver-specific ioctl - GEM only has a common userspace interface for | ||
1080 | sharing and destroying objects. While not an issue for full-fledged | ||
1081 | graphics stacks that include device-specific userspace components (in | ||
1082 | libdrm for instance), this limit makes DRM-based early boot graphics | ||
1083 | unnecessarily complex. | ||
1084 | </para> | ||
1085 | <para> | ||
1086 | Dumb objects partly alleviate the problem by providing a standard | ||
1087 | API to create dumb buffers suitable for scanout, which can then be used | ||
1088 | to create KMS frame buffers. | ||
1089 | </para> | ||
1090 | <para> | ||
1091 | To support dumb objects drivers must implement the | ||
1092 | <methodname>dumb_create</methodname>, | ||
1093 | <methodname>dumb_destroy</methodname> and | ||
1094 | <methodname>dumb_map_offset</methodname> operations. | ||
1095 | </para> | ||
1096 | <itemizedlist> | ||
1097 | <listitem> | ||
1098 | <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, | ||
1099 | struct drm_mode_create_dumb *args);</synopsis> | ||
1100 | <para> | ||
1101 | The <methodname>dumb_create</methodname> operation creates a driver | ||
1102 | object (GEM or TTM handle) suitable for scanout based on the | ||
1103 | width, height and depth from the struct | ||
1104 | <structname>drm_mode_create_dumb</structname> argument. It fills the | ||
1105 | argument's <structfield>handle</structfield>, | ||
1106 | <structfield>pitch</structfield> and <structfield>size</structfield> | ||
1107 | fields with a handle for the newly created object and its line | ||
1108 | pitch and size in bytes. | ||
1109 | </para> | ||
1110 | </listitem> | ||
1111 | <listitem> | ||
1112 | <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, | ||
1113 | uint32_t handle);</synopsis> | ||
1114 | <para> | ||
1115 | The <methodname>dumb_destroy</methodname> operation destroys a dumb | ||
1116 | object created by <methodname>dumb_create</methodname>. | ||
1117 | </para> | ||
1118 | </listitem> | ||
1119 | <listitem> | ||
1120 | <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, | ||
1121 | uint32_t handle, uint64_t *offset);</synopsis> | ||
1122 | <para> | ||
1123 | The <methodname>dumb_map_offset</methodname> operation associates an | ||
1124 | mmap fake offset with the object given by the handle and returns | ||
1125 | it. Drivers must use the | ||
1126 | <function>drm_gem_create_mmap_offset</function> function to | ||
1127 | associate the fake offset as described in | ||
1128 | <xref linkend="drm-gem-objects-mapping"/>. | ||
1129 | </para> | ||
1130 | </listitem> | ||
1131 | </itemizedlist> | ||
1132 | <para> | ||
1133 | Note that dumb objects may not be used for gpu acceleration, as has been | ||
1134 | attempted on some ARM embedded platforms. Such drivers really must have | ||
1135 | a hardware-specific ioctl to allocate suitable buffer objects. | ||
1136 | </para> | ||
1053 | </sect2> | 1137 | </sect2> |
1054 | <sect2> | 1138 | <sect2> |
1055 | <title>Output Polling</title> | 1139 | <title>Output Polling</title> |
@@ -1110,7 +1194,7 @@ int max_width, max_height;</synopsis> | |||
1110 | pointer to CRTC functions. | 1194 | pointer to CRTC functions. |
1111 | </para> | 1195 | </para> |
1112 | </sect3> | 1196 | </sect3> |
1113 | <sect3> | 1197 | <sect3 id="drm-kms-crtcops"> |
1114 | <title>CRTC Operations</title> | 1198 | <title>CRTC Operations</title> |
1115 | <sect4> | 1199 | <sect4> |
1116 | <title>Set Configuration</title> | 1200 | <title>Set Configuration</title> |
@@ -1130,8 +1214,11 @@ int max_width, max_height;</synopsis> | |||
1130 | This operation is called with the mode config lock held. | 1214 | This operation is called with the mode config lock held. |
1131 | </para> | 1215 | </para> |
1132 | <note><para> | 1216 | <note><para> |
1133 | FIXME: How should set_config interact with DPMS? If the CRTC is | 1217 | Note that the drm core has no notion of restoring the mode setting |
1134 | suspended, should it be resumed? | 1218 | state after resume, since all resume handling is in the full |
1219 | responsibility of the driver. The common mode setting helper library | ||
1220 | though provides a helper which can be used for this: | ||
1221 | <function>drm_helper_resume_force_mode</function>. | ||
1135 | </para></note> | 1222 | </para></note> |
1136 | </sect4> | 1223 | </sect4> |
1137 | <sect4> | 1224 | <sect4> |
@@ -1248,15 +1335,47 @@ int max_width, max_height;</synopsis> | |||
1248 | 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 |
1249 | with or overlayed on top of a CRTC. | 1336 | with or overlayed on top of a CRTC. |
1250 | </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> | ||
1251 | <sect3> | 1361 | <sect3> |
1252 | <title>Plane Initialization</title> | 1362 | <title>Plane Initialization</title> |
1253 | <para> | 1363 | <para> |
1254 | Planes are optional. To create a plane, a KMS drivers allocates and | 1364 | To create a plane, a KMS drivers allocates and |
1255 | zeroes an instances of struct <structname>drm_plane</structname> | 1365 | zeroes an instances of struct <structname>drm_plane</structname> |
1256 | (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 |
1257 | to <function>drm_plane_init</function>. The function takes a bitmask | 1367 | to <function>drm_universal_plane_init</function>. The function takes a bitmask |
1258 | 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 |
1259 | 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. | ||
1260 | </para> | 1379 | </para> |
1261 | </sect3> | 1380 | </sect3> |
1262 | <sect3> | 1381 | <sect3> |
@@ -1687,7 +1806,7 @@ void intel_crt_init(struct drm_device *dev) | |||
1687 | <sect1> | 1806 | <sect1> |
1688 | <title>Mode Setting Helper Functions</title> | 1807 | <title>Mode Setting Helper Functions</title> |
1689 | <para> | 1808 | <para> |
1690 | The CRTC, encoder and connector functions provided by the drivers | 1809 | The plane, CRTC, encoder and connector functions provided by the drivers |
1691 | 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 |
1692 | to handle device state changes and configuration request. As implementing | 1811 | to handle device state changes and configuration request. As implementing |
1693 | those functions often requires logic not specific to drivers, mid-layer | 1812 | those functions often requires logic not specific to drivers, mid-layer |
@@ -1695,8 +1814,8 @@ void intel_crt_init(struct drm_device *dev) | |||
1695 | </para> | 1814 | </para> |
1696 | <para> | 1815 | <para> |
1697 | 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 |
1698 | implementations of several CRTC, encoder and connector functions (called | 1817 | implementations of several plane, CRTC, encoder and connector functions |
1699 | 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 |
1700 | 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 |
1701 | mid-layer). For instance, the | 1820 | mid-layer). For instance, the |
1702 | <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 |
@@ -2134,7 +2253,7 @@ void intel_crt_init(struct drm_device *dev) | |||
2134 | set the <structfield>display_info</structfield> | 2253 | set the <structfield>display_info</structfield> |
2135 | <structfield>width_mm</structfield> and | 2254 | <structfield>width_mm</structfield> and |
2136 | <structfield>height_mm</structfield> fields if they haven't been set | 2255 | <structfield>height_mm</structfield> fields if they haven't been set |
2137 | already (for instance at initilization time when a fixed-size panel is | 2256 | already (for instance at initialization time when a fixed-size panel is |
2138 | attached to the connector). The mode <structfield>width_mm</structfield> | 2257 | attached to the connector). The mode <structfield>width_mm</structfield> |
2139 | and <structfield>height_mm</structfield> fields are only used internally | 2258 | and <structfield>height_mm</structfield> fields are only used internally |
2140 | during EDID parsing and should not be set when creating modes manually. | 2259 | during EDID parsing and should not be set when creating modes manually. |
@@ -2196,10 +2315,19 @@ void intel_crt_init(struct drm_device *dev) | |||
2196 | !Edrivers/gpu/drm/drm_flip_work.c | 2315 | !Edrivers/gpu/drm/drm_flip_work.c |
2197 | </sect2> | 2316 | </sect2> |
2198 | <sect2> | 2317 | <sect2> |
2199 | <title>VMA Offset Manager</title> | 2318 | <title>HDMI Infoframes Helper Reference</title> |
2200 | !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager | 2319 | <para> |
2201 | !Edrivers/gpu/drm/drm_vma_manager.c | 2320 | Strictly speaking this is not a DRM helper library but generally useable |
2202 | !Iinclude/drm/drm_vma_manager.h | 2321 | by any driver interfacing with HDMI outputs like v4l or alsa drivers. |
2322 | But it nicely fits into the overall topic of mode setting helper | ||
2323 | libraries and hence is also included here. | ||
2324 | </para> | ||
2325 | !Iinclude/linux/hdmi.h | ||
2326 | !Edrivers/video/hdmi.c | ||
2327 | </sect2> | ||
2328 | <sect2> | ||
2329 | <title id="drm-kms-planehelpers">Plane Helper Reference</title> | ||
2330 | !Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers | ||
2203 | </sect2> | 2331 | </sect2> |
2204 | </sect1> | 2332 | </sect1> |
2205 | 2333 | ||
@@ -2561,42 +2689,44 @@ int num_ioctls;</synopsis> | |||
2561 | </para> | 2689 | </para> |
2562 | </sect2> | 2690 | </sect2> |
2563 | </sect1> | 2691 | </sect1> |
2564 | |||
2565 | <sect1> | 2692 | <sect1> |
2566 | <title>Command submission & fencing</title> | 2693 | <title>Legacy Support Code</title> |
2567 | <para> | 2694 | <para> |
2568 | This should cover a few device-specific command submission | 2695 | The section very brievely covers some of the old legacy support code which |
2569 | implementations. | 2696 | is only used by old DRM drivers which have done a so-called shadow-attach |
2697 | to the underlying device instead of registering as a real driver. This | ||
2698 | also includes some of the old generic buffer mangement and command | ||
2699 | submission code. Do not use any of this in new and modern drivers. | ||
2570 | </para> | 2700 | </para> |
2571 | </sect1> | ||
2572 | |||
2573 | <!-- Internals: suspend/resume --> | ||
2574 | 2701 | ||
2575 | <sect1> | 2702 | <sect2> |
2576 | <title>Suspend/Resume</title> | 2703 | <title>Legacy Suspend/Resume</title> |
2577 | <para> | 2704 | <para> |
2578 | The DRM core provides some suspend/resume code, but drivers wanting full | 2705 | The DRM core provides some suspend/resume code, but drivers wanting full |
2579 | suspend/resume support should provide save() and restore() functions. | 2706 | suspend/resume support should provide save() and restore() functions. |
2580 | These are called at suspend, hibernate, or resume time, and should perform | 2707 | These are called at suspend, hibernate, or resume time, and should perform |
2581 | any state save or restore required by your device across suspend or | 2708 | any state save or restore required by your device across suspend or |
2582 | hibernate states. | 2709 | hibernate states. |
2583 | </para> | 2710 | </para> |
2584 | <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); | 2711 | <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); |
2585 | int (*resume) (struct drm_device *);</synopsis> | 2712 | int (*resume) (struct drm_device *);</synopsis> |
2586 | <para> | 2713 | <para> |
2587 | Those are legacy suspend and resume methods. New driver should use the | 2714 | Those are legacy suspend and resume methods which |
2588 | power management interface provided by their bus type (usually through | 2715 | <emphasis>only</emphasis> work with the legacy shadow-attach driver |
2589 | the struct <structname>device_driver</structname> dev_pm_ops) and set | 2716 | registration functions. New driver should use the power management |
2590 | these methods to NULL. | 2717 | interface provided by their bus type (usually through |
2591 | </para> | 2718 | the struct <structname>device_driver</structname> dev_pm_ops) and set |
2592 | </sect1> | 2719 | these methods to NULL. |
2720 | </para> | ||
2721 | </sect2> | ||
2593 | 2722 | ||
2594 | <sect1> | 2723 | <sect2> |
2595 | <title>DMA services</title> | 2724 | <title>Legacy DMA Services</title> |
2596 | <para> | 2725 | <para> |
2597 | This should cover how DMA mapping etc. is supported by the core. | 2726 | This should cover how DMA mapping etc. is supported by the core. |
2598 | These functions are deprecated and should not be used. | 2727 | These functions are deprecated and should not be used. |
2599 | </para> | 2728 | </para> |
2729 | </sect2> | ||
2600 | </sect1> | 2730 | </sect1> |
2601 | </chapter> | 2731 | </chapter> |
2602 | 2732 | ||
@@ -2658,8 +2788,8 @@ int (*resume) (struct drm_device *);</synopsis> | |||
2658 | DRM core provides multiple character-devices for user-space to use. | 2788 | DRM core provides multiple character-devices for user-space to use. |
2659 | Depending on which device is opened, user-space can perform a different | 2789 | Depending on which device is opened, user-space can perform a different |
2660 | set of operations (mainly ioctls). The primary node is always created | 2790 | set of operations (mainly ioctls). The primary node is always created |
2661 | and called <term>card<num></term>. Additionally, a currently | 2791 | and called card<num>. Additionally, a currently |
2662 | unused control node, called <term>controlD<num></term> is also | 2792 | unused control node, called controlD<num> is also |
2663 | created. The primary node provides all legacy operations and | 2793 | created. The primary node provides all legacy operations and |
2664 | historically was the only interface used by userspace. With KMS, the | 2794 | historically was the only interface used by userspace. With KMS, the |
2665 | control node was introduced. However, the planned KMS control interface | 2795 | control node was introduced. However, the planned KMS control interface |
@@ -2674,21 +2804,21 @@ int (*resume) (struct drm_device *);</synopsis> | |||
2674 | nodes were introduced. Render nodes solely serve render clients, that | 2804 | nodes were introduced. Render nodes solely serve render clients, that |
2675 | is, no modesetting or privileged ioctls can be issued on render nodes. | 2805 | is, no modesetting or privileged ioctls can be issued on render nodes. |
2676 | Only non-global rendering commands are allowed. If a driver supports | 2806 | Only non-global rendering commands are allowed. If a driver supports |
2677 | render nodes, it must advertise it via the <term>DRIVER_RENDER</term> | 2807 | render nodes, it must advertise it via the DRIVER_RENDER |
2678 | DRM driver capability. If not supported, the primary node must be used | 2808 | DRM driver capability. If not supported, the primary node must be used |
2679 | for render clients together with the legacy drmAuth authentication | 2809 | for render clients together with the legacy drmAuth authentication |
2680 | procedure. | 2810 | procedure. |
2681 | </para> | 2811 | </para> |
2682 | <para> | 2812 | <para> |
2683 | If a driver advertises render node support, DRM core will create a | 2813 | If a driver advertises render node support, DRM core will create a |
2684 | separate render node called <term>renderD<num></term>. There will | 2814 | separate render node called renderD<num>. There will |
2685 | be one render node per device. No ioctls except PRIME-related ioctls | 2815 | be one render node per device. No ioctls except PRIME-related ioctls |
2686 | will be allowed on this node. Especially <term>GEM_OPEN</term> will be | 2816 | will be allowed on this node. Especially GEM_OPEN will be |
2687 | explicitly prohibited. Render nodes are designed to avoid the | 2817 | explicitly prohibited. Render nodes are designed to avoid the |
2688 | buffer-leaks, which occur if clients guess the flink names or mmap | 2818 | buffer-leaks, which occur if clients guess the flink names or mmap |
2689 | offsets on the legacy interface. Additionally to this basic interface, | 2819 | offsets on the legacy interface. Additionally to this basic interface, |
2690 | drivers must mark their driver-dependent render-only ioctls as | 2820 | drivers must mark their driver-dependent render-only ioctls as |
2691 | <term>DRM_RENDER_ALLOW</term> so render clients can use them. Driver | 2821 | DRM_RENDER_ALLOW so render clients can use them. Driver |
2692 | authors must be careful not to allow any privileged ioctls on render | 2822 | authors must be careful not to allow any privileged ioctls on render |
2693 | nodes. | 2823 | nodes. |
2694 | </para> | 2824 | </para> |
@@ -2749,15 +2879,73 @@ int (*resume) (struct drm_device *);</synopsis> | |||
2749 | </sect1> | 2879 | </sect1> |
2750 | 2880 | ||
2751 | </chapter> | 2881 | </chapter> |
2882 | </part> | ||
2883 | <part id="drmDrivers"> | ||
2884 | <title>DRM Drivers</title> | ||
2752 | 2885 | ||
2753 | <!-- API reference --> | 2886 | <partintro> |
2887 | <para> | ||
2888 | This second part of the DRM Developer's Guide documents driver code, | ||
2889 | implementation details and also all the driver-specific userspace | ||
2890 | interfaces. Especially since all hardware-acceleration interfaces to | ||
2891 | userspace are driver specific for efficiency and other reasons these | ||
2892 | interfaces can be rather substantial. Hence every driver has its own | ||
2893 | chapter. | ||
2894 | </para> | ||
2895 | </partintro> | ||
2754 | 2896 | ||
2755 | <appendix id="drmDriverApi"> | 2897 | <chapter id="drmI915"> |
2756 | <title>DRM Driver API</title> | 2898 | <title>drm/i915 Intel GFX Driver</title> |
2757 | <para> | 2899 | <para> |
2758 | Include auto-generated API reference here (need to reference it | 2900 | The drm/i915 driver supports all (with the exception of some very early |
2759 | from paragraphs above too). | 2901 | models) integrated GFX chipsets with both Intel display and rendering |
2902 | blocks. This excludes a set of SoC platforms with an SGX rendering unit, | ||
2903 | those have basic support through the gma500 drm driver. | ||
2760 | </para> | 2904 | </para> |
2761 | </appendix> | 2905 | <sect1> |
2906 | <title>Display Hardware Handling</title> | ||
2907 | <para> | ||
2908 | This section covers everything related to the display hardware including | ||
2909 | the mode setting infrastructure, plane, sprite and cursor handling and | ||
2910 | display, output probing and related topics. | ||
2911 | </para> | ||
2912 | <sect2> | ||
2913 | <title>Mode Setting Infrastructure</title> | ||
2914 | <para> | ||
2915 | The i915 driver is thus far the only DRM driver which doesn't use the | ||
2916 | common DRM helper code to implement mode setting sequences. Thus it | ||
2917 | has its own tailor-made infrastructure for executing a display | ||
2918 | configuration change. | ||
2919 | </para> | ||
2920 | </sect2> | ||
2921 | <sect2> | ||
2922 | <title>Plane Configuration</title> | ||
2923 | <para> | ||
2924 | This section covers plane configuration and composition with the | ||
2925 | primary plane, sprites, cursors and overlays. This includes the | ||
2926 | infrastructure to do atomic vsync'ed updates of all this state and | ||
2927 | also tightly coupled topics like watermark setup and computation, | ||
2928 | framebuffer compression and panel self refresh. | ||
2929 | </para> | ||
2930 | </sect2> | ||
2931 | <sect2> | ||
2932 | <title>Output Probing</title> | ||
2933 | <para> | ||
2934 | This section covers output probing and related infrastructure like the | ||
2935 | hotplug interrupt storm detection and mitigation code. Note that the | ||
2936 | i915 driver still uses most of the common DRM helper code for output | ||
2937 | probing, so those sections fully apply. | ||
2938 | </para> | ||
2939 | </sect2> | ||
2940 | </sect1> | ||
2762 | 2941 | ||
2942 | <sect1> | ||
2943 | <title>Memory Management and Command Submission</title> | ||
2944 | <para> | ||
2945 | This sections covers all things related to the GEM implementation in the | ||
2946 | i915 driver. | ||
2947 | </para> | ||
2948 | </sect1> | ||
2949 | </chapter> | ||
2950 | </part> | ||
2763 | </book> | 2951 | </book> |