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