# Lima

Lima is an open source graphics driver which supports Mali-400/450 embedded
GPUs from ARM via reverse engineering.
It was upstreamed in mesa 19.1 and linux kernel 5.2.

This page aims to provide an overview and track the status of the project.
Note that as lima is now part of the respective upstream projects, it is
increasingly less necessary to take special steps to install or use it; the goal
is that it becomes just another driver automatically available in mesa and
linux distribution builds.

Note that the Mali GPU is only for rendering, not for controlling a display.
Each SoC has its own separate display engine to control the display output.
Therefore, to display the contents rendered by the Mali GPU, a separate display
driver is also required.
In mesa, this is handled by the `kmsro` infrastructure. If you want a display,
make sure `kmsro` is also enabled in your mesa build and that your kernel also
includes both lima and the driver for your display engine.

Lima is a project still in heavy development. If possible, please try
the latest mesa master branch before reporting issues, as they may
have already been worked on. In the current state, there is
little-to-none support/backport to older releases.

## Status
### Applications

Note: The following is not meant to be an exhaustive list of applications.
Please report an
[issue](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima)
if applications misbehave, whether they are listed here or not.

* desktop
  * Wayland: weston, sway, etc.
  * Xorg+modesetting+glamor
* mobile desktop
  * Phosh, KDE and others on the [pinephone](https://wiki.pine64.org/index.php?title=PinePhone_Software_Releases)
  * Android ([user report](https://gitlab.freedesktop.org/lima/mesa/issues/120))
* Games
  * supertuxkart (GL2 renderer)
  * Quake 3 arena
  * neverball
* User Applications
  * Firefox (webgl)
* off-screen rendering
  * off-screen reference application at https://github.com/yuq/gfx/tree/master/gbm-surface
* Test applications
  * kmscube
  * glxgears, es2\_gears
  * glmark2-es2, glmark2-es2-drm, glmark2-es2-wayland
  * https://github.com/yuq/gfx
* Test/development suites
  * piglit
  * deqp
  * shader-db

### Tested on
* Mali-400
* Mali-450

Mali-470 currently unsupported.

### Display drivers
* Allwinner: `sun4i-drm`
* Amlogic: `meson`
* Exynos: `exynos`
* Ericsson MCDE: `mcde`
* Rockchip: `rockchip`
* Tinydrm: `tinydrm`

## Issues
Please try the latest mesa master branch or at least mesa latest release before
reporting issues.
Please review the mesa3d bug report [guidelines](https://docs.mesa3d.org/bugs.html).

File and track issues in the [upstream mesa issue tracker](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima).
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.

## Development
The lima driver has been upstreamed to linux kernel and mesa, so work is done on
the upstream repos now. The mesa and linux repos in the freedesktop lima gitlab
group are deprecated.

### kernel driver
kernel driver changes need to be sent to the [drm-misc repo](https://cgit.freedesktop.org/drm/drm-misc/).
There is no gitlab project for it, so we have to send patches to dri-devel
mailing list for review, please also CC lima mailing list to get lima
developers' attention.

Reference: [https://dri.freedesktop.org/docs/drm/gpu/introduction.html](https://dri.freedesktop.org/docs/drm/gpu/introduction.html)

### mesa driver
mesa driver changes need to be sent to [mesa repo](https://gitlab.freedesktop.org/mesa/mesa).
We prefer to send gitlab MR for review which ease the review process and has CI
test. Please add `lima` MR tag to get lima developers' attention.

After review and CI pass, please rebase the MR with reviewers'
Reviewed-by/Acked-by/Tested-by tags added and select the checkbox of: `Allow
commits from members who can merge to the target branch` to permit other
developers to merge your MR if you don't have merge permission.

Reference: [https://docs.mesa3d.org/submittingpatches.html](https://docs.mesa3d.org/submittingpatches.html)

### doc
For project topics, still this readme page. MRs can be submitted to this page.
For technical topics, we may write into upstream repos, like kernel
Documentation/gpu/lima.rst.

## Build and install

Lima is now included in upstream mesa, so there are no lima-specific steps other
than just enabling lima in mesa.
Lima is now increasingly being included in popular linux distributions so it
might be just be included in your kernel and mesa-dri-drivers or equivalent
package.
In this case, nothing needs to be done to install lima on your system.
Below is a quick start guide, but keep in mind that these are just standard mesa
build steps as described in the [mesa documentation](https://www.mesa3d.org/meson.html).

### common process
1. build Linux kernel with lima driver from: https://cgit.freedesktop.org/drm/drm-misc/
2. build mesa with lima driver from: https://gitlab.freedesktop.org/mesa/mesa

mesa build
```
meson build -Dvulkan-drivers=[] -Dplatforms=x11,drm,wayland -Ddri-drivers=[] -Dgallium-drivers=lima,kmsro
ninja -C build install
```

### xorg.conf
For xserver >=1.20, if you have issues with starting X, you may try the
following xorg.conf:
```
Section "ServerFlags"
        Option  "AutoAddGPU" "off"
        Option "Debug" "dmabuf_capable"
EndSection

Section "OutputClass"
        Identifier "Lima"
        MatchDriver "<display DRM driver>"
        Driver "modesetting"
        Option "PrimaryGPU" "true"
EndSection
```
Note that the Mali GPU is only for rendering, each SoC has its own separate
display engine.
You need to find your display engine DRM driver name and replace `<display DRM driver>`
with it. For example, see the list of display drivers mentioned above.

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

## TODO
* List of known [mesa issues](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima).

## FAQ
### Will lima support OpenGL 3.x+ / OpenGL ES 3.x+ / OpenCL / Vulkan ?

**No.** The Mali-400/450 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.

For example: the shader cores operate mostly around 16-bit floating point
values. It is not possible to operate in any other higher precision and even
integer operations have to be lowered to 16-bit float. The Mali-400/450 also
do not implement a unified shader model.

### What APIs does lima support?

lima mainly targets **OpenGL ES 2.0**, as well as **OpenGL 2.x** (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.
However, note that some features of OpenGL 2.x are not supported in hardware in
the Mali-400/450 which makes it impossible to fully support it in lima.
Usually these are less common features which are not also part of the OpenGL ES
2.0 spec, things such as `glPolygonMode(GL_FRONT_AND_BACK, GL_LINE)` or texture
wrapping with `GL_CLAMP_TO_BORDER`.
Some (but not all) features of OpenGL 2.x are not supported directly in
hardware but are emulated internally through shader transformations.

**OpenGL ES 1.1** and **OpenGL 1.x** are also provided by mesa and similarly
supported to some extent in lima.

### How complete is lima? Is reverse engineering complete?

On an OpenGL ES 2.0 level with local runs of the
[OpenGL ES Conformance Tests](https://github.com/KhronosGroup/VK-GL-CTS/)
(deqp), lima currently reports around **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 low 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 already.
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 (glitches, crashes in specific cases),
shader compiler optimizations, which are not necessarily related to new
hardware bits and unrelated 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 currently driven by improving coverage of 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](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima).
Issues that are not covered by an existing test suite or common application and
are also not reported 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.x (not just ES) 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 fully 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.
lima continues to gain improvements as the linux 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-400/450 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, that might not be very performant due to memory bandwidth, CPU and
GPU limitations.

Overall performance with lima is already good enough for many applications
where the Mali-400/450 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](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima)
(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
* lima [mailing list](https://lists.freedesktop.org/mailman/listinfo/lima)
* dri-devel [mailing list](https://lists.freedesktop.org/mailman/listinfo/dri-devel)

## Reference
* Luc Verhaegen's original Lima site: http://web.archive.org/web/20180106112822/http://limadriver.org/