Rework README
authorCafe <cafe@not.applicable>
Sun, 30 Jul 2017 00:00:00 +0000 (00:00 +0000)
committerCafe <cafe@not.applicable>
Sun, 30 Jul 2017 19:09:06 +0000 (19:09 +0000)
README.md [deleted file]
framebuffer_memory_notes.md [deleted file]
job_memory_map.md [deleted file]
jobs.md [deleted file]
notes/README.md [new file with mode: 0644]
notes/framebuffer_memory_notes.md [new file with mode: 0644]
notes/job_memory_map.md [new file with mode: 0644]
notes/jobs.md [new file with mode: 0644]

diff --git a/README.md b/README.md
deleted file mode 100644 (file)
index 5278d9d..0000000
--- a/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Chai
-
-Chai is a project to reverse engineer the
-[Mali](https://en.wikipedia.org/wiki/Mali_(GPU)) T-series of GPUs. It
-focuses on the T760 which is found in the
-[RK3288](https://en.wikipedia.org/wiki/RK3288) SoC. This SoC is notably
-used in the Veyron design for Chromebooks, which are supported in
-[Libreboot](https://libreboot.org).
-
-Chai has its roots in [lima](https://limadriver.org/) by Luc Verhaegen
-et al. Lima targets the older Mali cores; chai is for the newer cores
-like its unreleased successor Tamil. At the time of writing, no code is
-shared with lima, although limare was useful for illustrative purposes.
-One of lima's authors, Connor Abbott, did release reverse-engineered
-documentation for the [T6xx ISA](http://limadriver.org/T6xx+ISA/), which
-will be used in chai, along with his
-[disassembler](https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools.git).
-
-Chai, oolong, and black are for T GPUs. It's a joke. Get it?
-
-## Roadmap
-
-- [x] Basic understanding of the ecosystem
-- [x] Fork of the [kernel module](https://notabug.org/chai/oolong)
-- [x] Basic userspace code to interact with the kernel module
-- [x] Basic fuzzing from userspace
-- [x] Basic command stream [tracer](https://notabug.org/chai/black)
-- [ ] Deep decoding of command stream
-- [ ] Command stream replay and synthesis
-- [ ] High-level command stream recreation
-- [x] Partial ISA (thanks Connor!)
-- [ ] ISA disassembler
-- [ ] ISA assembler
-- [ ] Complete ISA reverse-engineering 
-- [ ] Native kernel interface
-- [ ] Mesa driver
-- [ ] Gallium compiler
-- [ ] Performance tuning
-- [ ] Upstream!
-
-## Legal aspects
-
-The shim is free (GPLv2) and is modified for chai. No other ARM code is
-used in chai.
-
-Initial reverse engineering used a combination of fuzzing and reading
-through the shim source code. Later notes observe communication between
-the shim and the blob. A tracer was written that hooks into the shim
-function `kbase_ioctl`, called for each message. It decodes the message
-and dumps it to the console for inspection and replay.
-
-The Mali Offline Shader Compiler may be useful for ISA reverse
-engineering. See the [Lima
-wiki](http://limadriver.org/Mali_Offline_Shader_Compiler/) which
-discusses legal aspects here.
-
-None of chai's authors are or were affiliated with ARM Limited.
diff --git a/framebuffer_memory_notes.md b/framebuffer_memory_notes.md
deleted file mode 100644 (file)
index b800167..0000000
+++ /dev/null
@@ -1,20 +0,0 @@
-Framebuffer memory notes
-=========================
-
-The framebuffer is BGRA8888 format. It likely uses 16x16 tiles (TODO:
-verify). There is a stride of zeroes every 1856 bytes for unknown
-reasons.
-
----
-
-Zeroes at:
-
-1345548
-1347404
-1349260
-1351116
-
-Deltas of 1856 between zero regions; groups of 1804 valid pixels in
-between
-
-2048 = 1856 + 4 * 48?
diff --git a/job_memory_map.md b/job_memory_map.md
deleted file mode 100644 (file)
index d01590b..0000000
+++ /dev/null
@@ -1,25 +0,0 @@
-Coarse job descriptor memory map
-================================
-
-E000 (refreshed -- 0x340)
-E040 (descriptor)
-E060 (VERTEX)
-E120 (referenced in VERTEX)
-E140 (referenced in TILER)
-E170 (referenced in VERTEX + TILER)
-E180 (descriptor)
-E1A0 (TILER)
-E280 (refreshed -- 0x80)
-E300 (descriptor set)
-E320 (SET_VALUE)
-E340 (refreshed -- 0x80)
-E380 (descriptor)
-E3A0 (FRAGMENT)
-E3C0 (soft job chain, refreshed -- 0x28)
-
-Conclusions:
-
-FRAGMENT    <= 32  bytes
-SET_VALUE   <= 32  bytes
-VERTEX     <= 192 bytes
-TILER      <= 224 bytes
diff --git a/jobs.md b/jobs.md
deleted file mode 100644 (file)
index 08c3ec7..0000000
--- a/jobs.md
+++ /dev/null
@@ -1,106 +0,0 @@
-This is a job-based architecture. All interesting behaviour (shaders,
-rendering) is a result of jobs. Each job is sent from the driver across
-the shim to the GPU. The job is encoded as a special data structure in
-GPU memory.
-
-There are two families of jobs, hardware jobs and software jobs.
-Hardware jobs interact with the GPU directly. Software jobs are used to
-manipulate the driver. Software jobs set BASE_JD_REQ_SOFT_JOB in the
-.core_req field of the atom.
-
-Hardware jobs contain the jc pointer into GPU memory. This points to the
-job descriptor. All hardware jobs begin with the job descriptor header
-which is found in the shim headers. The header contains a field,
-job_type, which must be set according to the job type:
-
-Byte  Job type
------ ---------
-0     Not started
-1     Null
-2     Set value
-3     Cache flush
-4     Compute
-5     Vertex
-6     (none)
-7     Tiler
-8     Fused
-9     Fragment
-
-This header contains a pointer to the next job, forming sequences of
-hardware jobs.
-
-The header also denotes the type of job (vertex, fragment, or tiler).
-After the header there is simple type specific information.
-
-Set value jobs follow:
-
-       struct tentative_set_value {
-               uint64_t write_iut; /* Maybe vertices or shader? */
-               uint64_t unknown1; /* Trace has it set at 3 */
-       }
-
-
-Fragment jobs follow:
-
-       struct tentative_fragment {
-               tile_coord_t min_tile_coord;
-               tile_coord_t max_tile_coord;
-               uint64_t fragment_fbd;
-       };
-
-tile_coord_t is an ordered pair for specifying a tile. It is encoded as
-a uint32_t where bits 0-11 represent the X coordinate and bits 16-27
-represent the Y coordinate.
-
-Tiles are 16x16 pixels. This can be concluded from max_tile_coord in
-known render sizes.
-
-Fragment jobs contain an external resource, the framebuffer (in shared
-memory / UMM). The framebuffer is in BGRA8888 format.
-
-Vertex and tiler jobs follow the same structure (pointers are 32-bit to
-GPU memory):
-
-       struct tentative_vertex_tiler {
-               uint32_t block1[11];
-               uint32_t addresses1[4];
-               tentative_shader *shaderMeta;
-               vertex_buffer *vb;
-               uint32_t addresses2[6];
-               tentative_fbd *fbd;
-               uint32_t addresses3[1];
-               uint32_t block2[36];
-       }
-
-In tiler jobs, block1[8] encodes the drawing mode used:
-
-Byte  Mode
------ -----
-0x01  GL_POINTS
-0x02  GL_LINES
-0x08  GL_TRIANGLES
-0x0A  GL_TRIANGLE_STRIP
-0x0C  GL_TRIANGLE_FAN
-
-The shader metadata follows a (very indirect) structure:
-
-       struct tentative_shader {
-               uint64_t shader; /* ORed with 16 bytes of flags */
-               uint32_t block[unknown];
-       }
-
-Shader points directly to the compiled instruction stream. For vertex
-jobs, this is the vertex shader. For tiler jobs, this is the fragment
-shader.
-
-Shaders are 128-bit aligned. The lower 128-bits of the shader metadata
-pointer contains flags. Bit 0 is set for all shaders. Bit 2 is set for
-vertex shaders. Bit 3 is set for fragment shaders.
-
-The vertex buffer contains metadata about the vertices:
-
-       struct vertex_buffer {
-               float *vertices;
-               size_t vertex_size; /* sizeof(*vertices) * components */
-               size_t buffer_size; /* vertex_size * num_vertices */
-       }
diff --git a/notes/README.md b/notes/README.md
new file mode 100644 (file)
index 0000000..2d619fb
--- /dev/null
@@ -0,0 +1,81 @@
+# Chai
+
+Chai is a project to reverse engineer the
+[Mali](https://en.wikipedia.org/wiki/Mali_(GPU)) T-series of GPUs. It
+focuses on the T760 which is found in the
+[RK3288](https://en.wikipedia.org/wiki/RK3288) SoC. This SoC is notably
+used in the Veyron design for Chromebooks, which are supported in
+[Libreboot](https://libreboot.org).
+
+Chai has its roots in [lima](https://limadriver.org/) by Luc Verhaegen
+et al. Lima targets the older Mali cores; chai is for the newer cores
+like its unreleased successor Tamil. At the time of writing, no code is
+shared with lima, although limare was useful for illustrative purposes.
+One of lima's authors, Connor Abbott, did release reverse-engineered
+documentation for the [T6xx ISA](http://limadriver.org/T6xx+ISA/), which
+will be used in chai, along with his
+[disassembler](https://gitorious.org/open-gpu-tools/cwabbotts-open-gpu-tools.git).
+
+Documentation about the GPU is in notes/. Supporting source code is in
+src/. Source code is under the GPLv2.
+
+## Roadmap
+
+- [x] Basic understanding of the ecosystem
+- [x] Fork of the [kernel module](https://notabug.org/chai/oolong)
+- [x] Basic userspace code to interact with the kernel module
+- [x] Basic fuzzing from userspace
+- [x] Ioctl [tracer](https://notabug.org/chai/black)
+- [ ] Polygon drawing
+- [x] ...dump memory
+- [x] ...decode memory
+- [x] ...edit memory
+- [ ] ...replay
+- [ ] Textures
+- [ ] ...dump memory
+- [ ] ...decode memory
+- [ ] ...edit memory
+- [ ] ...replay
+- [ ] Primitive shaders
+- [x] ...dump memory
+- [x] ...reverse ISA (thanks cwabbott!)
+- [x] ...disassemble memory (ditto!)
+- [ ] ...reassemble
+- [ ] Complex shaders
+- [ ] ...reverse entire ISA
+- [ ] ...functional compiler
+- [ ] ...optimising compiling
+- [ ] Kernel interface
+- [x] ...port to mainline (thanks phh!)
+- [x] ...basic cleanup
+- [ ] ...use native kernel interfaces
+- [ ] ...upstreamed
+- [ ] Mesa driver
+- [ ] ...with toy programs and toy shaders
+- [ ] ...with shader compiler
+- [ ] ...with all commands supported
+- [ ] ...upstreamed
+
+This list is in flux as project requirements change.
+
+## Legal aspects
+
+The shim is free (GPLv2) and is modified for chai. No other ARM code is
+used in chai.
+
+Initial reverse engineering used a combination of fuzzing and reading
+through the shim source code. Later notes observe communication between
+the shim and the blob. A tracer was written that hooks into the shim
+function `kbase_ioctl`, called for each message. It decodes the message
+and dumps it to the console for inspection and replay.
+
+The Mali Offline Shader Compiler may be useful for ISA reverse
+engineering. See the [Lima
+wiki](http://limadriver.org/Mali_Offline_Shader_Compiler/) which
+discusses legal aspects here.
+
+None of chai's authors are or were affiliated with ARM Limited.
+
+## Name
+
+Chai, oolong, and black are for T GPUs. It's a joke. Get it?
diff --git a/notes/framebuffer_memory_notes.md b/notes/framebuffer_memory_notes.md
new file mode 100644 (file)
index 0000000..b800167
--- /dev/null
@@ -0,0 +1,20 @@
+Framebuffer memory notes
+=========================
+
+The framebuffer is BGRA8888 format. It likely uses 16x16 tiles (TODO:
+verify). There is a stride of zeroes every 1856 bytes for unknown
+reasons.
+
+---
+
+Zeroes at:
+
+1345548
+1347404
+1349260
+1351116
+
+Deltas of 1856 between zero regions; groups of 1804 valid pixels in
+between
+
+2048 = 1856 + 4 * 48?
diff --git a/notes/job_memory_map.md b/notes/job_memory_map.md
new file mode 100644 (file)
index 0000000..d01590b
--- /dev/null
@@ -0,0 +1,25 @@
+Coarse job descriptor memory map
+================================
+
+E000 (refreshed -- 0x340)
+E040 (descriptor)
+E060 (VERTEX)
+E120 (referenced in VERTEX)
+E140 (referenced in TILER)
+E170 (referenced in VERTEX + TILER)
+E180 (descriptor)
+E1A0 (TILER)
+E280 (refreshed -- 0x80)
+E300 (descriptor set)
+E320 (SET_VALUE)
+E340 (refreshed -- 0x80)
+E380 (descriptor)
+E3A0 (FRAGMENT)
+E3C0 (soft job chain, refreshed -- 0x28)
+
+Conclusions:
+
+FRAGMENT    <= 32  bytes
+SET_VALUE   <= 32  bytes
+VERTEX     <= 192 bytes
+TILER      <= 224 bytes
diff --git a/notes/jobs.md b/notes/jobs.md
new file mode 100644 (file)
index 0000000..08c3ec7
--- /dev/null
@@ -0,0 +1,106 @@
+This is a job-based architecture. All interesting behaviour (shaders,
+rendering) is a result of jobs. Each job is sent from the driver across
+the shim to the GPU. The job is encoded as a special data structure in
+GPU memory.
+
+There are two families of jobs, hardware jobs and software jobs.
+Hardware jobs interact with the GPU directly. Software jobs are used to
+manipulate the driver. Software jobs set BASE_JD_REQ_SOFT_JOB in the
+.core_req field of the atom.
+
+Hardware jobs contain the jc pointer into GPU memory. This points to the
+job descriptor. All hardware jobs begin with the job descriptor header
+which is found in the shim headers. The header contains a field,
+job_type, which must be set according to the job type:
+
+Byte  Job type
+----- ---------
+0     Not started
+1     Null
+2     Set value
+3     Cache flush
+4     Compute
+5     Vertex
+6     (none)
+7     Tiler
+8     Fused
+9     Fragment
+
+This header contains a pointer to the next job, forming sequences of
+hardware jobs.
+
+The header also denotes the type of job (vertex, fragment, or tiler).
+After the header there is simple type specific information.
+
+Set value jobs follow:
+
+       struct tentative_set_value {
+               uint64_t write_iut; /* Maybe vertices or shader? */
+               uint64_t unknown1; /* Trace has it set at 3 */
+       }
+
+
+Fragment jobs follow:
+
+       struct tentative_fragment {
+               tile_coord_t min_tile_coord;
+               tile_coord_t max_tile_coord;
+               uint64_t fragment_fbd;
+       };
+
+tile_coord_t is an ordered pair for specifying a tile. It is encoded as
+a uint32_t where bits 0-11 represent the X coordinate and bits 16-27
+represent the Y coordinate.
+
+Tiles are 16x16 pixels. This can be concluded from max_tile_coord in
+known render sizes.
+
+Fragment jobs contain an external resource, the framebuffer (in shared
+memory / UMM). The framebuffer is in BGRA8888 format.
+
+Vertex and tiler jobs follow the same structure (pointers are 32-bit to
+GPU memory):
+
+       struct tentative_vertex_tiler {
+               uint32_t block1[11];
+               uint32_t addresses1[4];
+               tentative_shader *shaderMeta;
+               vertex_buffer *vb;
+               uint32_t addresses2[6];
+               tentative_fbd *fbd;
+               uint32_t addresses3[1];
+               uint32_t block2[36];
+       }
+
+In tiler jobs, block1[8] encodes the drawing mode used:
+
+Byte  Mode
+----- -----
+0x01  GL_POINTS
+0x02  GL_LINES
+0x08  GL_TRIANGLES
+0x0A  GL_TRIANGLE_STRIP
+0x0C  GL_TRIANGLE_FAN
+
+The shader metadata follows a (very indirect) structure:
+
+       struct tentative_shader {
+               uint64_t shader; /* ORed with 16 bytes of flags */
+               uint32_t block[unknown];
+       }
+
+Shader points directly to the compiled instruction stream. For vertex
+jobs, this is the vertex shader. For tiler jobs, this is the fragment
+shader.
+
+Shaders are 128-bit aligned. The lower 128-bits of the shader metadata
+pointer contains flags. Bit 0 is set for all shaders. Bit 2 is set for
+vertex shaders. Bit 3 is set for fragment shaders.
+
+The vertex buffer contains metadata about the vertices:
+
+       struct vertex_buffer {
+               float *vertices;
+               size_t vertex_size; /* sizeof(*vertices) * components */
+               size_t buffer_size; /* vertex_size * num_vertices */
+       }