Commit 145df246 authored by Erico Nunes's avatar Erico Nunes

README.md: lima doc update

Update and simplify the lima documentation. Try to reference and direct
users more to upstream documentation as generally upstream processes can
be followed without special requirements for lima.

Try to remove old information and not maintain information that gets out
of date quickly. Point to the issue tracker rather than maintain a
duplicated list of issues and status here.
Signed-off-by: Erico Nunes's avatarErico Nunes <nunes.erico@gmail.com>
Reviewed-by: Qiang Yu's avatarQiang Yu <yuq825@gmail.com>
parent 6e02c319
# 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
Be able to run the following OGL application:
* off-screen rendering
* simple triangle: https://github.com/yuq/gfx/tree/master/gbm-surface
* vertex shader uniform: https://github.com/yuq/gfx/tree/master/gbm-surface-move
* multi varying: https://github.com/yuq/gfx/tree/master/gbm-surface-color
* multi draw: https://github.com/yuq/gfx/tree/master/gbm-surface-draw
* FBO: https://github.com/yuq/gfx/tree/master/gbm-surface-fbo
* **kmscube**: https://github.com/yuq/kmscube
* ./kmscube -d -D /dev/dri/renderD128
* ./kmscube -d -D /dev/dri/renderD128 -M rgba
* on-screen rendering
* PRIME export/import: https://github.com/enunes/mesa-test-programs/blob/master/gbm-bo-test.c
* renderonly lib: https://github.com/enunes/mesa-test-programs/blob/master/eglkms.c
* **kmscube**: https://cgit.freedesktop.org/mesa/kmscube/
* ./kmscube
* ./kmscube -M rgba
* ./kmscube -A
* **glmark2**: https://github.com/glmark2/glmark2
* glmark2-drm -b build
* glmark2-es2-drm -b build
* **kodi-gbm**: https://github.com/xbmc/xbmc
### Applications
Note: The following is not a exhaustive list of applications or test targets.
Please report an issue if other applications misbehave.
* desktop
* Xorg+modesetting+glamor
* es2gears
* weston
* es2gears
## Tested on
* Mali400
* Allwinner A10/A20/H3/A64
* Rockchip RK3188
* Exynos 4412
* Mali450
* Allwinner H5
* Rockchip RK3328
* Amlogic S905X
* Wayland: weston, sway, etc.
* Xorg+modesetting+glamor (has known issues)
* Games
* supertuxkart (GL2 renderer)
* Quake 3 arena
* User Applications
* Firefox (webgl)
* Android
* Users reported early working status of lima on android. Please follow:
* https://gitlab.freedesktop.org/lima/mesa/issues/120
* 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
### 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://www.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
Lima driver has been upstreamed to linux kernel and mesa, so we need to work on the upstream repo now. The mesa/linux repo in this lima gitlab group is deprecated. But we can still utilize this place for non-code needs.
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 send to drm-misc repo here 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.
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
### mesa driver
mesa driver changes need to be send to mesa repo here 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.
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 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 merge your MR if you don't have the merge permission.
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://www.mesa3d.org/submittingpatches.html
### issues
For lima spec issues and open discussion, we may continue using this lima gitlab group.
### doc
For project topic, still this WIKI. For technical topic, we may write into upstream repos, like kernel Documentation/gpu/lima.rst.
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=drm,x11 -Ddri-drivers=[] -Dgallium-drivers=lima,kmsro
meson build -Dvulkan-drivers=[] -Dplatforms=x11,drm,wayland -Ddri-drivers=[] -Dgallium-drivers=lima,kmsro
ninja -C build install
```
### buildroot
For those who want to use buildroot:
https://github.com/enunes/buildroot-external-lima
### OpenEmbedded
meson metadata with lima driver and test apps:
https://github.com/superna9999/meta-meson/tree/topic/mesa-lima
### xorg.conf
For xserver >=1.20, you can use the following 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"
......@@ -89,63 +142,33 @@ Section "OutputClass"
Option "PrimaryGPU" "true"
EndSection
```
Mali GPU is only for rendering, each SoC has its own seperated display engine. You need to find your display engine DRM driver name and replace `<display DRM driver>` with it. For example:
* Amlogic: meson
* Allwinner: sun4i-drm
* RockChip: rockchip
* Exynos: exynos
## Tool
* dump the runtime close source mali driver memory for reverse engineering
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
### mesa
* Newly refined GP compiler needs optimization, code size can be ~40% smaller compared to close source driver output, main problem should be creating too many moves but too few reg load/store
* PP compiler optimization, add post scheduler instruction combination which combine multi instructions into one instruction
* both GP and PP compiler need control flow and other un-implemented instruction support
* texture mipmap support
* still miss multi level render target support for auto generate mipmap
* Build a piglit test result list so that we can start clear them one by one.
* X11 desktop support
* https://gitlab.freedesktop.org/lima/mesa/issues/56#note_98690
* Wayland desktop support
* https://gitlab.freedesktop.org/lima/mesa/issues/59
* List of known [mesa issues](https://gitlab.freedesktop.org/mesa/mesa/issues?label_name%5B%5D=lima).
* PP compiler optimization, add post scheduler instruction combination which
combine multi instructions into one instruction
* optimization
* thread rendering that has dedicated render thread to submit command
### kernel
* Power management
## Done
### mesa
* GP compiler needs re-fine so that we can guarantee the vertex shader compilation succeed, Connor Abbott think out a new algorithm which should work
* Mesa renderonly lib support
* multi varying support, current implementation assumes we only have a single varying (gl_Position), command stream setup need be implemented for multi varying support
* command stream setup for multi draw, flush at once
* Mali450 initial support
* PP uniform support, command stream need be setup for PP uniform
* fix render fail when buffer is 800x600, maybe due to buffer alignment or command stream setup
* break the ABI come from libdrm_lima which is integrated into mesa for more efficiency especially the command submit interface
* texture support, both PP compiler and command stream need be changed
* command stream setup refine for multi FBO and dynamic buffer size
* Mali450 fully support
* EGL_ANDROID_native_fence_sync support
* Tiled texture format support
* implement EGL_KHR_partial_update
* New mesa NIR changes will always lower io/alu to scalar which is not expected by PP, need merge scalar back to vector or create a PIPE_CAP to disable it, see
* https://www.mail-archive.com/mesa-dev@lists.freedesktop.org/msg189216.html
## Communication channels
### kernel
* PRIME export support
* Mali450 initial support
* New task scheduler which can create a per OGL context fence context. We can use the new drm_sched which is from amdgpu and will be adopted by etnaviv too. drm_sched should be in Linux kernel 4.16.
* New memory management for non-continuous buffer object
* Different GPU mCLK frequency setup, current GPU mCLK frequency is the default frequency when system boot, but GPU should be able to run on a higher frequency.
* Mali450 fully support, include multi group GP/PP, DLBU
* submit support syn fd dep
* use TTM as MM
* \#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/
* compiler: https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools/
* compiler: https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment