From: Erico Nunes Date: Wed, 21 Apr 2021 23:15:06 +0000 (+0200) Subject: docs/lima: add an initial page for Lima X-Git-Tag: upstream/21.2.3~4333 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=48d48fbf3c59bd2aad5e62ce74994bb661528562;p=platform%2Fupstream%2Fmesa.git docs/lima: add an initial page for Lima This is a cleaned up and updated version of the readme page for Lima that was until now being maintained separately. Let's move it in-tree so it is maintained along with the pages for other similar drivers. Signed-off-by: Erico Nunes Reviewed-by: Erik Faye-Lund Reviewed-by: Vasily Khoruzhick Reviewed-by: Eric Anholt Reviewed-by: Qiang Yu Reviewed-by: Andreas Baierl Part-of: --- diff --git a/docs/drivers/lima.rst b/docs/drivers/lima.rst new file mode 100644 index 0000000..1b16c01 --- /dev/null +++ b/docs/drivers/lima.rst @@ -0,0 +1,254 @@ +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 ` 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 ("") + +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 (None) + +set number of PLB per context (used for development purposes) + +.. envvar:: LIMA_PLB_MAX_BLK (None) + +set PLB max block (used for development purposes) + +.. envvar:: LIMA_PPIR_FORCE_SPILLING (None) + +force spilling of variables in ppir (used for development purposes) + +.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE (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 `__ + 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 `__ 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.freenode.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: +http://web.archive.org/web/20180106112822/http://limadriver.org/ + +.. _Mesa issue: https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima diff --git a/docs/index.rst b/docs/index.rst index ffece71..72c59f3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,6 +83,7 @@ and other operating systems. drivers/d3d12 drivers/freedreno + drivers/lima drivers/llvmpipe drivers/openswr drivers/panfrost diff --git a/docs/systems.rst b/docs/systems.rst index 9e95dfd..52a6c88 100644 --- a/docs/systems.rst +++ b/docs/systems.rst @@ -21,8 +21,7 @@ Hardware drivers include: Wiki `__ - Broadcom VideoCore 4, 5. See `This Week in V3D `__ -- ARM Mali Utgard. See `Lima - Wiki `__ +- ARM Mali Utgard. See :doc:`Lima ` - ARM Mali Midgard, Bifrost. See :doc:`Panfrost ` - Vivante GCxxx. See `Etnaviv Wiki `__