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