mirror of
https://gitlab.freedesktop.org/mesa/mesa.git
synced 2024-12-05 00:05:25 +08:00
4eef5628c8
The custom envvar directive is strange. It overloads the global namespace, where there's already a well-known envvar directive, but the envvar role won't resolve to envvars defined using the custom directive. It's not really critical to declare the type and default value here, and many descriptions already include this. Let's just use the plain one, and let the description take care of the details where needed. Reviewed-by: Yonggang Luo <luoyonggang@gmail.com> Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19593>
258 lines
9.8 KiB
ReStructuredText
258 lines
9.8 KiB
ReStructuredText
Lima
|
||
====
|
||
|
||
Lima is an open source graphics driver which supports Mali Utgard
|
||
(Mali-4xx) embedded GPUs from ARM. It’s a reverse-engineered,
|
||
community-developed driver, and is not endorsed by ARM. Lima was
|
||
upstreamed in Mesa 19.1 and Linux kernel 5.2.
|
||
|
||
======== ============ ===========
|
||
Product Architecture Status
|
||
======== ============ ===========
|
||
Mali-400 Utgard Supported
|
||
Mali-450 Utgard Supported
|
||
Mali-470 Utgard Unsupported
|
||
======== ============ ===========
|
||
|
||
Newer Mali chips based on the Midgard/Bifrost architectures (Mali T or G
|
||
series) are handled by the :doc:`Panfrost <panfrost>` driver, not Lima.
|
||
|
||
Note that the Mali GPU is only for rendering: the GPU does not control a
|
||
display and has little to do with display-related issues.
|
||
Each SoC has its own separate display engine to control the display
|
||
output. To display the contents rendered by the Mali GPU to a screen, a
|
||
separate `display driver <#display-drivers>`__ is also required, which
|
||
is able to share buffers with the GPU. In Mesa, this is handled by
|
||
``kmsro``.
|
||
|
||
Supported APIs
|
||
--------------
|
||
|
||
Lima mainly targets **OpenGL ES 2.0**, as well as **OpenGL 2.1**
|
||
(desktop) to some extent.
|
||
|
||
The OpenGL (desktop) implementation is enabled by Mesa and Gallium,
|
||
where it is possible to reuse the same implementation backend. That way,
|
||
it is possible to support running a majority of Linux desktop
|
||
applications designed for OpenGL. It is not possible to fully support
|
||
OpenGL (desktop), though, due to hardware limitations. Some (but not
|
||
all) features of OpenGL 2.1 that are not supported directly in hardware
|
||
are enabled by internal shader transformations.
|
||
Check the `known hardware limitations <#known-hardware-limitations>`__
|
||
list for additional information.
|
||
|
||
**OpenGL ES 1.1** and **OpenGL 1.x** are also provided by Mesa and
|
||
similarly supported to some extent in Lima.
|
||
|
||
Display drivers
|
||
---------------
|
||
|
||
These are some display drivers that have been tested with Lima:
|
||
|
||
- Allwinner: ``sun4i-drm``
|
||
- Amlogic: ``meson``
|
||
- Ericsson MCDE: ``mcde``
|
||
- Exynos: ``exynos``
|
||
- Rockchip: ``rockchip``
|
||
- Tiny DRM: ``tinydrm``
|
||
|
||
Environment variables
|
||
---------------------
|
||
|
||
These are some Lima-specific environment variables that may aid in
|
||
debugging. None of this is required for normal use.
|
||
|
||
.. envvar:: LIMA_DEBUG
|
||
|
||
accepts the following comma-separated list of flags:
|
||
|
||
``bocache``
|
||
print debug info for BO cache
|
||
``diskcache``
|
||
print debug info for shader disk cache
|
||
``dump``
|
||
dump GPU command stream to ``$PWD/lima.dump``
|
||
``gp``
|
||
print GP shader compiler result of each stage
|
||
``noblit``
|
||
use generic u_blitter instead of Lima-specific
|
||
``nobocache``
|
||
disable BO cache
|
||
``nogrowheap``
|
||
disable growable heap buffer
|
||
``notiling``
|
||
don’t use tiled buffers
|
||
``pp``
|
||
print PP shader compiler result of each stage
|
||
``precompile``
|
||
precompile shaders for shader-db
|
||
``shaderdb``
|
||
print shader information for shaderdb
|
||
``singlejob``
|
||
disable multi job optimization
|
||
|
||
|
||
.. envvar:: LIMA_CTX_NUM_PLB
|
||
|
||
set number of PLB per context (used for development purposes)
|
||
|
||
.. envvar:: LIMA_PLB_MAX_BLK
|
||
|
||
set PLB max block (used for development purposes)
|
||
|
||
.. envvar:: LIMA_PPIR_FORCE_SPILLING
|
||
|
||
force spilling of variables in PPIR (used for development purposes)
|
||
|
||
.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE
|
||
|
||
set PP stream cache size (used for development purposes)
|
||
|
||
Known hardware limitations
|
||
--------------------------
|
||
|
||
Here are some known caveats in OpenGL support:
|
||
|
||
- ``glPolygonMode()`` with ``GL_LINE`` is not supported. This is not part of
|
||
OpenGL ES 2.0 and so it is not possible to reverse engineer.
|
||
|
||
- Precision limitations in fragment shaders:
|
||
|
||
- In general, only
|
||
`FP16 <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`__
|
||
precision is supported in fragment shaders. Specifying ``highp``
|
||
will have no effect.
|
||
- Integers are not supported in hardware, they are lowered down to
|
||
FP16.
|
||
- There is a higher precision (FP24) path for texture lookups, if
|
||
there is *no* math performed on texture coordinates obtained from
|
||
varyings. If there is *any* calculation done in the texture
|
||
coordinates, the texture coordinates will fall back to FP16 and
|
||
that may affect the quality of the texture lookup.
|
||
|
||
- Lima supports FP16 textures in OpenGL ES (through
|
||
:ext:`GL_OES_texture_half_float<GL_OES_texture_float>`), but not in OpenGL.
|
||
This is because it would require :ext:`GL_ARB_texture_float` which would
|
||
also require 32-bit float textures, that the Mali-4xx does not support.
|
||
- Rendering to FP16 is possible, but the result is clamped to the
|
||
[0.0,1.0] range.
|
||
|
||
Bug Reporting
|
||
-------------
|
||
|
||
Please try the latest Mesa development branch or at least Mesa latest
|
||
release before reporting issues. Please review the
|
||
:doc:`Mesa bug report guidelines <../bugs>`.
|
||
|
||
Issues should be filed as a `Mesa issue`_.
|
||
Lima tags will be added accordingly by the developers.
|
||
|
||
`apitrace <https://github.com/apitrace/apitrace>`__ traces are very
|
||
welcome in issue reports and significantly ease the debug and fix
|
||
process.
|
||
|
||
FAQ
|
||
---
|
||
|
||
Will Lima support OpenGL 3.x+ / OpenGL ES 3.x+ / OpenCL / Vulkan ?
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
**No.** The Mali-4xx was designed to implement OpenGL ES 2.0 and OpenGL
|
||
ES 1.1. The hardware lacks features to properly implement some features
|
||
required by newer APIs.
|
||
|
||
How complete is Lima? Is reverse engineering complete?
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
At the time of writing, with local runs of the
|
||
`OpenGL ES Conformance Tests <https://github.com/KhronosGroup/VK-GL-CTS/>`__
|
||
(dEQP) for OpenGL ES 2.0, Lima reports **97%** pass rate.
|
||
This coverage is on par with coverage provided by the ARM Mali driver.
|
||
Some tests that pass with Lima fail on Mali and vice versa. Some of
|
||
these issues are related to precision limitations which likely don’t
|
||
affect end user applications.
|
||
|
||
The work being done in Lima at this stage is largely decoupled from
|
||
reverse engineering. Reverse engineering is still useful sometimes to
|
||
obtain details on how to implement low level features (e.g. how to
|
||
enable some missing legacy OpenGL ES 1.1 feature to support an
|
||
additional application), but with the current information Lima is
|
||
already able to cover most of OpenGL ES 2.0.
|
||
|
||
Much of the work to be done is related to plumbing features within the
|
||
frameworks provided by Mesa, fixing bugs (e.g. artifacts or crashes in
|
||
specific applications), shader compiler improvements, which are not
|
||
necessarily related to new hardware bits and not related at all to the
|
||
Mali driver.
|
||
|
||
When will Feature XYZ be supported? Is there a roadmap for features implementation?
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
There is no established roadmap for features implementation.
|
||
Development is driven by improving coverage in existing OpenGL test
|
||
frameworks, adding support to features that enable more existing Linux
|
||
applications, and fixing issues reported by users in their applications.
|
||
Development is fully based on community contributions.
|
||
|
||
If some desired feature is missing or there is an OpenGL-related bug
|
||
while running some application, please do file a `Mesa issue`_.
|
||
Issues that are not reproduced by an existing test suite or common
|
||
application and are also not reported by users are just likely not going
|
||
to be noticed and fixed.
|
||
|
||
How does Lima compare to Mali (blob)? How is performance?
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
By the fact that Lima is a fully open source driver and leverages a lot
|
||
of Mesa and Linux functionality, feature-wise Lima is able to support
|
||
many things that Mali does not. As already mentioned, supporting OpenGL
|
||
2.1 is one of them. This allows Lima to support many more Linux desktop
|
||
applications out of the box. Through the abstractions implemented in
|
||
Mesa, Lima supports a number of OpenGL and OpenGL ES extensions that
|
||
originally the Mali did not support. Lima is also aligned with the
|
||
current status of the Linux graphics stack and is therefore able to
|
||
leverage modern features (such as zero copy pipelines) much more
|
||
seamlessly. Finally, Lima continues to gain improvements as the Linux
|
||
graphics ecosystem evolves.
|
||
|
||
The entire software stack of the Mali driver and the software stack with
|
||
Lima are significantly different which makes it hard to offer a single
|
||
number comparison for performance of the GPU driver. The difference
|
||
really depends on the type of application. Keep in mind that hardware
|
||
containing a Mali-4xx is usually quite limited for modern standards and
|
||
it might not perform as well as hoped. For example: while it is now
|
||
technically possible to run full GL modern desktop environments at 1080p
|
||
(which might not have been even possible before due to limited GL
|
||
support), that might not be very performant due to memory bandwidth, CPU
|
||
and GPU limitations of the SoC with a Mali-4xx.
|
||
|
||
Overall performance with Lima is good for many applications where the
|
||
Mali-4xx would be a suitable target GPU.
|
||
But bottom line for a performance evaluation, you need to try with your
|
||
target application. If performance with Lima does not seem right in some
|
||
application where it should reasonably perform better, please file a
|
||
`Mesa issue`_ (in which case some indication on why Lima in particular
|
||
seems to be the bottleneck would also be helpful).
|
||
|
||
Communication channels
|
||
----------------------
|
||
|
||
- `#lima channel <irc://irc.oftc.net/lima>`__ on `irc.oftc.net <https://webchat.oftc.net/>`__
|
||
- `lima mailing list <https://lists.freedesktop.org/mailman/listinfo/lima>`__
|
||
- `dri-devel mailing list <https://lists.freedesktop.org/mailman/listinfo/dri-devel>`__
|
||
|
||
Dump tool
|
||
---------
|
||
|
||
A tool to dump the runtime of the closed source Mali driver for
|
||
reverse engineering is available at:
|
||
https://gitlab.freedesktop.org/lima/mali-syscall-tracker
|
||
|
||
Reference
|
||
---------
|
||
|
||
Luc Verhaegen’s original Lima site:
|
||
https://web.archive.org/web/20180101212947/http://limadriver.org/
|
||
|
||
.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/-/issues?label_name%5B%5D=lima
|