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 105Note: a work-in-progress implementation currently resides in 106`drivers/gpu/nova-core/regs/macros.rs` and is used in nova-core. It would be 107nice to improve it (possibly using proc macros) and move it to the `kernel` 108crate so it can be used by other components as well. 109 110| Complexity: Advanced 111| Contact: Alexandre Courbot 112 113Delay / Sleep abstractions 114-------------------------- 115 116Rust abstractions for the kernel's delay() and sleep() functions. 117 118FUJITA Tomonori plans to work on abstractions for read_poll_timeout_atomic() 119(and friends) [1]. 120 121| Complexity: Beginner 122| Link: https://lore.kernel.org/netdev/20250228.080550.354359820929821928.fujita.tomonori@gmail.com/ [1] 123 124IRQ abstractions 125---------------- 126 127Rust abstractions for IRQ handling. 128 129There is active ongoing work from Daniel Almeida [1] for the "core" abstractions 130to request IRQs. 131 132Besides optional review and testing work, the required ``pci::Device`` code 133around those core abstractions needs to be worked out. 134 135| Complexity: Intermediate 136| Link: https://lore.kernel.org/lkml/20250122163932.46697-1-daniel.almeida@collabora.com/ [1] 137| Contact: Daniel Almeida 138 139Page abstraction for foreign pages 140---------------------------------- 141 142Rust abstractions for pages not created by the Rust page abstraction without 143direct ownership. 144 145There is active onging work from Abdiel Janulgue [1] and Lina [2]. 146 147| Complexity: Advanced 148| Link: https://lore.kernel.org/linux-mm/20241119112408.779243-1-abdiel.janulgue@gmail.com/ [1] 149| Link: https://lore.kernel.org/rust-for-linux/20250202-rust-page-v1-0-e3170d7fe55e@asahilina.net/ [2] 150 151Scatterlist / sg_table abstractions 152----------------------------------- 153 154Rust abstractions for scatterlist / sg_table. 155 156There is preceding work from Abdiel Janulgue, which hasn't made it to the 157mailing list yet. 158 159| Complexity: Intermediate 160| Contact: Abdiel Janulgue 161 162ELF utils 163--------- 164 165Rust implementation of ELF header representation to retrieve section header 166tables, names, and data from an ELF-formatted images. 167 168There is preceding work from Abdiel Janulgue, which hasn't made it to the 169mailing list yet. 170 171| Complexity: Beginner 172| Contact: Abdiel Janulgue 173 174PCI MISC APIs 175------------- 176 177Extend the existing PCI device / driver abstractions by SR-IOV, config space, 178capability, MSI API abstractions. 179 180| Complexity: Beginner 181 182Auxiliary bus abstractions 183-------------------------- 184 185Rust abstraction for the auxiliary bus APIs. 186 187This is needed to connect nova-core to the nova-drm driver. 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 202Parse firmware headers 203---------------------- 204 205Parse ELF headers from the firmware files loaded from the filesystem. 206 207| Reference: ELF utils 208| Complexity: Beginner 209| Contact: Abdiel Janulgue 210 211Build radix3 page table 212----------------------- 213 214Build the radix3 page table to map the firmware. 215 216| Complexity: Intermediate 217| Contact: Abdiel Janulgue 218 219vBIOS support 220------------- 221 222Parse the vBIOS and probe the structures required for driver initialization. 223 224| Contact: Dave Airlie 225| Reference: Vec extensions 226| Complexity: Intermediate 227 228Initial Devinit support 229----------------------- 230 231Implement BIOS Device Initialization, i.e. memory sizing, waiting, PLL 232configuration. 233 234| Contact: Dave Airlie 235| Complexity: Beginner 236 237Boot Falcon controller 238---------------------- 239 240Infrastructure to load and execute falcon (sec2) firmware images; handle the 241GSP falcon processor and fwsec loading. 242 243| Complexity: Advanced 244| Contact: Dave Airlie 245 246GPU Timer support 247----------------- 248 249Support for the GPU's internal timer peripheral. 250 251| Complexity: Beginner 252| Contact: Dave Airlie 253 254MMU / PT management 255------------------- 256 257Work out the architecture for MMU / page table management. 258 259We need to consider that nova-drm will need rather fine-grained control, 260especially in terms of locking, in order to be able to implement asynchronous 261Vulkan queues. 262 263While generally sharing the corresponding code is desirable, it needs to be 264evaluated how (and if at all) sharing the corresponding code is expedient. 265 266| Complexity: Expert 267 268VRAM memory allocator 269--------------------- 270 271Investigate options for a VRAM memory allocator. 272 273Some possible options: 274 - Rust abstractions for 275 - RB tree (interval tree) / drm_mm 276 - maple_tree 277 - native Rust collections 278 279| Complexity: Advanced 280 281Instance Memory 282--------------- 283 284Implement support for instmem (bar2) used to store page tables. 285 286| Complexity: Intermediate 287| Contact: Dave Airlie 288 289GPU System Processor (GSP) 290========================== 291 292Export GSP log buffers 293---------------------- 294 295Recent patches from Timur Tabi [1] added support to expose GSP-RM log buffers 296(even after failure to probe the driver) through debugfs. 297 298This is also an interesting feature for nova-core, especially in the early days. 299 300| Link: https://lore.kernel.org/nouveau/20241030202952.694055-2-ttabi@nvidia.com/ [1] 301| Reference: Debugfs abstractions 302| Complexity: Intermediate 303 304GSP firmware abstraction 305------------------------ 306 307The GSP-RM firmware API is unstable and may incompatibly change from version to 308version, in terms of data structures and semantics. 309 310This problem is one of the big motivations for using Rust for nova-core, since 311it turns out that Rust's procedural macro feature provides a rather elegant way 312to address this issue: 313 3141. generate Rust structures from the C headers in a separate namespace per version 3152. build abstraction structures (within a generic namespace) that implement the 316 firmware interfaces; annotate the differences in implementation with version 317 identifiers 3183. use a procedural macro to generate the actual per version implementation out 319 of this abstraction 3204. instantiate the correct version type one on runtime (can be sure that all 321 have the same interface because it's defined by a common trait) 322 323There is a PoC implementation of this pattern, in the context of the nova-core 324PoC driver. 325 326This task aims at refining the feature and ideally generalize it, to be usable 327by other drivers as well. 328 329| Complexity: Expert 330 331GSP message queue 332----------------- 333 334Implement low level GSP message queue (command, status) for communication 335between the kernel driver and GSP. 336 337| Complexity: Advanced 338| Contact: Dave Airlie 339 340Bootstrap GSP 341------------- 342 343Call the boot firmware to boot the GSP processor; execute initial control 344messages. 345 346| Complexity: Intermediate 347| Contact: Dave Airlie 348 349Client / Device APIs 350-------------------- 351 352Implement the GSP message interface for client / device allocation and the 353corresponding client and device allocation APIs. 354 355| Complexity: Intermediate 356| Contact: Dave Airlie 357 358Bar PDE handling 359---------------- 360 361Synchronize page table handling for BARs between the kernel driver and GSP. 362 363| Complexity: Beginner 364| Contact: Dave Airlie 365 366FIFO engine 367----------- 368 369Implement support for the FIFO engine, i.e. the corresponding GSP message 370interface and provide an API for chid allocation and channel handling. 371 372| Complexity: Advanced 373| Contact: Dave Airlie 374 375GR engine 376--------- 377 378Implement support for the graphics engine, i.e. the corresponding GSP message 379interface and provide an API for (golden) context creation and promotion. 380 381| Complexity: Advanced 382| Contact: Dave Airlie 383 384CE engine 385--------- 386 387Implement support for the copy engine, i.e. the corresponding GSP message 388interface. 389 390| Complexity: Intermediate 391| Contact: Dave Airlie 392 393VFN IRQ controller 394------------------ 395 396Support for the VFN interrupt controller. 397 398| Complexity: Intermediate 399| Contact: Dave Airlie 400 401External APIs 402============= 403 404nova-core base API 405------------------ 406 407Work out the common pieces of the API to connect 2nd level drivers, i.e. vGPU 408manager and nova-drm. 409 410| Complexity: Advanced 411 412vGPU manager API 413---------------- 414 415Work out the API parts required by the vGPU manager, which are not covered by 416the base API. 417 418| Complexity: Advanced 419 420nova-core C API 421--------------- 422 423Implement a C wrapper for the APIs required by the vGPU manager driver. 424 425| Complexity: Intermediate 426 427Testing 428======= 429 430CI pipeline 431----------- 432 433Investigate option for continuous integration testing. 434 435This can go from as simple as running KUnit tests over running (graphics) CTS to 436booting up (multiple) guest VMs to test VFIO use-cases. 437 438It might also be worth to consider the introduction of a new test suite directly 439sitting on top of the uAPI for more targeted testing and debugging. There may be 440options for collaboration / shared code with the Mesa project. 441 442| Complexity: Advanced 443