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- Xilinx ZynqMP: ``zynqmp-dpsub`` 59 60Environment variables 61--------------------- 62 63These are some Lima-specific environment variables that may aid in 64debugging. None of this is required for normal use. 65 66.. envvar:: LIMA_DEBUG 67 68 accepts the following comma-separated list of flags: 69 70 ``bocache`` 71 print debug info for BO cache 72 ``diskcache`` 73 print debug info for shader disk cache 74 ``dump`` 75 dump GPU command stream to ``$PWD/lima.dump`` 76 ``gp`` 77 print GP shader compiler result of each stage 78 ``noblit`` 79 use generic u_blitter instead of Lima-specific 80 ``nobocache`` 81 disable BO cache 82 ``nogrowheap`` 83 disable growable heap buffer 84 ``notiling`` 85 don’t use tiled buffers 86 ``pp`` 87 print PP shader compiler result of each stage 88 ``precompile`` 89 precompile shaders for shader-db 90 ``shaderdb`` 91 print shader information for shaderdb 92 ``singlejob`` 93 disable multi job optimization 94 95 96.. envvar:: LIMA_CTX_NUM_PLB 97 98 set number of PLB per context (used for development purposes) 99 100.. envvar:: LIMA_PLB_MAX_BLK 101 102 set PLB max block (used for development purposes) 103 104.. envvar:: LIMA_PPIR_FORCE_SPILLING 105 106 force spilling of variables in PPIR (used for development purposes) 107 108.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE 109 110 set PP stream cache size (used for development purposes) 111 112Known hardware limitations 113-------------------------- 114 115Here are some known caveats in OpenGL support: 116 117- ``glPolygonMode()`` with ``GL_LINE`` is not supported. This is not part of 118 OpenGL ES 2.0 and so it is not possible to reverse engineer. 119 120- Precision limitations in fragment shaders: 121 122 - In general, only 123 `FP16 <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`__ 124 precision is supported in fragment shaders. Specifying ``highp`` 125 will have no effect. 126 - Integers are not supported in hardware, they are lowered down to 127 FP16. 128 - There is a higher precision (FP24) path for texture lookups, if 129 there is *no* math performed on texture coordinates obtained from 130 varyings. If there is *any* calculation done in the texture 131 coordinates, the texture coordinates will fall back to FP16 and 132 that may affect the quality of the texture lookup. 133 134- Lima supports FP16 textures in OpenGL ES (through 135 :ext:`GL_OES_texture_half_float<GL_OES_texture_float>`), but not in OpenGL. 136 This is because it would require :ext:`GL_ARB_texture_float` which would 137 also require 32-bit float textures, that the Mali-4xx does not support. 138- Rendering to FP16 is possible, but the result is clamped to the 139 [0.0,1.0] range. 140 141Bug Reporting 142------------- 143 144Please try the latest Mesa development branch or at least Mesa latest 145release before reporting issues. Please review the 146:doc:`Mesa bug report guidelines <../bugs>`. 147 148Issues should be filed as a `Mesa issue`_. 149Lima tags will be added accordingly by the developers. 150 151`apitrace <https://github.com/apitrace/apitrace>`__ traces are very 152welcome in issue reports and significantly ease the debug and fix 153process. 154 155FAQ 156--- 157 158Will Lima support OpenGL 3.x+ / OpenGL ES 3.x+ / OpenCL / Vulkan ? 159~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 160 161**No.** The Mali-4xx was designed to implement OpenGL ES 2.0 and OpenGL 162ES 1.1. The hardware lacks features to properly implement some features 163required by newer APIs. 164 165How complete is Lima? Is reverse engineering complete? 166~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 167 168At the time of writing, with local runs of the 169`OpenGL ES Conformance Tests <https://github.com/KhronosGroup/VK-GL-CTS/>`__ 170(dEQP) for OpenGL ES 2.0, Lima reports **97%** pass rate. 171This coverage is on par with coverage provided by the ARM Mali driver. 172Some tests that pass with Lima fail on Mali and vice versa. Some of 173these issues are related to precision limitations which likely don’t 174affect end user applications. 175 176The work being done in Lima at this stage is largely decoupled from 177reverse engineering. Reverse engineering is still useful sometimes to 178obtain details on how to implement low level features (e.g. how to 179enable some missing legacy OpenGL ES 1.1 feature to support an 180additional application), but with the current information Lima is 181already able to cover most of OpenGL ES 2.0. 182 183Much of the work to be done is related to plumbing features within the 184frameworks provided by Mesa, fixing bugs (e.g. artifacts or crashes in 185specific applications), shader compiler improvements, which are not 186necessarily related to new hardware bits and not related at all to the 187Mali driver. 188 189When will Feature XYZ be supported? Is there a roadmap for features implementation? 190~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 191 192There is no established roadmap for features implementation. 193Development is driven by improving coverage in existing OpenGL test 194frameworks, adding support to features that enable more existing Linux 195applications, and fixing issues reported by users in their applications. 196Development is fully based on community contributions. 197 198If some desired feature is missing or there is an OpenGL-related bug 199while running some application, please do file a `Mesa issue`_. 200Issues that are not reproduced by an existing test suite or common 201application and are also not reported by users are just likely not going 202to be noticed and fixed. 203 204How does Lima compare to Mali (blob)? How is performance? 205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 206 207By the fact that Lima is a fully open source driver and leverages a lot 208of Mesa and Linux functionality, feature-wise Lima is able to support 209many things that Mali does not. As already mentioned, supporting OpenGL 2102.1 is one of them. This allows Lima to support many more Linux desktop 211applications out of the box. Through the abstractions implemented in 212Mesa, Lima supports a number of OpenGL and OpenGL ES extensions that 213originally the Mali did not support. Lima is also aligned with the 214current status of the Linux graphics stack and is therefore able to 215leverage modern features (such as zero copy pipelines) much more 216seamlessly. Finally, Lima continues to gain improvements as the Linux 217graphics ecosystem evolves. 218 219The entire software stack of the Mali driver and the software stack with 220Lima are significantly different which makes it hard to offer a single 221number comparison for performance of the GPU driver. The difference 222really depends on the type of application. Keep in mind that hardware 223containing a Mali-4xx is usually quite limited for modern standards and 224it might not perform as well as hoped. For example: while it is now 225technically possible to run full GL modern desktop environments at 1080p 226(which might not have been even possible before due to limited GL 227support), that might not be very performant due to memory bandwidth, CPU 228and GPU limitations of the SoC with a Mali-4xx. 229 230Overall performance with Lima is good for many applications where the 231Mali-4xx would be a suitable target GPU. 232But bottom line for a performance evaluation, you need to try with your 233target application. If performance with Lima does not seem right in some 234application where it should reasonably perform better, please file a 235`Mesa issue`_ (in which case some indication on why Lima in particular 236seems to be the bottleneck would also be helpful). 237 238Communication channels 239---------------------- 240 241- `#lima channel <irc://irc.oftc.net/lima>`__ on `irc.oftc.net <https://webchat.oftc.net/>`__ 242- `lima mailing list <https://lists.freedesktop.org/mailman/listinfo/lima>`__ 243- `dri-devel mailing list <https://lists.freedesktop.org/mailman/listinfo/dri-devel>`__ 244 245Dump tool 246--------- 247 248A tool to dump the runtime of the closed source Mali driver for 249reverse engineering is available at: 250https://gitlab.freedesktop.org/lima/mali-syscall-tracker 251 252Reference 253--------- 254 255Luc Verhaegen’s original Lima site: 256https://web.archive.org/web/20180101212947/http://limadriver.org/ 257 258.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/-/issues?label_name%5B%5D=lima 259