WikiBot: Fix repository links: point to the cgit tree URLs

2026-10-12T04:40:58Z

Fix repository links: point to the cgit tree URLs

← Older revision		Revision as of 04:40, 12 October 2026
Line 3:		Line 3:
	= Install and First Run =		= Install and First Run =

	<blockquote>'''What this page is.''' From a fresh Ubuntu host with a supported NVIDIA GPU to a guest VM running a stock NVIDIA driver and <code>nvidia-smi</code>, in about half an hour. Condensed from the maintained guide [https://git.vgpu.io/open-iov/~~blob/master~~/docs/02-getting-started/01-install-and-first-run.md <code>../docs/02-getting-started/01-install-and-first-run.md</code>]; the docs tree wins on disagreement.</blockquote>		<blockquote>'''What this page is.''' From a fresh Ubuntu host with a supported NVIDIA GPU to a guest VM running a stock NVIDIA driver and <code>nvidia-smi</code>, in about half an hour. Condensed from the maintained guide [https://git.vgpu.io/open-iov.git/tree/docs/02-getting-started/01-install-and-first-run.md <code>../docs/02-getting-started/01-install-and-first-run.md</code>]; the docs tree wins on disagreement.</blockquote>

	Status: 2026-10-12, tree <code>master @ 2f066727</code>. Tags: <code>[live]</code> verified path; <code>[target]</code> roadmap item.		Status: 2026-10-12, tree <code>master @ 2f066727</code>. Tags: <code>[live]</code> verified path; <code>[target]</code> roadmap item.

WikiBot: Carry the site-wide About/licensing message on every page (2026-10-12)

2026-10-12T04:29:49Z

Carry the site-wide About/licensing message on every page (2026-10-12)

← Older revision		Revision as of 04:29, 12 October 2026
Line 1:		Line 1:
			{{About message}}

	= Install and First Run =		= Install and First Run =

WikiBot: Add page from tracked wiki source (2026 IA update)

2026-10-12T04:22:12Z

Add page from tracked wiki source (2026 IA update)

New page

= Install and First Run =

<blockquote>'''What this page is.''' From a fresh Ubuntu host with a supported NVIDIA GPU to a guest VM running a stock NVIDIA driver and <code>nvidia-smi</code>, in about half an hour. Condensed from the maintained guide [https://git.vgpu.io/open-iov/blob/master/docs/02-getting-started/01-install-and-first-run.md <code>../docs/02-getting-started/01-install-and-first-run.md</code>]; the docs tree wins on disagreement.</blockquote>

Status: 2026-10-12, tree <code>master @ 2f066727</code>. Tags: <code>[live]</code> verified path; <code>[target]</code> roadmap item.

== 1. Prerequisites ==

'''Host'''

* Ubuntu 22.04 or 24.04, x86_64 (aarch64 is a <code>[target]</code>);
* an NVIDIA GPU covered by the current emulation profile (Turing TU104 is the reference — see [[Hardware and Software Matrix|<code>Hardware-Software-Matrix.md</code>]]);
* a working '''host''' NVIDIA driver (<code>nvidia-smi</code> runs on the host; Open-IOV does not modify it);
* IOMMU enabled (<code>intel_iommu=on</code> / <code>amd_iommu=on</code>), hugepages configured, kernel headers for the running kernel;
* <code>qemu-system-x86_64</code> with KVM; libvirt optional;
* root (or sudo) for module load and mdev creation.

'''Guest'''

* Ubuntu 24.04 server (the reference guest), or any Linux with the matching stock NVIDIA driver available;
* '''no Open-IOV component at all''' — that is the point ([[System Overview|<code>System-Overview.md</code>]]).

== 2. Get the code and build ==

<pre>git clone https://git.vgpu.io/open-iov.git
cd open-iov
./install.sh deps # build/runtime dependencies
./install.sh nvidia # optional: NVIDIA OpenRM modules + build glue
./install.sh firmware # GSP firmware image (verified)
./install.sh build # kernel module + userspace</pre>

<code>install.sh</code> is safe to re-run. The manual equivalent, and the order that matters:

<pre>make kernel # first: generates Module.symvers
./scripts/build_nvidia_openrm.sh # optional (see below)
make userspace</pre>

'''Build order matters.''' NVIDIA's OpenRM modules resolve symbols that <code>vgsp.ko</code> exports; building them in the wrong order produces <code>Unknown symbol</code> failures at load time.

'''The OpenRM stage is optional.''' It is needed only for the native vGPU-management workflows in which NVIDIA's modules are built against the symbols <code>vgsp.ko</code> exports. The QEMU/emulated path uses the distribution driver that already manages the physical GPU; <code>load-stack</code> skips the OpenRM submodule when a distribution driver is present.

== 3. Load the stack and create a virtual GPU ==

<pre>./scripts/stack_manager.sh status # what is currently loaded
./scripts/stack_manager.sh load-stack # vfio/mdev prereqs -> vgsp.ko -> (optional) nvidia
./scripts/stack_manager.sh mdev-create # create a vGPU mediated device
./scripts/stack_manager.sh mdev-list # inspect /sys/bus/mdev/devices/</pre>

The mdev device ''is'' the virtual GPU; everything after this treats it like any other VFIO device.

== 4. Launch a reference guest ==

<pre>./scripts/stack_manager.sh qemu # reference raw-QEMU guest with the mdev</pre>

To integrate with your own stack (libvirt, Xen, ...), attach the mdev exactly as any VFIO device:

<pre><hostdev mode='subsystem' type='mdev' model='vfio-pci'>
<source>
<address uuid='<mdev-uuid>'/>
</source>
</hostdev></pre>

'''Attach behind a root port, not on the root bus.''' QEMU rewrites a device's PCIe capability when it detects a root-complex-integrated endpoint, which changes the link capabilities the guest driver sees. The reference script does this for you.

== 5. Install the stock driver in the guest ==

Inside the guest:

<pre>sudo apt update
sudo apt install -y linux-headers-generic build-essential
# The validated combination is the stock 570.144 Linux runfile (the same
# driver version as the emulation target).
sudo sh ./NVIDIA-Linux-x86_64-570.144.run
sudo reboot</pre>

Verify:

<pre>nvidia-smi # must list the virtual GPU
lsmod | grep -c nvidia</pre>

If <code>nvidia.ko</code> fails to probe, capture host dmesg, guest dmesg, guest <code>lspci -vvv</code> and the guest module parameters, and file an issue.

== 6. First CUDA check ==

<pre># in the guest
git clone https://github.com/NVIDIA/cuda-samples.git
cd cuda-samples/Samples/1_Utilities/deviceQuery && make && ./deviceQuery</pre>

'''Expectation today''' (<code>[live]</code> unless noted): driver probe, <code>nvidia-smi</code>, device enumeration and the full CUDA '''driver-API''' smoke complete end to end (<code>ALL OK</code>, 64-byte payload round-trips). CUDA '''kernel execution''' is the current frontier: a guest launch is forwarded and reaches the engine queue, but engine execution is not yet observed (<code>[wall]</code>) — see [[Project Status|<code>Project-Status.md</code>]] and [[The Execution Frontier|<code>Execution-Frontier.md</code>]] before drawing conclusions from a kernel that does not run.

== 7. Day-to-day operations ==

<pre>./scripts/stack_manager.sh up # build all + load + create mdev
./scripts/stack_manager.sh status # modules, mdev, vfio, firmware
./scripts/stack_manager.sh test # host test suite
./scripts/stack_manager.sh unload # correct-order teardown
./scripts/stack_manager.sh cleanup-crash</pre>

Load order is prerequisites → kernel module → (optional) NVIDIA OpenRM → firmware; unload is the reverse. Do not <code>rmmod</code> by hand while a VM holds the mdev.

== 8. Watching the emulation work ==

The module logs with the prefix '''<code>vgsp-<subsystem>:</code>''' (for example <code>vgsp-rpc:</code>, <code>vgsp-sema:</code>, <code>vgsp-work:</code>) plus per-RPC traces:

<pre>sudo dmesg -w | grep -i 'vgsp' # live
sudo dmesg -T | grep -i 'vgsp' | tail -50</pre>

Developer debug knobs (module parameters) are documented in the repository's debugging workflow document.

== 9. Troubleshooting index ==

{| class="wikitable"
|-
! Symptom
! Start here
|-
| Module will not load
| <code>dmesg</code>, <code>modinfo vgsp.ko</code>, stale module state → <code>cleanup-crash</code>
|-
| No mdev type for your GPU
| [[Hardware and Software Matrix|<code>Hardware-Software-Matrix.md</code>]]
|-
| Guest sees wrong PCIe link speed/width
| attach behind a root port (section 4)
|-
| <code>nvidia.ko</code> probe fails in guest
| guest dmesg + <code>lspci -vvv</code> + [[Guest Driver Lifecycle: A Field Guide|<code>Driver-Lifecycle-Field-Guide.md</code>]]
|-
| <code>nvidia-smi</code> works, a CUDA kernel does not run
| expected today — the execution frontier, not your setup ([[The Execution Frontier|<code>Execution-Frontier.md</code>]])
|-
| VM boot fails or the guest hangs
| <code>scripts/stack_manager.sh cleanup-crash</code>, then reboot
|}

== 10. Uninstall ==

<pre>./scripts/stack_manager.sh unload</pre>

The project never modifies your host driver's files; removing the module and its mdev devices returns the host to its previous state.

Install and First Run - Revision history

WikiBot: Fix repository links: point to the cgit tree URLs

WikiBot: Carry the site-wide About/licensing message on every page (2026-10-12)

WikiBot: Add page from tracked wiki source (2026 IA update)