← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/drivers/lima.rst

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/drivers/lima.rst
1
 
Lima
2
 
====
3
 
 
4
 
Lima is an open source graphics driver which supports Mali Utgard
5
 
(Mali-4xx) embedded GPUs from ARM. It’s a reverse-engineered,
6
 
community-developed driver, and is not endorsed by ARM. Lima was
7
 
upstreamed in Mesa 19.1 and Linux kernel 5.2.
8
 
 
9
 
========  ============ ===========
10
 
Product   Architecture   Status
11
 
========  ============ ===========
12
 
Mali-400     Utgard     Supported
13
 
Mali-450     Utgard     Supported
14
 
Mali-470     Utgard    Unsupported
15
 
========  ============ ===========
16
 
 
17
 
Newer Mali chips based on the Midgard/Bifrost architectures (Mali T or G
18
 
series) are handled by the :doc:`Panfrost <panfrost>` driver, not Lima.
19
 
 
20
 
Note that the Mali GPU is only for rendering: the GPU does not control a
21
 
display and has little to do with display-related issues.
22
 
Each SoC has its own separate display engine to control the display
23
 
output. To display the contents rendered by the Mali GPU to a screen, a
24
 
separate `display driver <#display-drivers>`__ is also required, which
25
 
is able to share buffers with the GPU. In Mesa, this is handled by
26
 
``kmsro``.
27
 
 
28
 
Supported APIs
29
 
--------------
30
 
 
31
 
Lima mainly targets **OpenGL ES 2.0**, as well as **OpenGL 2.1**
32
 
(desktop) to some extent.
33
 
 
34
 
The OpenGL (desktop) implementation is enabled by Mesa and Gallium,
35
 
where it is possible to reuse the same implementation backend. That way,
36
 
it is possible to support running a majority of Linux desktop
37
 
applications designed for OpenGL. It is not possible to fully support
38
 
OpenGL (desktop), though, due to hardware limitations. Some (but not
39
 
all) features of OpenGL 2.1 that are not supported directly in hardware
40
 
are enabled by internal shader transformations.
41
 
Check the `known hardware limitations <#known-hardware-limitations>`__
42
 
list for additional information.
43
 
 
44
 
**OpenGL ES 1.1** and **OpenGL 1.x** are also provided by Mesa and
45
 
similarly supported to some extent in Lima.
46
 
 
47
 
Display drivers
48
 
---------------
49
 
 
50
 
These are some display drivers that have been tested with Lima:
51
 
 
52
 
- Allwinner: ``sun4i-drm``
53
 
- Amlogic: ``meson``
54
 
- Ericsson MCDE: ``mcde``
55
 
- Exynos: ``exynos``
56
 
- Rockchip: ``rockchip``
57
 
- Tiny DRM: ``tinydrm``
58
 
 
59
 
Environment variables
60
 
---------------------
61
 
 
62
 
These are some Lima-specific environment variables that may aid in
63
 
debugging. None of this is required for normal use.
64
 
 
65
 
.. envvar:: LIMA_DEBUG <flags> ("")
66
 
 
67
 
accepts the following comma-separated list of flags:
68
 
 
69
 
  ``bocache``
70
 
    print debug info for BO cache
71
 
  ``dump``
72
 
    dump GPU command stream to ``$PWD/lima.dump``
73
 
  ``gp``
74
 
    print GP shader compiler result of each stage
75
 
  ``nobocache``
76
 
    disable BO cache
77
 
  ``nogrowheap``
78
 
    disable growable heap buffer
79
 
  ``notiling``
80
 
    don’t use tiled buffers
81
 
  ``pp``
82
 
    print PP shader compiler result of each stage
83
 
  ``precompile``
84
 
    precompile shaders for shader-db
85
 
  ``shaderdb``
86
 
    print shader information for shaderdb
87
 
  ``singlejob``
88
 
    disable multi job optimization
89
 
 
90
 
