Write up additional findings in jobs.md
[chai.git] / jobs.md
1 This is a job-based architecture. All interesting behaviour (shaders,
2 rendering) is a result of jobs. Each job is sent from the driver across
3 the shim to the GPU. The job is encoded as a special data structure in
4 GPU memory.
5
6 There are two families of jobs, hardware jobs and software jobs.
7 Hardware jobs interact with the GPU directly. Software jobs are used to
8 manipulate the driver. Software jobs set BASE_JD_REQ_SOFT_JOB in the
9 .core_req field of the atom.
10
11 Hardware jobs contain the jc pointer into GPU memory. This points to the
12 job descriptor. All hardware jobs begin with the job descriptor header
13 which is found in the shim headers. The header contains a field,
14 job_type, which must be set according to the job type:
15
16 Byte  Job type
17 ----- ---------
18 0     Not started
19 1     Null
20 2     Set value
21 3     Cache flush
22 4     Compute
23 5     Vertex
24 6     (none)
25 7     Tiler
26 8     Fused
27 9     Fragment
28
29 This header contains a pointer to the next job, forming sequences of
30 hardware jobs.
31
32 The header also denotes the type of job (vertex, fragment, or tiler).
33 After the header there is simple type specific information.
34
35 Set value jobs follow:
36
37         struct tentative_set_value {
38                 uint64_t write_iut; /* Maybe vertices or shader? */
39                 uint64_t unknown1; /* Trace has it set at 3 */
40         }
41
42
43 Fragment jobs follow:
44
45         struct tentative_fragment {
46                 tile_coord_t min_tile_coord;
47                 tile_coord_t max_tile_coord;
48                 uint64_t fragment_fbd;
49         };
50
51 tile_coord_t is an ordered pair for specifying a tile. It is encoded as
52 a uint32_t where bits 0-11 represent the X coordinate and bits 16-27
53 represent the Y coordinate.
54
55 Tiles are 16x16 pixels. This can be concluded from max_tile_coord in
56 known render sizes.
57
58 Fragment jobs contain an external resource, the framebuffer (in shared
59 memory / UMM). The framebuffer is in BGRA8888 format.
60
61 Vertex and tiler jobs follow the same structure (pointers are 32-bit to
62 GPU memory):
63
64         struct tentative_vertex_tiler {
65                 uint32_t block1[11];
66                 uint32_t addresses1[4];
67                 tentative_shader *shaderMeta;
68                 vertex_buffer *vb;
69                 uint32_t addresses2[6];
70                 tentative_fbd *fbd;
71                 uint32_t addresses3[1];
72                 uint32_t block2[36];
73         }
74
75 In tiler jobs, block1[8] encodes the drawing mode used:
76
77 Byte  Mode
78 ----- -----
79 0x01  GL_POINTS
80 0x02  GL_LINES
81 0x08  GL_TRIANGLES
82 0x0A  GL_TRIANGLE_STRIP
83 0x0C  GL_TRIANGLE_FAN
84
85 The shader metadata follows a (very indirect) structure:
86
87         struct tentative_shader {
88                 uint64_t shader; /* ORed with 16 bytes of flags */
89                 uint32_t block[unknown];
90         }
91
92 Shader points directly to the compiled instruction stream. For vertex
93 jobs, this is the vertex shader. For tiler jobs, this is the fragment
94 shader.
95
96 Shaders are 128-bit aligned. The lower 128-bits of the shader metadata
97 pointer contains flags. Bit 0 is set for all shaders. Bit 2 is set for
98 vertex shaders. Bit 3 is set for fragment shaders.
99
100 The vertex buffer contains metadata about the vertices:
101
102         struct vertex_buffer {
103                 float *vertices;
104                 size_t vertex_size; /* sizeof(*vertices) * components */
105                 size_t buffer_size; /* vertex_size * num_vertices */
106         }