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