.. envvar:: LIMA_CTX_NUM_PLB <int> (None)
91
 
 
92
 
set number of PLB per context (used for development purposes)
93
 
 
94
 
.. envvar:: LIMA_PLB_MAX_BLK <int> (None)
95
 
 
96
 
set PLB max block (used for development purposes)
97
 
 
98
 
.. envvar:: LIMA_PPIR_FORCE_SPILLING <int> (None)
99
 
 
100
 
force spilling of variables in ppir (used for development purposes)
101
 
 
102
 
.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE <int> (None)
103
 
 
104
 
set PP stream cache size (used for development purposes)
105
 
 
106
 
Known hardware limitations
107
 
--------------------------
108
 
 
109
 
Here are some known caveats in OpenGL support:
110
 
 
111
 
- ``glPolygonMode()`` with ``GL_LINE`` is not supported. This is not part of
112
 
  OpenGL ES 2.0 and so it is not possible to reverse engineer.
113
 
 
114
 
- Precision limitations in fragment shaders:
115
 
 
116
 
  - In general, only
117
 
    `FP16 <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`__
118
 
    precision is supported in fragment shaders. Specifying ``highp``
119
 
    will have no effect.
120
 
  - Integers are not supported in hardware, they are lowered down to
121
 
    FP16.
122
 
  - There is a higher precision (FP24) path for texture lookups, if
123
 
    there is *no* math performed on texture coordinates obtained from
124
 
    varyings. If there is *any* calculation done in the texture
125
 
    coordinates, the texture coordinates will fall back to FP16 and
126
 
    that may affect the quality of the texture lookup.
127
 
 
128
 
- Lima supports FP16 textures in OpenGL ES (through
129
 
  ``GL_OES_texture_half_float``), but not in OpenGL.
130
 
  This is because it would require ``ARB_texture_float`` which would also
131
 
  require 32-bit float textures, that the Mali-4xx does not support.
132
 
- Rendering to FP16 is possible, but the result is clamped to the
133
 
  [0.0,1.0] range.
134
 
 
135
 
Bug Reporting
136
 
-------------
137
 
 
138
 
Please try the latest Mesa development branch or at least Mesa latest
139
 
release before reporting issues. Please review the
140
 
:doc:`Mesa bug report guidelines <../bugs>`.
141
 
 
142
 
Issues should be filed as a `Mesa issue`_.
143
 
Lima tags will be added accordingly by the developers.
144
 
 
145
 
`apitrace <https://github.com/apitrace/apitrace>`__ traces are very
146
 
welcome in issue reports and significantly ease the debug and fix
147
 
process.
148
 
 
149
 
FAQ
150
 
---
151
 
 
152
 
Will Lima support OpenGL 3.x+ / OpenGL ES 3.x+ / OpenCL / Vulkan ?
153
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154
 
 
155
 
**No.** The Mali-4xx was designed to implement OpenGL ES 2.0 and OpenGL
156
 
ES 1.1. The hardware lacks features to properly implement some features
157
 
required by newer APIs.
158
 
 
159
 
How complete is Lima? Is reverse engineering complete?
160
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161
 
 
162
 
At the time of writing, with local runs of the
163
 
`OpenGL ES Conformance Tests <https://github.com/KhronosGroup/VK-GL-CTS/>`__
164
 
(deqp) for OpenGL ES 2.0, Lima reports **97%** pass rate.
165
 
This coverage is on par with coverage provided by the ARM Mali driver.
166
 
Some tests that pass with Lima fail on Mali and vice versa. Some of
167
 
these issues are related to precision limitations which likely don’t
168
 
affect end user applications.
169
 
 
170
 
The work being done in Lima at this stage is largely decoupled from
171
 
reverse engineering. Reverse engineering is still useful sometimes to
172
 
obtain details on how to implement low level features (e.g. how to
173
 
enable some missing legacy OpenGL ES 1.1 feature to support an
174
 
additional application), but with the current information Lima is
175
 
