Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
drm/tegra: Add driver documentation
Adds some driver documentation for Tegra. It provides a short overview
of the hardware and software architectures.
Signed-off-by: Thierry Reding <treding@nvidia.com>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Thierry Reding <treding@nvidia.com>
+179
+1
Documentation/gpu/index.rst
+1
Documentation/gpu/index.rst
+178
Documentation/gpu/tegra.rst
+178
Documentation/gpu/tegra.rst
···
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.