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