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 17A task might have `[ABCD]` code after its name. This code can be used to grep 18into the code for `TODO` entries related to it. 19 20Enablement (Rust) 21================= 22 23Tasks that are not directly related to nova-core, but are preconditions in terms 24of required APIs. 25 26FromPrimitive API [FPRI] 27------------------------ 28 29Sometimes the need arises to convert a number to a value of an enum or a 30structure. 31 32A good example from nova-core would be the ``Chipset`` enum type, which defines 33the value ``AD102``. When probing the GPU the value ``0x192`` can be read from a 34certain register indication the chipset AD102. Hence, the enum value ``AD102`` 35should be derived from the number ``0x192``. Currently, nova-core uses a custom 36implementation (``Chipset::from_u32`` for this. 37 38Instead, it would be desirable to have something like the ``FromPrimitive`` 39trait [1] from the num crate. 40 41Having this generalization also helps with implementing a generic macro that 42automatically generates the corresponding mappings between a value and a number. 43 44| Complexity: Beginner 45| Link: https://docs.rs/num/latest/num/trait.FromPrimitive.html 46 47Generic register abstraction [REGA] 48----------------------------------- 49 50Work out how register constants and structures can be automatically generated 51through generalized macros. 52 53Example: 54 55.. code-block:: rust 56 57 register!(BOOT0, 0x0, u32, pci::Bar<SIZE>, Fields [ 58 MINOR_REVISION(3:0, RO), 59 MAJOR_REVISION(7:4, RO), 60 REVISION(7:0, RO), // Virtual register combining major and minor rev. 61 ]) 62 63This could expand to something like: 64 65.. code-block:: rust 66 67 const BOOT0_OFFSET: usize = 0x00000000; 68 const BOOT0_MINOR_REVISION_SHIFT: u8 = 0; 69 const BOOT0_MINOR_REVISION_MASK: u32 = 0x0000000f; 70 const BOOT0_MAJOR_REVISION_SHIFT: u8 = 4; 71 const BOOT0_MAJOR_REVISION_MASK: u32 = 0x000000f0; 72 const BOOT0_REVISION_SHIFT: u8 = BOOT0_MINOR_REVISION_SHIFT; 73 const BOOT0_REVISION_MASK: u32 = BOOT0_MINOR_REVISION_MASK | BOOT0_MAJOR_REVISION_MASK; 74 75 struct Boot0(u32); 76 77 impl Boot0 { 78 #[inline] 79 fn read(bar: &RevocableGuard<'_, pci::Bar<SIZE>>) -> Self { 80 Self(bar.readl(BOOT0_OFFSET)) 81 } 82 83 #[inline] 84 fn minor_revision(&self) -> u32 { 85 (self.0 & BOOT0_MINOR_REVISION_MASK) >> BOOT0_MINOR_REVISION_SHIFT 86 } 87 88 #[inline] 89 fn major_revision(&self) -> u32 { 90 (self.0 & BOOT0_MAJOR_REVISION_MASK) >> BOOT0_MAJOR_REVISION_SHIFT 91 } 92 93 #[inline] 94 fn revision(&self) -> u32 { 95 (self.0 & BOOT0_REVISION_MASK) >> BOOT0_REVISION_SHIFT 96 } 97 } 98 99Usage: 100 101.. code-block:: rust 102 103 let bar = bar.try_access().ok_or(ENXIO)?; 104 105 let boot0 = Boot0::read(&bar); 106 pr_info!("Revision: {}\n", boot0.revision()); 107 108A work-in-progress implementation currently resides in 109`drivers/gpu/nova-core/regs/macros.rs` and is used in nova-core. It would be 110nice to improve it (possibly using proc macros) and move it to the `kernel` 111crate so it can be used by other components as well. 112 113Features desired before this happens: 114 115* Make I/O optional I/O (for field values that are not registers), 116* Support other sizes than `u32`, 117* Allow visibility control for registers and individual fields, 118* Use Rust slice syntax to express fields ranges. 119 120| Complexity: Advanced 121| Contact: Alexandre Courbot 122 123Numerical operations [NUMM] 124--------------------------- 125 126Nova uses integer operations that are not part of the standard library (or not 127implemented in an optimized way for the kernel). These include: 128 129- The "Find Last Set Bit" (`fls` function of the C part of the kernel) 130 operation. 131 132A `num` core kernel module is being designed to provide these operations. 133 134| Complexity: Intermediate 135| Contact: Alexandre Courbot 136 137IRQ abstractions 138---------------- 139 140Rust abstractions for IRQ handling. 141 142There is active ongoing work from Daniel Almeida [1] for the "core" abstractions 143to request IRQs. 144 145Besides optional review and testing work, the required ``pci::Device`` code 146around those core abstractions needs to be worked out. 147 148| Complexity: Intermediate 149| Link: https://lore.kernel.org/lkml/20250122163932.46697-1-daniel.almeida@collabora.com/ [1] 150| Contact: Daniel Almeida 151 152Page abstraction for foreign pages 153---------------------------------- 154 155Rust abstractions for pages not created by the Rust page abstraction without 156direct ownership. 157 158There is active onging work from Abdiel Janulgue [1] and Lina [2]. 159 160| Complexity: Advanced 161| Link: https://lore.kernel.org/linux-mm/20241119112408.779243-1-abdiel.janulgue@gmail.com/ [1] 162| Link: https://lore.kernel.org/rust-for-linux/20250202-rust-page-v1-0-e3170d7fe55e@asahilina.net/ [2] 163 164Scatterlist / sg_table abstractions 165----------------------------------- 166 167Rust abstractions for scatterlist / sg_table. 168 169There is preceding work from Abdiel Janulgue, which hasn't made it to the 170mailing list yet. 171 172| Complexity: Intermediate 173| Contact: Abdiel Janulgue 174 175PCI MISC APIs 176------------- 177 178Extend the existing PCI device / driver abstractions by SR-IOV, config space, 179capability, MSI API abstractions. 180 181| Complexity: Beginner 182 183XArray bindings [XARR] 184---------------------- 185 186We need bindings for `xa_alloc`/`xa_alloc_cyclic` in order to generate the 187auxiliary device IDs. 188 189| Complexity: Intermediate 190 191Debugfs abstractions 192-------------------- 193 194Rust abstraction for debugfs APIs. 195 196| Reference: Export GSP log buffers 197| Complexity: Intermediate 198 199GPU (general) 200============= 201 202Initial Devinit support 203----------------------- 204 205Implement BIOS Device Initialization, i.e. memory sizing, waiting, PLL 206configuration. 207 208| Contact: Dave Airlie 209| Complexity: Beginner 210 211MMU / PT management 212------------------- 213 214Work out the architecture for MMU / page table management. 215 216We need to consider that nova-drm will need rather fine-grained control, 217especially in terms of locking, in order to be able to implement asynchronous 218Vulkan queues. 219 220While generally sharing the corresponding code is desirable, it needs to be 221evaluated how (and if at all) sharing the corresponding code is expedient. 222 223| Complexity: Expert 224 225VRAM memory allocator 226--------------------- 227 228Investigate options for a VRAM memory allocator. 229 230Some possible options: 231 - Rust abstractions for 232 - RB tree (interval tree) / drm_mm 233 - maple_tree 234 - native Rust collections 235 236| Complexity: Advanced 237 238Instance Memory 239--------------- 240 241Implement support for instmem (bar2) used to store page tables. 242 243| Complexity: Intermediate 244| Contact: Dave Airlie 245 246GPU System Processor (GSP) 247========================== 248 249Export GSP log buffers 250---------------------- 251 252Recent patches from Timur Tabi [1] added support to expose GSP-RM log buffers 253(even after failure to probe the driver) through debugfs. 254 255This is also an interesting feature for nova-core, especially in the early days. 256 257| Link: https://lore.kernel.org/nouveau/20241030202952.694055-2-ttabi@nvidia.com/ [1] 258| Reference: Debugfs abstractions 259| Complexity: Intermediate 260 261GSP firmware abstraction 262------------------------ 263 264The GSP-RM firmware API is unstable and may incompatibly change from version to 265version, in terms of data structures and semantics. 266 267This problem is one of the big motivations for using Rust for nova-core, since 268it turns out that Rust's procedural macro feature provides a rather elegant way 269to address this issue: 270 2711. generate Rust structures from the C headers in a separate namespace per version 2722. build abstraction structures (within a generic namespace) that implement the 273 firmware interfaces; annotate the differences in implementation with version 274 identifiers 2753. use a procedural macro to generate the actual per version implementation out 276 of this abstraction 2774. instantiate the correct version type one on runtime (can be sure that all 278 have the same interface because it's defined by a common trait) 279 280There is a PoC implementation of this pattern, in the context of the nova-core 281PoC driver. 282 283This task aims at refining the feature and ideally generalize it, to be usable 284by other drivers as well. 285 286| Complexity: Expert 287 288GSP message queue 289----------------- 290 291Implement low level GSP message queue (command, status) for communication 292between the kernel driver and GSP. 293 294| Complexity: Advanced 295| Contact: Dave Airlie 296 297Bootstrap GSP 298------------- 299 300Call the boot firmware to boot the GSP processor; execute initial control 301messages. 302 303| Complexity: Intermediate 304| Contact: Dave Airlie 305 306Client / Device APIs 307-------------------- 308 309Implement the GSP message interface for client / device allocation and the 310corresponding client and device allocation APIs. 311 312| Complexity: Intermediate 313| Contact: Dave Airlie 314 315Bar PDE handling 316---------------- 317 318Synchronize page table handling for BARs between the kernel driver and GSP. 319 320| Complexity: Beginner 321| Contact: Dave Airlie 322 323FIFO engine 324----------- 325 326Implement support for the FIFO engine, i.e. the corresponding GSP message 327interface and provide an API for chid allocation and channel handling. 328 329| Complexity: Advanced 330| Contact: Dave Airlie 331 332GR engine 333--------- 334 335Implement support for the graphics engine, i.e. the corresponding GSP message 336interface and provide an API for (golden) context creation and promotion. 337 338| Complexity: Advanced 339| Contact: Dave Airlie 340 341CE engine 342--------- 343 344Implement support for the copy engine, i.e. the corresponding GSP message 345interface. 346 347| Complexity: Intermediate 348| Contact: Dave Airlie 349 350VFN IRQ controller 351------------------ 352 353Support for the VFN interrupt controller. 354 355| Complexity: Intermediate 356| Contact: Dave Airlie 357 358External APIs 359============= 360 361nova-core base API 362------------------ 363 364Work out the common pieces of the API to connect 2nd level drivers, i.e. vGPU 365manager and nova-drm. 366 367| Complexity: Advanced 368 369vGPU manager API 370---------------- 371 372Work out the API parts required by the vGPU manager, which are not covered by 373the base API. 374 375| Complexity: Advanced 376 377nova-core C API 378--------------- 379 380Implement a C wrapper for the APIs required by the vGPU manager driver. 381 382| Complexity: Intermediate 383 384Testing 385======= 386 387CI pipeline 388----------- 389 390Investigate option for continuous integration testing. 391 392This can go from as simple as running KUnit tests over running (graphics) CTS to 393booting up (multiple) guest VMs to test VFIO use-cases. 394 395It might also be worth to consider the introduction of a new test suite directly 396sitting on top of the uAPI for more targeted testing and debugging. There may be 397options for collaboration / shared code with the Mesa project. 398 399| Complexity: Advanced 400