--- /dev/null
+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
+enabling the ``kmsro`` driver in addition to Lima.
+
+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 <flags> ("")
+
+accepts the following comma-separated list of flags:
+
+ ``bocache``
+ print debug info for BO cache
+ ``dump``
+ dump GPU command stream to ``$PWD/lima.dump``
+ ``gp``
+ print GP shader compiler result of each stage
+ ``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 <int> (None)
+
+set number of PLB per context (used for development purposes)
+
+.. envvar:: LIMA_PLB_MAX_BLK <int> (None)
+
+set PLB max block (used for development purposes)
+
+.. envvar:: LIMA_PPIR_FORCE_SPILLING <int> (None)
+
+force spilling of variables in ppir (used for development purposes)
+
+.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE <int> (None)
+
+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.
+- Texture wrapping with ``GL_CLAMP_TO_BORDER`` 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
+ ``GL_OES_texture_half_float``), but not in OpenGL.
+ This is because it would require ``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://chat.freenode.net#lima>`__ on `irc.freenode.net <https://webchat.freenode.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:
+http://web.archive.org/web/20180106112822/http://limadriver.org/
+
+.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima
projects / platform / upstream / mesa.git / commitdiff