docs/drivers/lima.rst

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 <flags> ("")

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 <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.

- 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://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:
http://web.archive.org/web/20180106112822/http://limadriver.org/

.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima