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 193GPU (general) 194============= 195 196Parse firmware headers 197---------------------- 198 199Parse ELF headers from the firmware files loaded from the filesystem. 200 201| Reference: ELF utils 202| Complexity: Beginner 203| Contact: Abdiel Janulgue 204 205Build radix3 page table 206----------------------- 207 208Build the radix3 page table to map the firmware. 209 210| Complexity: Intermediate 211| Contact: Abdiel Janulgue 212 213vBIOS support 214------------- 215 216Parse the vBIOS and probe the structures required for driver initialization. 217 218| Contact: Dave Airlie 219| Reference: Vec extensions 220| Complexity: Intermediate 221 222Initial Devinit support 223----------------------- 224 225Implement BIOS Device Initialization, i.e. memory sizing, waiting, PLL 226configuration. 227 228| Contact: Dave Airlie 229| Complexity: Beginner 230 231Boot Falcon controller 232---------------------- 233 234Infrastructure to load and execute falcon (sec2) firmware images; handle the 235GSP falcon processor and fwsec loading. 236 237| Complexity: Advanced 238| Contact: Dave Airlie 239 240GPU Timer support 241----------------- 242 243Support for the GPU's internal timer peripheral. 244 245| Complexity: Beginner 246| Contact: Dave Airlie 247 248MMU / PT management 249------------------- 250 251Work out the architecture for MMU / page table management. 252 253We need to consider that nova-drm will need rather fine-grained control, 254especially in terms of locking, in order to be able to implement asynchronous 255Vulkan queues. 256 257While generally sharing the corresponding code is desirable, it needs to be 258evaluated how (and if at all) sharing the corresponding code is expedient. 259 260| Complexity: Expert 261 262VRAM memory allocator 263--------------------- 264 265Investigate options for a VRAM memory allocator. 266 267Some possible options: 268 - Rust abstractions for 269 - RB tree (interval tree) / drm_mm 270 - maple_tree 271 - native Rust collections 272 273| Complexity: Advanced 274 275Instance Memory 276--------------- 277 278Implement support for instmem (bar2) used to store page tables. 279 280| Complexity: Intermediate 281| Contact: Dave Airlie 282 283GPU System Processor (GSP) 284========================== 285 286Export GSP log buffers 287---------------------- 288 289Recent patches from Timur Tabi [1] added support to expose GSP-RM log buffers 290(even after failure to probe the driver) through debugfs. 291 292This is also an interesting feature for nova-core, especially in the early days. 293 294| Link: https://lore.kernel.org/nouveau/20241030202952.694055-2-ttabi@nvidia.com/ [1] 295| Reference: Debugfs abstractions 296| Complexity: Intermediate 297 298GSP firmware abstraction 299------------------------ 300 301The GSP-RM firmware API is unstable and may incompatibly change from version to 302version, in terms of data structures and semantics. 303 304This problem is one of the big motivations for using Rust for nova-core, since 305it turns out that Rust's procedural macro feature provides a rather elegant way 306to address this issue: 307 3081. generate Rust structures from the C headers in a separate namespace per version 3092. build abstraction structures (within a generic namespace) that implement the 310 firmware interfaces; annotate the differences in implementation with version 311 identifiers 3123. use a procedural macro to generate the actual per version implementation out 313 of this abstraction 3144. instantiate the correct version type one on runtime (can be sure that all 315 have the same interface because it's defined by a common trait) 316 317There is a PoC implementation of this pattern, in the context of the nova-core 318PoC driver. 319 320This task aims at refining the feature and ideally generalize it, to be usable 321by other drivers as well. 322 323| Complexity: Expert 324 325GSP message queue 326----------------- 327 328Implement low level GSP message queue (command, status) for communication 329between the kernel driver and GSP. 330 331| Complexity: Advanced 332| Contact: Dave Airlie 333 334Bootstrap GSP 335------------- 336 337Call the boot firmware to boot the GSP processor; execute initial control 338messages. 339 340| Complexity: Intermediate 341| Contact: Dave Airlie 342 343Client / Device APIs 344-------------------- 345 346Implement the GSP message interface for client / device allocation and the 347corresponding client and device allocation APIs. 348 349| Complexity: Intermediate 350| Contact: Dave Airlie 351 352Bar PDE handling 353---------------- 354 355Synchronize page table handling for BARs between the kernel driver and GSP. 356 357| Complexity: Beginner 358| Contact: Dave Airlie 359 360FIFO engine 361----------- 362 363Implement support for the FIFO engine, i.e. the corresponding GSP message 364interface and provide an API for chid allocation and channel handling. 365 366| Complexity: Advanced 367| Contact: Dave Airlie 368 369GR engine 370--------- 371 372Implement support for the graphics engine, i.e. the corresponding GSP message 373interface and provide an API for (golden) context creation and promotion. 374 375| Complexity: Advanced 376| Contact: Dave Airlie 377 378CE engine 379--------- 380 381Implement support for the copy engine, i.e. the corresponding GSP message 382interface. 383 384| Complexity: Intermediate 385| Contact: Dave Airlie 386 387VFN IRQ controller 388------------------ 389 390Support for the VFN interrupt controller. 391 392| Complexity: Intermediate 393| Contact: Dave Airlie 394 395External APIs 396============= 397 398nova-core base API 399------------------ 400 401Work out the common pieces of the API to connect 2nd level drivers, i.e. vGPU 402manager and nova-drm. 403 404| Complexity: Advanced 405 406vGPU manager API 407---------------- 408 409Work out the API parts required by the vGPU manager, which are not covered by 410the base API. 411 412| Complexity: Advanced 413 414nova-core C API 415--------------- 416 417Implement a C wrapper for the APIs required by the vGPU manager driver. 418 419| Complexity: Intermediate 420 421Testing 422======= 423 424CI pipeline 425----------- 426 427Investigate option for continuous integration testing. 428 429This can go from as simple as running KUnit tests over running (graphics) CTS to 430booting up (multiple) guest VMs to test VFIO use-cases. 431 432It might also be worth to consider the introduction of a new test suite directly 433sitting on top of the uAPI for more targeted testing and debugging. There may be 434options for collaboration / shared code with the Mesa project. 435 436| Complexity: Advanced 437