Merge pull request #45 from dasteihn/nova-docu-update

Nova docu update

Author: ojeda

src/Nova-GPU-Driver.md

@@ -1,62 +1,107 @@
 # Nova GPU Driver
 
-Nova is a driver for GSP-based Nvidia GPUs that is currently under development
-and is being written in Rust.
+Nova is a driver for GSP (GPU system processor) based Nvidia GPUs. It is
+intended to become the successor of Nouveau as the mainline driver for Nvidia
+(GSP) GPUs in Linux.
 
-Currently, the objective is to upstream Rust abstractions for the relevant
-subsystems a prerequisite for the actual driver. Hence, the first mainline
-version of Nova will be a stub driver which helps establishing the necessary
-infrastructure in other subsystems (notably PCI and DRM).
+It will support all Nvidia GPUs beginning with the GeForce RTX20 (Turing family)
+series and newer.
 
 ## Contact
 
-To contact the team and / or participate in development, please use the mailing
-list: nouveau@lists.freedesktop.org
+Available communication channels are:
+
+- The mailing list: nouveau@lists.freedesktop.org
+- IRC: #nouveau on OFTC
+- [Zulip Chat](https://rust-for-linux.zulipchat.com/#narrow/channel/509436-Nova)
 
 
 ## Resources
 
-- [Official Source Tree](https://gitlab.freedesktop.org/drm/nova)
-- [Announcement E-Mail](https://lore.kernel.org/dri-devel/Zfsj0_tb-0-tNrJy@cassiopeiae/)
+The parts that are already in mainline Linux can be found in
+`drivers/gpu/nova-core/` and `drivers/gpu/drm/nova/`
+
+The development repository for the in-tree driver is located on
+[Freedesktop](https://gitlab.freedesktop.org/drm/nova).
+
+
+## Background
+
+### Why a new driver?
+
+Nouveau was, for the most part, designed for pre-GSP hardware. The driver exists
+since ~2009 and its authors back in the day had to reverse engineer a lot about
+the hardware's internals, resulting in a relatively difficult to maintain
+codebase.
+
+Moreover, Nouveau's maintainers concluded that a new driver, exclusively for
+GSP hardware, would allow for significantly simplifying the driver design: Most
+of the hardware internals that Nouveau had to reverse engineer reside in the
+GSP firmware. Hereby, the GSP takes up the role of a hardware abstraction layer
+which communicates with the host kernel through IPC. Thereby, a lot of the
+stack's complexity is moved from the GPU driver into the GSP firmware.
+
+This, in consequence, enables better maintainability. Another chance with a new
+driver is to obtain active community participation from the very beginning.
+
+
+### Why write it in Rust?
 
-In the source tree, the driver lives in `drivers/gpu/drm/nova`.
+Besides Rust's built-in ownership and lifetime model, its powerful type system
+allows us to avoid a large portion of a whole class of bugs (i.e. memory safety
+bugs).
 
+Additionally, the same features allow us to model APIs in a way that also
+certain logic errors can be caught at compile time already.
 
-## Status
+Especially GPU drivers can benefit a lot from Rust's ownership and lifetime
+model, given their highly concurrent and asynchronous design.
 
-Currently, Nova is just a stub driver intended to lift the bindings necessary
-for a real GPU driver into the (mainline) kernel.
+Since Nova is a new driver, written from scratch, it is an opportunity to try to
+leverage the advantages of Rust and obtain a more reliable, maintainable driver.
 
-Currently, those efforts are mostly focused on getting bindings for PCI, DRM
-and the Device (driver) model upstream.
 
-It can be expected that, as the driver continues to grow, various other abstractions
-will be needed.
+## Architecture
 
+![Nova Architecture with vGPUs](./nova-core-vm.png)
 
-## Utilized Common Rust Infrastructure
+The overall GPU driver is split into two parts:
 
-Nova depends on the Rust for Linux `staging/*` [branches](Branches.md).
+1. "Nova-Core", living in `drivers/gpu/nova-core/`. Nova-Core implements
+   the fundamental interaction with the hardware (through PCI etc.) and,
+   notably, boots up the GSP and interacts with it through a command queue.
+2. "Nova-DRM" (the official name is actually just "Nova", but to avoid
+   confusion developers usually call it "Nova-DRM"), living in
+   `drivers/gpu/drm/nova/`. This is the actual graphics driver,
+   implementing all the typical DRM interfaces for userspace.
 
+This split architecture allows for different drivers building on top of the
+abstraction layer provided by Nova-Core. Besides Nova-DRM, for instance, a VFIO
+driver to virtualize the GPU can be built on top of Nova-Core. Through this
+driver Nova-Core can be used to instruct the GPU's firmware to spawn new PCI
+virtual functions (through
+[SR-IOV](https://docs.kernel.org/PCI/pci-iov-howto.html)), representing virtual
+GPUs. Those virtual functions (or vGPUs) can be used by virtual machines. Such
+a virtual machine running Linux may run Nova-Core and Nova-DRM as conventional
+GPU drivers on top of this vGPU.
 
-## Contributing
+A main advantage of this design is that the amount of software running on the
+host (where crashes would be far more fatal than inside of a VM) is kept small,
+which contributes to stability.
 
-As with every real open source program, help and participation is highly welcome!
+It is also possible to use Nova-Core + Nova-DRM on one physical machine (not
+depicted in the diagram) in order to expose a DRM compatible uAPI to the host
+userspace.
 
-As the driver is very young, however, it is currently difficult to assign tasks
-to people. Many things still have to settle until a steadily paced workflow
-produces atomic work topics a new one can work on.
+For more details about vGPUs, take a look at
+[Zhi's announcement email](https://lore.kernel.org/nouveau/20240922124951.1946072-1-zhiw@nvidia.com/).
 
-If you really want to jump in immediately regardless, here are a few things you
-can consider:
 
-- Most work to do right now is with more bindings for Rust. Notably, this
-  includes the device driver model, DRM and PCI. If you have expertise there,
-  have a look at the existing code in the [topic branches](Branches.md) and see
-  if there's something you can add or improve.
-- Feel free to go over Nova's code base and make suggestions or send patches,
-  for example for improved comments, grammar fixes, improving code readability
-  etc.
+## Status and Contributing
 
+The necessary Rust infrastructure has been progressing a lot. Current work now
+focuses more on the actual driver. In case you want to contribute, take a look
+at the
+[NOVA TODO List](https://docs.kernel.org/gpu/nova/core/todo.html).
 
-Happy hacking!
+Don't hesitate reaching out on the aforementioned community channels.