From 7ec4a50dd1920c6942061b44f05f5dfdad6f8a12 Mon Sep 17 00:00:00 2001
From: William Phetsinorath <william.phetsinorath@shikanime.studio>
Date: Sun, 10 Nov 2024 20:26:59 +0000
Subject: [PATCH] Add NVIDIA acceleration how-to documentation

---
 docs/src/how-to/docker-nvidia-device.md       | 32 +++++++++++++
 docs/src/how-to/nix-ld-nvidia-acceleration.md | 45 +++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 docs/src/how-to/docker-nvidia-device.md
 create mode 100644 docs/src/how-to/nix-ld-nvidia-acceleration.md

diff --git a/docs/src/how-to/docker-nvidia-device.md b/docs/src/how-to/docker-nvidia-device.md
new file mode 100644
index 00000000..aa6248af
--- /dev/null
+++ b/docs/src/how-to/docker-nvidia-device.md
@@ -0,0 +1,32 @@
+# How to use NVIDIA GPU in Docker
+
+WSL supports NVIDIA-based GPU acceleration, making it ideal for many use cases
+including machine learning or general compute acceleration. Since Docker version
+25, the use of `virtualisation.docker.enableNvidia` has been deprecated in
+favour of a more standard specification called Container Device Interface.
+
+1. Enable the NVIDIA Container Toolkit and disable the mounting of executables,
+   as this will cause an problem related to missing libraries.
+
+```nix
+hardware.nvidia-container-toolkit = {
+  enable = true;
+  mount-nvidia-executables = false;
+};
+```
+
+2. As of Docker 25, the Docker daemon doesn't have the CDI feature enabled by
+   default.
+
+```nix
+virtualisation.docker = {
+  enable = true;
+  daemon.settings.features.cdi = true;
+};
+```
+
+3. Test the installation by running the following command.
+
+```shell
+docker run --rm --device nvidia.com/gpu=all ubuntu nvidia-smi -L
+```
diff --git a/docs/src/how-to/nix-ld-nvidia-acceleration.md b/docs/src/how-to/nix-ld-nvidia-acceleration.md
new file mode 100644
index 00000000..becd1f02
--- /dev/null
+++ b/docs/src/how-to/nix-ld-nvidia-acceleration.md
@@ -0,0 +1,45 @@
+# How to use NVIDIA acceleration with nix-ld
+
+By default, the NixOS WSL configuration provides a symlink farm from
+/usr/lib/wsl/lib to the OpenGL packages. However, if you want to use the GPU
+with a non-NixOS compiled program via nix-ld (e.g. nvidia-smi), you also need to
+add the symlinks to the to the nix-ld libraries.
+
+```nix
+let
+  wsl-lib = pkgs.runCommand "wsl-lib" { } ''
+    mkdir -p "$out/lib"
+    # # We can't just symlink the lib directory, because it will break merging with other drivers that provide the same directory
+    ln -s /usr/lib/wsl/lib/libcudadebugger.so.1 "$out/lib"
+    ln -s /usr/lib/wsl/lib/libcuda.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libcuda.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libcuda.so.1.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libd3d12core.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libd3d12.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libdxcore.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvcuvid.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvcuvid.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvdxdlkernels.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvidia-encode.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvidia-encode.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvidia-ml.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvidia-opticalflow.so "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvidia-opticalflow.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvoptix.so.1 "$out/lib
+    ln -s /usr/lib/wsl/lib/libnvwgf2umx.so "$out/lib
+    ln -s /usr/lib/wsl/lib/nvidia-smi "$out/lib
+  '';
+in
+{
+  programs.nix-ld = {
+    enable = true;
+    libraries = [ wsl-lib ];
+  };
+}
+```
+
+Test the installation by running the following command:
+
+```shell
+nvidia-smi
+```