Remove unnecessary syncs
[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 Documentation about the GPU is in notes/. Supporting source code is in
20 src/. Source code is under the GPLv2.
21
22 ## Roadmap
23
24 - [x] Basic understanding of the ecosystem
25 - [x] Fork of the [kernel module](https://notabug.org/cafe/oolong)
26 - [x] Basic userspace code to interact with the kernel module
27 - [x] Basic fuzzing from userspace
28 - [x] Ioctl [tracer](https://notabug.org/cafe/black)
29 - [ ] Polygon drawing
30 - [x] ...dump memory
31 - [x] ...decode memory
32 - [x] ...edit memory
33 - [ ] ...replay
34 - [ ] Textures
35 - [ ] ...dump memory
36 - [ ] ...decode memory
37 - [ ] ...edit memory
38 - [ ] ...replay
39 - [ ] Primitive shaders
40 - [x] ...dump memory
41 - [x] ...reverse ISA (thanks cwabbott!)
42 - [x] ...disassemble memory (ditto!)
43 - [ ] ...reassemble
44 - [ ] Complex shaders
45 - [ ] ...reverse entire ISA
46 - [ ] ...functional compiler
47 - [ ] ...optimising compiling
48 - [ ] Kernel interface
49 - [x] ...port to mainline (thanks phh!)
50 - [x] ...basic cleanup
51 - [ ] ...use native kernel interfaces
52 - [ ] ...upstreamed
53 - [ ] Mesa driver
54 - [ ] ...with toy programs and toy shaders
55 - [ ] ...with shader compiler
56 - [ ] ...with all commands supported
57 - [ ] ...upstreamed
58
59 This list is in flux as project requirements change.
60
61 ## Legal aspects
62
63 The shim is free (GPLv2) and is modified for chai. No other ARM code is
64 used in chai.
65
66 Initial reverse engineering used a combination of fuzzing and reading
67 through the shim source code. Later notes observe communication between
68 the shim and the blob. A tracer was written that hooks into the shim
69 function `kbase_ioctl`, called for each message. It decodes the message
70 and dumps it to the console for inspection and replay.
71
72 The Mali Offline Shader Compiler may be useful for ISA reverse
73 engineering. See the [Lima
74 wiki](http://limadriver.org/Mali_Offline_Shader_Compiler/) which
75 discusses legal aspects here.
76
77 None of chai's authors are or were affiliated with ARM Limited.
78
79 ## Name
80
81 Chai, oolong, and black are for T GPUs. It's a joke. Get it?