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