Commit | Line | Data |
---|---|---|
fa6d095e TR |
1 | =============================================== |
2 | drm/tegra NVIDIA Tegra GPU and display driver | |
3 | =============================================== | |
4 | ||
5 | NVIDIA Tegra SoCs support a set of display, graphics and video functions via | |
6 | the host1x controller. host1x supplies command streams, gathered from a push | |
7 | buffer provided directly by the CPU, to its clients via channels. Software, | |
8 | or blocks amongst themselves, can use syncpoints for synchronization. | |
9 | ||
10 | Up until, but not including, Tegra124 (aka Tegra K1) the drm/tegra driver | |
11 | supports the built-in GPU, comprised of the gr2d and gr3d engines. Starting | |
12 | with Tegra124 the GPU is based on the NVIDIA desktop GPU architecture and | |
13 | supported by the drm/nouveau driver. | |
14 | ||
15 | The drm/tegra driver supports NVIDIA Tegra SoC generations since Tegra20. It | |
16 | has three parts: | |
17 | ||
18 | - A host1x driver that provides infrastructure and access to the host1x | |
19 | services. | |
20 | ||
21 | - A KMS driver that supports the display controllers as well as a number of | |
22 | outputs, such as RGB, HDMI, DSI, and DisplayPort. | |
23 | ||
24 | - A set of custom userspace IOCTLs that can be used to submit jobs to the | |
25 | GPU and video engines via host1x. | |
26 | ||
27 | Driver Infrastructure | |
28 | ===================== | |
29 | ||
30 | The various host1x clients need to be bound together into a logical device in | |
31 | order to expose their functionality to users. The infrastructure that supports | |
32 | this is implemented in the host1x driver. When a driver is registered with the | |
33 | infrastructure it provides a list of compatible strings specifying the devices | |
34 | that it needs. The infrastructure creates a logical device and scan the device | |
35 | tree for matching device nodes, adding the required clients to a list. Drivers | |
36 | for individual clients register with the infrastructure as well and are added | |
37 | to the logical host1x device. | |
38 | ||
39 | Once all clients are available, the infrastructure will initialize the logical | |
40 | device using a driver-provided function which will set up the bits specific to | |
41 | the subsystem and in turn initialize each of its clients. | |
42 | ||
43 | Similarly, when one of the clients is unregistered, the infrastructure will | |
44 | destroy the logical device by calling back into the driver, which ensures that | |
45 | the subsystem specific bits are torn down and the clients destroyed in turn. | |
46 | ||
47 | Host1x Infrastructure Reference | |
48 | ------------------------------- | |
49 | ||
50 | .. kernel-doc:: include/linux/host1x.h | |
51 | ||
52 | .. kernel-doc:: drivers/gpu/host1x/bus.c | |
53 | :export: | |
54 | ||
55 | Host1x Syncpoint Reference | |
56 | -------------------------- | |
57 | ||
58 | .. kernel-doc:: drivers/gpu/host1x/syncpt.c | |
59 | :export: | |
60 | ||
61 | KMS driver | |
62 | ========== | |
63 | ||
64 | The display hardware has remained mostly backwards compatible over the various | |
65 | Tegra SoC generations, up until Tegra186 which introduces several changes that | |
66 | make it difficult to support with a parameterized driver. | |
67 | ||
68 | Display Controllers | |
69 | ------------------- | |
70 | ||
71 | Tegra SoCs have two display controllers, each of which can be associated with | |
72 | zero or more outputs. Outputs can also share a single display controller, but | |
73 | only if they run with compatible display timings. Two display controllers can | |
74 | also share a single framebuffer, allowing cloned configurations even if modes | |
75 | on two outputs don't match. A display controller is modelled as a CRTC in KMS | |
76 | terms. | |
77 | ||
78 | On Tegra186, the number of display controllers has been increased to three. A | |
79 | display controller can no longer drive all of the outputs. While two of these | |
80 | controllers can drive both DSI outputs and both SOR outputs, the third cannot | |
81 | drive any DSI. | |
82 | ||
83 | Windows | |
84 | ~~~~~~~ | |
85 | ||
86 | A display controller controls a set of windows that can be used to composite | |
87 | multiple buffers onto the screen. While it is possible to assign arbitrary Z | |
88 | ordering to individual windows (by programming the corresponding blending | |
89 | registers), this is currently not supported by the driver. Instead, it will | |
90 | assume a fixed Z ordering of the windows (window A is the root window, that | |
91 | is, the lowest, while windows B and C are overlaid on top of window A). The | |
92 | overlay windows support multiple pixel formats and can automatically convert | |
93 | from YUV to RGB at scanout time. This makes them useful for displaying video | |
94 | content. In KMS, each window is modelled as a plane. Each display controller | |
95 | has a hardware cursor that is exposed as a cursor plane. | |
96 | ||
97 | Outputs | |
98 | ------- | |
99 | ||
100 | The type and number of supported outputs varies between Tegra SoC generations. | |
101 | All generations support at least HDMI. While earlier generations supported the | |
102 | very simple RGB interfaces (one per display controller), recent generations no | |
103 | longer do and instead provide standard interfaces such as DSI and eDP/DP. | |
104 | ||
105 | Outputs are modelled as a composite encoder/connector pair. | |
106 | ||
107 | RGB/LVDS | |
108 | ~~~~~~~~ | |
109 | ||
110 | This interface is no longer available since Tegra124. It has been replaced by | |
111 | the more standard DSI and eDP interfaces. | |
112 | ||
113 | HDMI | |
114 | ~~~~ | |
115 | ||
116 | HDMI is supported on all Tegra SoCs. Starting with Tegra210, HDMI is provided | |
117 | by the versatile SOR output, which supports eDP, DP and HDMI. The SOR is able | |
118 | to support HDMI 2.0, though support for this is currently not merged. | |
119 | ||
120 | DSI | |
121 | ~~~ | |
122 | ||
123 | Although Tegra has supported DSI since Tegra30, the controller has changed in | |
124 | several ways in Tegra114. Since none of the publicly available development | |
125 | boards prior to Dalmore (Tegra114) have made use of DSI, only Tegra114 and | |
126 | later are supported by the drm/tegra driver. | |
127 | ||
128 | eDP/DP | |
129 | ~~~~~~ | |
130 | ||
131 | eDP was first introduced in Tegra124 where it was used to drive the display | |
132 | panel for notebook form factors. Tegra210 added support for full DisplayPort | |
133 | support, though this is currently not implemented in the drm/tegra driver. | |
134 | ||
135 | Userspace Interface | |
136 | =================== | |
137 | ||
138 | The userspace interface provided by drm/tegra allows applications to create | |
139 | GEM buffers, access and control syncpoints as well as submit command streams | |
140 | to host1x. | |
141 | ||
142 | GEM Buffers | |
143 | ----------- | |
144 | ||
145 | The ``DRM_IOCTL_TEGRA_GEM_CREATE`` IOCTL is used to create a GEM buffer object | |
146 | with Tegra-specific flags. This is useful for buffers that should be tiled, or | |
147 | that are to be scanned out upside down (useful for 3D content). | |
148 | ||
149 | After a GEM buffer object has been created, its memory can be mapped by an | |
150 | application using the mmap offset returned by the ``DRM_IOCTL_TEGRA_GEM_MMAP`` | |
151 | IOCTL. | |
152 | ||
153 | Syncpoints | |
154 | ---------- | |
155 | ||
156 | The current value of a syncpoint can be obtained by executing the | |
157 | ``DRM_IOCTL_TEGRA_SYNCPT_READ`` IOCTL. Incrementing the syncpoint is achieved | |
158 | using the ``DRM_IOCTL_TEGRA_SYNCPT_INCR`` IOCTL. | |
159 | ||
160 | Userspace can also request blocking on a syncpoint. To do so, it needs to | |
161 | execute the ``DRM_IOCTL_TEGRA_SYNCPT_WAIT`` IOCTL, specifying the value of | |
162 | the syncpoint to wait for. The kernel will release the application when the | |
163 | syncpoint reaches that value or after a specified timeout. | |
164 | ||
165 | Command Stream Submission | |
166 | ------------------------- | |
167 | ||
168 | Before an application can submit command streams to host1x it needs to open a | |
169 | channel to an engine using the ``DRM_IOCTL_TEGRA_OPEN_CHANNEL`` IOCTL. Client | |
170 | IDs are used to identify the target of the channel. When a channel is no | |
171 | longer needed, it can be closed using the ``DRM_IOCTL_TEGRA_CLOSE_CHANNEL`` | |
172 | IOCTL. To retrieve the syncpoint associated with a channel, an application | |
173 | can use the ``DRM_IOCTL_TEGRA_GET_SYNCPT``. | |
174 | ||
175 | After opening a channel, submitting command streams is easy. The application | |
176 | writes commands into the memory backing a GEM buffer object and passes these | |
177 | to the ``DRM_IOCTL_TEGRA_SUBMIT`` IOCTL along with various other parameters, | |
178 | such as the syncpoints or relocations used in the job submission. |