# 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 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 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 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`

- Xilinx ZynqMP: `zynqmp-dpsub`

## Environment variables

These are some Lima-specific environment variables that may aid in debugging. None of this is required for normal use.

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

LIMA_CTX_NUM_PLB

  set number of PLB per context (used for development purposes)

LIMA_PLB_MAX_BLK

  set PLB max block (used for development purposes)

LIMA_PPIR_FORCE_SPILLING

  force spilling of variables in PPIR (used for development purposes)

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 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 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 Mesa bug report guidelines.

Issues should be filed as a Mesa issue. Lima tags will be added accordingly by the developers.

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 (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 on irc.oftc.net

- lima mailing list

- dri-devel mailing list

## 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/