already able to cover most of OpenGL ES 2.0.
176
 
 
177
 
Much of the work to be done is related to plumbing features within the
178
 
frameworks provided by Mesa, fixing bugs (e.g. artifacts or crashes in
179
 
specific applications), shader compiler improvements, which are not
180
 
necessarily related to new hardware bits and not related at all to the
181
 
Mali driver.
182
 
 
183
 
When will Feature XYZ be supported? Is there a roadmap for features implementation?
184
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185
 
 
186
 
There is no established roadmap for features implementation.
187
 
Development is driven by improving coverage in existing OpenGL test
188
 
frameworks, adding support to features that enable more existing Linux
189
 
applications, and fixing issues reported by users in their applications.
190
 
Development is fully based on community contributions.
191
 
 
192
 
If some desired feature is missing or there is an OpenGL-related bug
193
 
while running some application, please do file a `Mesa issue`_.
194
 
Issues that are not reproduced by an existing test suite or common
195
 
application and are also not reported by users are just likely not going
196
 
to be noticed and fixed.
197
 
 
198
 
How does Lima compare to Mali (blob)? How is performance?
199
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
200
 
 
201
 
By the fact that Lima is a fully open source driver and leverages a lot
202
 
of Mesa and Linux functionality, feature-wise Lima is able to support
203
 
many things that Mali does not. As already mentioned, supporting OpenGL
204
 
2.1 is one of them. This allows Lima to support many more Linux desktop
205
 
applications out of the box. Through the abstractions implemented in
206
 
Mesa, Lima supports a number of OpenGL and OpenGL ES extensions that
207
 
originally the Mali did not support. Lima is also aligned with the
208
 
current status of the Linux graphics stack and is therefore able to
209
 
leverage modern features (such as zero copy pipelines) much more
210
 
seamlessly. Finally, Lima continues to gain improvements as the Linux
211
 
graphics ecosystem evolves.
212
 
 
213
 
The entire software stack of the Mali driver and the software stack with
214
 
Lima are significantly different which makes it hard to offer a single
215
 
number comparison for performance of the GPU driver. The difference
216
 
really depends on the type of application. Keep in mind that hardware
217
 
containing a Mali-4xx is usually quite limited for modern standards and
218
 
it might not perform as well as hoped. For example: while it is now
219
 
technically possible to run full GL modern desktop environments at 1080p
220
 
(which might not have been even possible before due to limited GL
221
 
support), that might not be very performant due to memory bandwidth, CPU
222
 
and GPU limitations of the SoC with a Mali-4xx.
223
 
 
224
 
Overall performance with Lima is good for many applications where the
225
 
Mali-4xx would be a suitable target GPU.
226
 
But bottom line for a performance evaluation, you need to try with your
227
 
target application. If performance with Lima does not seem right in some
228
 
application where it should reasonably perform better, please file a
229
 
`Mesa issue`_ (in which case some indication on why Lima in particular
230
 
seems to be the bottleneck would also be helpful).
231
 
 
232
 
Communication channels
233
 
----------------------
234
 
 
235
 
- `#lima channel <irc://irc.oftc.net/lima>`__ on `irc.oftc.net <https://webchat.oftc.net/>`__
236
 
- `lima mailing list <https://lists.freedesktop.org/mailman/listinfo/lima>`__
237
 
- `dri-devel mailing list <https://lists.freedesktop.org/mailman/listinfo/dri-devel>`__
238
 
 
239
 
Dump tool
240
 
---------
241
 
 
242
 
A tool to dump the runtime of the closed source Mali driver for
243
 
reverse engineering is available at:
244
 
https://gitlab.freedesktop.org/lima/mali-syscall-tracker
245
 
 
246
 
Reference
247
 
---------
248
 
 
249
 
Luc Verhaegen’s original Lima site:
250
 
http://web.archive.org/web/20180106112822/http://limadriver.org/
251
 
 
252
 
.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima