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- The "Find Last Set Bit" (`fls` function of the C part of the kernel) 149 operation. 150 151A `num` core kernel module is being designed to provide these operations. 152 153| Complexity: Intermediate 154| Contact: Alexandre Courbot 155 156IRQ abstractions 157---------------- 158 159Rust abstractions for IRQ handling. 160 161There is active ongoing work from Daniel Almeida [1] for the "core" abstractions 162to request IRQs. 163 164Besides optional review and testing work, the required ``pci::Device`` code 165around those core abstractions needs to be worked out. 166 167| Complexity: Intermediate 168| Link: https://lore.kernel.org/lkml/20250122163932.46697-1-daniel.almeida@collabora.com/ [1] 169| Contact: Daniel Almeida 170 171Page abstraction for foreign pages 172---------------------------------- 173 174Rust abstractions for pages not created by the Rust page abstraction without 175direct ownership. 176 177There is active onging work from Abdiel Janulgue [1] and Lina [2]. 178 179| Complexity: Advanced 180| Link: https://lore.kernel.org/linux-mm/20241119112408.779243-1-abdiel.janulgue@gmail.com/ [1] 181| Link: https://lore.kernel.org/rust-for-linux/20250202-rust-page-v1-0-e3170d7fe55e@asahilina.net/ [2] 182 183Scatterlist / sg_table abstractions 184----------------------------------- 185 186Rust abstractions for scatterlist / sg_table. 187 188There is preceding work from Abdiel Janulgue, which hasn't made it to the 189mailing list yet. 190 191| Complexity: Intermediate 192| Contact: Abdiel Janulgue 193 194PCI MISC APIs 195------------- 196 197Extend the existing PCI device / driver abstractions by SR-IOV, config space, 198capability, MSI API abstractions. 199 200| Complexity: Beginner 201 202XArray bindings [XARR] 203---------------------- 204 205We need bindings for `xa_alloc`/`xa_alloc_cyclic` in order to generate the 206auxiliary device IDs. 207 208| Complexity: Intermediate 209 210Debugfs abstractions 211-------------------- 212 213Rust abstraction for debugfs APIs. 214 215| Reference: Export GSP log buffers 216| Complexity: Intermediate 217 218GPU (general) 219============= 220 221Initial Devinit support 222----------------------- 223 224Implement BIOS Device Initialization, i.e. memory sizing, waiting, PLL 225configuration. 226 227| Contact: Dave Airlie 228| Complexity: Beginner 229 230MMU / PT management 231------------------- 232 233Work out the architecture for MMU / page table management. 234 235We need to consider that nova-drm will need rather fine-grained control, 236especially in terms of locking, in order to be able to implement asynchronous 237Vulkan queues. 238 239While generally sharing the corresponding code is desirable, it needs to be 240evaluated how (and if at all) sharing the corresponding code is expedient. 241 242| Complexity: Expert 243 244VRAM memory allocator 245--------------------- 246 247Investigate options for a VRAM memory allocator. 248 249Some possible options: 250 - Rust abstractions for 251 - RB tree (interval tree) / drm_mm 252 - maple_tree 253 - native Rust collections 254 255| Complexity: Advanced 256 257Instance Memory 258--------------- 259 260Implement support for instmem (bar2) used to store page tables. 261 262| Complexity: Intermediate 263| Contact: Dave Airlie 264 265GPU System Processor (GSP) 266========================== 267 268Export GSP log buffers 269---------------------- 270 271Recent patches from Timur Tabi [1] added support to expose GSP-RM log buffers 272(even after failure to probe the driver) through debugfs. 273 274This is also an interesting feature for nova-core, especially in the early days. 275 276| Link: https://lore.kernel.org/nouveau/20241030202952.694055-2-ttabi@nvidia.com/ [1] 277| Reference: Debugfs abstractions 278| Complexity: Intermediate 279 280GSP firmware abstraction 281------------------------ 282 283The GSP-RM firmware API is unstable and may incompatibly change from version to 284version, in terms of data structures and semantics. 285 286This problem is one of the big motivations for using Rust for nova-core, since 287it turns out that Rust's procedural macro feature provides a rather elegant way 288to address this issue: 289 2901. generate Rust structures from the C headers in a separate namespace per version 2912. build abstraction structures (within a generic namespace) that implement the 292 firmware interfaces; annotate the differences in implementation with version 293 identifiers 2943. use a procedural macro to generate the actual per version implementation out 295 of this abstraction 2964. instantiate the correct version type one on runtime (can be sure that all 297 have the same interface because it's defined by a common trait) 298 299There is a PoC implementation of this pattern, in the context of the nova-core 300PoC driver. 301 302This task aims at refining the feature and ideally generalize it, to be usable 303by other drivers as well. 304 305| Complexity: Expert 306 307GSP message queue 308----------------- 309 310Implement low level GSP message queue (command, status) for communication 311between the kernel driver and GSP. 312 313| Complexity: Advanced 314| Contact: Dave Airlie 315 316Bootstrap GSP 317------------- 318 319Call the boot firmware to boot the GSP processor; execute initial control 320messages. 321 322| Complexity: Intermediate 323| Contact: Dave Airlie 324 325Client / Device APIs 326-------------------- 327 328Implement the GSP message interface for client / device allocation and the 329corresponding client and device allocation APIs. 330 331| Complexity: Intermediate 332| Contact: Dave Airlie 333 334Bar PDE handling 335---------------- 336 337Synchronize page table handling for BARs between the kernel driver and GSP. 338 339| Complexity: Beginner 340| Contact: Dave Airlie 341 342FIFO engine 343----------- 344 345Implement support for the FIFO engine, i.e. the corresponding GSP message 346interface and provide an API for chid allocation and channel handling. 347 348| Complexity: Advanced 349| Contact: Dave Airlie 350 351GR engine 352--------- 353 354Implement support for the graphics engine, i.e. the corresponding GSP message 355interface and provide an API for (golden) context creation and promotion. 356 357| Complexity: Advanced 358| Contact: Dave Airlie 359 360CE engine 361--------- 362 363Implement support for the copy engine, i.e. the corresponding GSP message 364interface. 365 366| Complexity: Intermediate 367| Contact: Dave Airlie 368 369VFN IRQ controller 370------------------ 371 372Support for the VFN interrupt controller. 373 374| Complexity: Intermediate 375| Contact: Dave Airlie 376 377External APIs 378============= 379 380nova-core base API 381------------------ 382 383Work out the common pieces of the API to connect 2nd level drivers, i.e. vGPU 384manager and nova-drm. 385 386| Complexity: Advanced 387 388vGPU manager API 389---------------- 390 391Work out the API parts required by the vGPU manager, which are not covered by 392the base API. 393 394| Complexity: Advanced 395 396nova-core C API 397--------------- 398 399Implement a C wrapper for the APIs required by the vGPU manager driver. 400 401| Complexity: Intermediate 402 403Testing 404======= 405 406CI pipeline 407----------- 408 409Investigate option for continuous integration testing. 410 411This can go from as simple as running KUnit tests over running (graphics) CTS to 412booting up (multiple) guest VMs to test VFIO use-cases. 413 414It might also be worth to consider the introduction of a new test suite directly 415sitting on top of the uAPI for more targeted testing and debugging. There may be 416options for collaboration / shared code with the Mesa project. 417 418| Complexity: Advanced 419