Fix vertex upload regression
[chai.git] / README.md
1 # Chai
2
3 Chai is a project to reverse engineer the
4 [Mali](https://en.wikipedia.org/wiki/Mali_(GPU)) T-series of GPUs. It
5 focuses on the T760 which is found in the
6 [RK3288](https://en.wikipedia.org/wiki/RK3288) SoC. This SoC is notably
7 used in the Veyron design for Chromebooks, which are supported in
8 [Libreboot](https://libreboot.org).
9
10 Chai has its roots in [lima](https://limadriver.org/) by Luc Verhaegen
11 et al. Lima targets the older Mali cores; chai is for the newer cores
12 like its unreleased successor Tamil. At the time of writing, no code is
13 shared with lima, although limare was useful for illustrative purposes.
14 One of lima's authors, Connor Abbott, did release reverse-engineered
15 documentation for the [T6xx ISA](http://limadriver.org/T6xx+ISA/), which
16 will be used in chai, along with his
17 [disassembler](https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools.git).
18
19 Chai, oolong, and black are for T GPUs. It's a joke. Get it?
20
21 ## Roadmap
22
23 - [x] Basic understanding of the ecosystem
24 - [x] Fork of the [kernel module](https://notabug.org/chai/oolong)
25 - [x] Basic userspace code to interact with the kernel module
26 - [x] Basic fuzzing from userspace
27 - [x] Basic command stream [tracer](https://notabug.org/chai/black)
28 - [ ] Deep decoding of command stream
29 - [ ] Command stream replay and synthesis
30 - [ ] High-level command stream recreation
31 - [x] Partial ISA (thanks Connor!)
32 - [ ] ISA disassembler
33 - [ ] ISA assembler
34 - [ ] Complete ISA reverse-engineering 
35 - [ ] Native kernel interface
36 - [ ] Mesa driver
37 - [ ] Gallium compiler
38 - [ ] Performance tuning
39 - [ ] Upstream!
40
41 ## Legal aspects
42
43 The shim is free (GPLv2) and is modified for chai. No other ARM code is
44 used in chai.
45
46 Initial reverse engineering used a combination of fuzzing and reading
47 through the shim source code. Later notes observe communication between
48 the shim and the blob. A tracer was written that hooks into the shim
49 function `kbase_ioctl`, called for each message. It decodes the message
50 and dumps it to the console for inspection and replay.
51
52 The Mali Offline Shader Compiler may be useful for ISA reverse
53 engineering. See the [Lima
54 wiki](http://limadriver.org/Mali_Offline_Shader_Compiler/) which
55 discusses legal aspects here.
56
57 None of chai's authors are or were affiliated with ARM Limited.