README.md 11.6 KB
Newer Older
Erico Nunes's avatar
Erico Nunes committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
# 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.

Qiang Yu's avatar
Qiang Yu committed
26
## Status
Erico Nunes's avatar
Erico Nunes committed
27 28
### Applications

29 30 31 32
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.
Erico Nunes's avatar
Erico Nunes committed
33

Qiang Yu's avatar
Qiang Yu committed
34
* desktop
Erico Nunes's avatar
Erico Nunes committed
35
  * Wayland: weston, sway, etc.
36 37 38 39
  * 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))
Erico Nunes's avatar
Erico Nunes committed
40 41 42
* Games
  * supertuxkart (GL2 renderer)
  * Quake 3 arena
43
  * neverball
Erico Nunes's avatar
Erico Nunes committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
* 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

62 63
Mali-470 currently unsupported.

Erico Nunes's avatar
Erico Nunes committed
64 65 66 67 68 69 70 71 72 73 74
### 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.
75
Please review the mesa3d bug report [guidelines](https://docs.mesa3d.org/bugs.html).
Erico Nunes's avatar
Erico Nunes committed
76 77 78 79 80 81

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.
Qiang Yu's avatar
Qiang Yu committed
82 83

## Development
Erico Nunes's avatar
Erico Nunes committed
84 85 86
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.
Qiang Yu's avatar
Qiang Yu committed
87 88

### kernel driver
Erico Nunes's avatar
Erico Nunes committed
89 90 91 92 93
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.

94
Reference: [https://dri.freedesktop.org/docs/drm/gpu/introduction.html](https://dri.freedesktop.org/docs/drm/gpu/introduction.html)
Qiang Yu's avatar
Qiang Yu committed
95 96

### mesa driver
Erico Nunes's avatar
Erico Nunes committed
97 98 99
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.
Qiang Yu's avatar
Qiang Yu committed
100

Erico Nunes's avatar
Erico Nunes committed
101 102 103 104
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.
Qiang Yu's avatar
Qiang Yu committed
105

106
Reference: [https://docs.mesa3d.org/submittingpatches.html](https://docs.mesa3d.org/submittingpatches.html)
Qiang Yu's avatar
Qiang Yu committed
107 108

### doc
Erico Nunes's avatar
Erico Nunes committed
109 110 111
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.
Qiang Yu's avatar
Qiang Yu committed
112 113

## Build and install
Erico Nunes's avatar
Erico Nunes committed
114 115 116 117 118 119 120 121 122 123

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).

Qiang Yu's avatar
Qiang Yu committed
124 125 126 127 128 129
### 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
```
Erico Nunes's avatar
Erico Nunes committed
130
meson build -Dvulkan-drivers=[] -Dplatforms=x11,drm,wayland -Ddri-drivers=[] -Dgallium-drivers=lima,kmsro
Qiang Yu's avatar
Qiang Yu committed
131 132 133
ninja -C build install
```

Qiang Yu's avatar
Qiang Yu committed
134
### xorg.conf
Erico Nunes's avatar
Erico Nunes committed
135 136
For xserver >=1.20, if you have issues with starting X, you may try the
following xorg.conf:
Qiang Yu's avatar
Qiang Yu committed
137 138 139 140 141 142 143 144 145 146 147 148 149
```
Section "ServerFlags"
        Option  "AutoAddGPU" "off"
        Option "Debug" "dmabuf_capable"
EndSection

Section "OutputClass"
        Identifier "Lima"
        MatchDriver "<display DRM driver>"
        Driver "modesetting"
        Option "PrimaryGPU" "true"
EndSection
```
Erico Nunes's avatar
Erico Nunes committed
150 151 152 153 154 155 156 157
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:
Qiang Yu's avatar
Qiang Yu committed
158 159 160
  * https://gitlab.freedesktop.org/lima/mali-syscall-tracker

## TODO
Erico Nunes's avatar
Erico Nunes committed
161
* List of known [mesa issues](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima).
Qiang Yu's avatar
Qiang Yu committed
162

163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263
## 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).
Qiang Yu's avatar
Qiang Yu committed
264

Erico Nunes's avatar
Erico Nunes committed
265
## Communication channels
Qiang Yu's avatar
Qiang Yu committed
266

Erico Nunes's avatar
Erico Nunes committed
267 268 269
* \#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)
Qiang Yu's avatar
Qiang Yu committed
270 271 272

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