1.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
2
3=========
4Task List
5=========
6
7Tasks may have the following fields:
8
9- ``Complexity``: Describes the required familiarity with Rust and / or the
10  corresponding kernel APIs or subsystems. There are four different complexities,
11  ``Beginner``, ``Intermediate``, ``Advanced`` and ``Expert``.
12- ``Reference``: References to other tasks.
13- ``Link``: Links to external resources.
14- ``Contact``: The person that can be contacted for further information about
15  the task.
16
17Enablement (Rust)
18=================
19
20Tasks that are not directly related to nova-core, but are preconditions in terms
21of required APIs.
22
23FromPrimitive API
24-----------------
25
26Sometimes the need arises to convert a number to a value of an enum or a
27structure.
28
29A good example from nova-core would be the ``Chipset`` enum type, which defines
30the value ``AD102``. When probing the GPU the value ``0x192`` can be read from a
31certain register indication the chipset AD102. Hence, the enum value ``AD102``
32should be derived from the number ``0x192``. Currently, nova-core uses a custom
33implementation (``Chipset::from_u32`` for this.
34
35Instead, it would be desirable to have something like the ``FromPrimitive``
36trait [1] from the num crate.
37
38Having this generalization also helps with implementing a generic macro that
39automatically generates the corresponding mappings between a value and a number.
40
41| Complexity: Beginner
42| Link: https://docs.rs/num/latest/num/trait.FromPrimitive.html
43
44Generic register abstraction
45----------------------------
46
47Work out how register constants and structures can be automatically generated
48through generalized macros.
49
50Example:
51
52.. code-block:: rust
53
54	register!(BOOT0, 0x0, u32, pci::Bar<SIZE>, Fields [
55	   MINOR_REVISION(3:0, RO),
56	   MAJOR_REVISION(7:4, RO),
57	   REVISION(7:0, RO), // Virtual register combining major and minor rev.
58	])
59
60This could expand to something like:
61
62.. code-block:: rust
63
64	const BOOT0_OFFSET: usize = 0x00000000;
65	const BOOT0_MINOR_REVISION_SHIFT: u8 = 0;
66	const BOOT0_MINOR_REVISION_MASK: u32 = 0x0000000f;
67	const BOOT0_MAJOR_REVISION_SHIFT: u8 = 4;
68	const BOOT0_MAJOR_REVISION_MASK: u32 = 0x000000f0;
69	const BOOT0_REVISION_SHIFT: u8 = BOOT0_MINOR_REVISION_SHIFT;
70	const BOOT0_REVISION_MASK: u32 = BOOT0_MINOR_REVISION_MASK | BOOT0_MAJOR_REVISION_MASK;
71
72	struct Boot0(u32);
73
74	impl Boot0 {
75	   #[inline]
76	   fn read(bar: &RevocableGuard<'_, pci::Bar<SIZE>>) -> Self {
77	      Self(bar.readl(BOOT0_OFFSET))
78	   }
79
80	   #[inline]
81	   fn minor_revision(&self) -> u32 {
82	      (self.0 & BOOT0_MINOR_REVISION_MASK) >> BOOT0_MINOR_REVISION_SHIFT
83	   }
84
85	   #[inline]
86	   fn major_revision(&self) -> u32 {
87	      (self.0 & BOOT0_MAJOR_REVISION_MASK) >> BOOT0_MAJOR_REVISION_SHIFT
88	   }
89
90	   #[inline]
91	   fn revision(&self) -> u32 {
92	      (self.0 & BOOT0_REVISION_MASK) >> BOOT0_REVISION_SHIFT
93	   }
94	}
95
96Usage:
97
98.. code-block:: rust
99
100	let bar = bar.try_access().ok_or(ENXIO)?;
101
102	let boot0 = Boot0::read(&bar);
103	pr_info!("Revision: {}\n", boot0.revision());
104
105| Complexity: Advanced
106
107Delay / Sleep abstractions
108--------------------------
109
110Rust abstractions for the kernel's delay() and sleep() functions.
111
112FUJITA Tomonori plans to work on abstractions for read_poll_timeout_atomic()
113(and friends) [1].
114
115| Complexity: Beginner
116| Link: https://lore.kernel.org/netdev/20250228.080550.354359820929821928.fujita.tomonori@gmail.com/ [1]
117
118IRQ abstractions
119----------------
120
121Rust abstractions for IRQ handling.
122
123There is active ongoing work from Daniel Almeida [1] for the "core" abstractions
124to request IRQs.
125
126Besides optional review and testing work, the required ``pci::Device`` code
127around those core abstractions needs to be worked out.
128
129| Complexity: Intermediate
130| Link: https://lore.kernel.org/lkml/20250122163932.46697-1-daniel.almeida@collabora.com/ [1]
131| Contact: Daniel Almeida
132
133Page abstraction for foreign pages
134----------------------------------
135
136Rust abstractions for pages not created by the Rust page abstraction without
137direct ownership.
138
139There is active onging work from Abdiel Janulgue [1] and Lina [2].
140
141| Complexity: Advanced
142| Link: https://lore.kernel.org/linux-mm/20241119112408.779243-1-abdiel.janulgue@gmail.com/ [1]
143| Link: https://lore.kernel.org/rust-for-linux/20250202-rust-page-v1-0-e3170d7fe55e@asahilina.net/ [2]
144
145Scatterlist / sg_table abstractions
146-----------------------------------
147
148Rust abstractions for scatterlist / sg_table.
149
150There is preceding work from Abdiel Janulgue, which hasn't made it to the
151mailing list yet.
152
153| Complexity: Intermediate
154| Contact: Abdiel Janulgue
155
156ELF utils
157---------
158
159Rust implementation of ELF header representation to retrieve section header
160tables, names, and data from an ELF-formatted images.
161
162There is preceding work from Abdiel Janulgue, which hasn't made it to the
163mailing list yet.
164
165| Complexity: Beginner
166| Contact: Abdiel Janulgue
167
168PCI MISC APIs
169-------------
170
171Extend the existing PCI device / driver abstractions by SR-IOV, config space,
172capability, MSI API abstractions.
173
174| Complexity: Beginner
175
176Auxiliary bus abstractions
177--------------------------
178
179Rust abstraction for the auxiliary bus APIs.
180
181This is needed to connect nova-core to the nova-drm driver.
182
183| Complexity: Intermediate
184
185Debugfs abstractions
186--------------------
187
188Rust abstraction for debugfs APIs.
189
190| Reference: Export GSP log buffers
191| Complexity: Intermediate
192
193Vec extensions
194--------------
195
196Implement ``Vec::truncate`` and ``Vec::resize``.
197
198Currently this is used for some experimental code to parse the vBIOS.
199
200| Reference vBIOS support
201| Complexity: Beginner
202
203GPU (general)
204=============
205
206Parse firmware headers
207----------------------
208
209Parse ELF headers from the firmware files loaded from the filesystem.
210
211| Reference: ELF utils
212| Complexity: Beginner
213| Contact: Abdiel Janulgue
214
215Build radix3 page table
216-----------------------
217
218Build the radix3 page table to map the firmware.
219
220| Complexity: Intermediate
221| Contact: Abdiel Janulgue
222
223vBIOS support
224-------------
225
226Parse the vBIOS and probe the structures required for driver initialization.
227
228| Contact: Dave Airlie
229| Reference: Vec extensions
230| Complexity: Intermediate
231
232Initial Devinit support
233-----------------------
234
235Implement BIOS Device Initialization, i.e. memory sizing, waiting, PLL
236configuration.
237
238| Contact: Dave Airlie
239| Complexity: Beginner
240
241Boot Falcon controller
242----------------------
243
244Infrastructure to load and execute falcon (sec2) firmware images; handle the
245GSP falcon processor and fwsec loading.
246
247| Complexity: Advanced
248| Contact: Dave Airlie
249
250GPU Timer support
251-----------------
252
253Support for the GPU's internal timer peripheral.
254
255| Complexity: Beginner
256| Contact: Dave Airlie
257
258MMU / PT management
259-------------------
260
261Work out the architecture for MMU / page table management.
262
263We need to consider that nova-drm will need rather fine-grained control,
264especially in terms of locking, in order to be able to implement asynchronous
265Vulkan queues.
266
267While generally sharing the corresponding code is desirable, it needs to be
268evaluated how (and if at all) sharing the corresponding code is expedient.
269
270| Complexity: Expert
271
272VRAM memory allocator
273---------------------
274
275Investigate options for a VRAM memory allocator.
276
277Some possible options:
278  - Rust abstractions for
279    - RB tree (interval tree) / drm_mm
280    - maple_tree
281  - native Rust collections
282
283| Complexity: Advanced
284
285Instance Memory
286---------------
287
288Implement support for instmem (bar2) used to store page tables.
289
290| Complexity: Intermediate
291| Contact: Dave Airlie
292
293GPU System Processor (GSP)
294==========================
295
296Export GSP log buffers
297----------------------
298
299Recent patches from Timur Tabi [1] added support to expose GSP-RM log buffers
300(even after failure to probe the driver) through debugfs.
301
302This is also an interesting feature for nova-core, especially in the early days.
303
304| Link: https://lore.kernel.org/nouveau/20241030202952.694055-2-ttabi@nvidia.com/ [1]
305| Reference: Debugfs abstractions
306| Complexity: Intermediate
307
308GSP firmware abstraction
309------------------------
310
311The GSP-RM firmware API is unstable and may incompatibly change from version to
312version, in terms of data structures and semantics.
313
314This problem is one of the big motivations for using Rust for nova-core, since
315it turns out that Rust's procedural macro feature provides a rather elegant way
316to address this issue:
317
3181. generate Rust structures from the C headers in a separate namespace per version
3192. build abstraction structures (within a generic namespace) that implement the
320   firmware interfaces; annotate the differences in implementation with version
321   identifiers
3223. use a procedural macro to generate the actual per version implementation out
323   of this abstraction
3244. instantiate the correct version type one on runtime (can be sure that all
325   have the same interface because it's defined by a common trait)
326
327There is a PoC implementation of this pattern, in the context of the nova-core
328PoC driver.
329
330This task aims at refining the feature and ideally generalize it, to be usable
331by other drivers as well.
332
333| Complexity: Expert
334
335GSP message queue
336-----------------
337
338Implement low level GSP message queue (command, status) for communication
339between the kernel driver and GSP.
340
341| Complexity: Advanced
342| Contact: Dave Airlie
343
344Bootstrap GSP
345-------------
346
347Call the boot firmware to boot the GSP processor; execute initial control
348messages.
349
350| Complexity: Intermediate
351| Contact: Dave Airlie
352
353Client / Device APIs
354--------------------
355
356Implement the GSP message interface for client / device allocation and the
357corresponding client and device allocation APIs.
358
359| Complexity: Intermediate
360| Contact: Dave Airlie
361
362Bar PDE handling
363----------------
364
365Synchronize page table handling for BARs between the kernel driver and GSP.
366
367| Complexity: Beginner
368| Contact: Dave Airlie
369
370FIFO engine
371-----------
372
373Implement support for the FIFO engine, i.e. the corresponding GSP message
374interface and provide an API for chid allocation and channel handling.
375
376| Complexity: Advanced
377| Contact: Dave Airlie
378
379GR engine
380---------
381
382Implement support for the graphics engine, i.e. the corresponding GSP message
383interface and provide an API for (golden) context creation and promotion.
384
385| Complexity: Advanced
386| Contact: Dave Airlie
387
388CE engine
389---------
390
391Implement support for the copy engine, i.e. the corresponding GSP message
392interface.
393
394| Complexity: Intermediate
395| Contact: Dave Airlie
396
397VFN IRQ controller
398------------------
399
400Support for the VFN interrupt controller.
401
402| Complexity: Intermediate
403| Contact: Dave Airlie
404
405External APIs
406=============
407
408nova-core base API
409------------------
410
411Work out the common pieces of the API to connect 2nd level drivers, i.e. vGPU
412manager and nova-drm.
413
414| Complexity: Advanced
415
416vGPU manager API
417----------------
418
419Work out the API parts required by the vGPU manager, which are not covered by
420the base API.
421
422| Complexity: Advanced
423
424nova-core C API
425---------------
426
427Implement a C wrapper for the APIs required by the vGPU manager driver.
428
429| Complexity: Intermediate
430
431Testing
432=======
433
434CI pipeline
435-----------
436
437Investigate option for continuous integration testing.
438
439This can go from as simple as running KUnit tests over running (graphics) CTS to
440booting up (multiple) guest VMs to test VFIO use-cases.
441
442It might also be worth to consider the introduction of a new test suite directly
443sitting on top of the uAPI for more targeted testing and debugging. There may be
444options for collaboration / shared code with the Mesa project.
445
446| Complexity: Advanced
447