> ## Documentation Index
> Fetch the complete documentation index at: https://cordial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-046: NVIDIA behaviour is gated on the device's vendor id, and says what is inferred

**Status:** accepted
**Supersedes:** nothing
**Related:** [ADR-001](/adr/ADR-001-in-process-hooking), [ADR-011](/adr/ADR-011-wayland-and-libadwaita), [ADR-017](/adr/ADR-017-sober-issue-corpus), [ADR-024](/adr/ADR-024-x11-is-supported-again), [ADR-042](/adr/ADR-042-texture-format-query-observability)

## Decision

Anything Cordial does only because a GPU is NVIDIA's is gated on the physical
device's `VkPhysicalDeviceProperties.vendorID` being `0x10DE`, read in
`crates/cordial-runtime/src/android/vulkan.rs` and decided by
`crates/cordial-shell/src/nvidia.rs`. It is never gated on "an NVIDIA kernel
module is loaded": a hybrid laptop has the module loaded and often renders on
the other GPU, and a workaround applied there is applied to the wrong hardware.
The one place the module is read is where the question is about the module, the
Flatpak's matching userspace driver.

What is built on that gate:

* an identity line for the device the engine builds its logical device on,
  printed for every vendor, because every GPU report needs it and the launcher's
  crash page reads it to decide whether to mention NVIDIA at all;
* an **advisory**, not a refusal, for driver series 535 and 550;
* a bounded retry of `vkGetPhysicalDeviceSurfacePresentModesKHR` when it fails
  with `VK_ERROR_UNKNOWN`, `INITIALIZATION_FAILED` or `SURFACE_LOST` on an NVIDIA
  device;
* a `Graphics` row in `cordial --diagnostics` and, in a Flatpak, a sentence when
  the sandbox lacks the `GL.nvidia` extension the host driver needs;
* hints on the crash page;
* three lines in `cordial --doctor` (`doctor::nvidia_checks`): the driver series,
  the Flatpak extension against the host module, and `nvidia-drm` modeset, each
  run only for a Vulkan device whose vendor id is `0x10DE`.

`CORDIAL_FORCE_GPU_VENDOR` and `CORDIAL_TEST_FAIL_PRESENT_MODES` exist so that
path can be run on a machine without NVIDIA hardware. They change what Cordial
decides and never what the engine is told, are named in `cordial-run --help`,
and are set by no packaging script, which is the same shape as
`CORDIAL_MASK_MOBILE_TEXTURE_FORMATS` in ADR-042.

## What was decided not to do

* **No renderer, window-system or GPU switch on NVIDIA's behalf.** Defaulting
  NVIDIA-on-Wayland to X11 (mocktail's choice) loses the embedded web windows,
  which the X11 backend cannot attach, reverses the primary backend of ADR-011
  on one forum report and one comment, and is decided before the device is known.
  Defaulting 535 and 550 to OpenGL ES has the same timing problem and GLES is not
  known to be stable. Both are stated to the user with their cost instead.
* **`FStringGraphicsVulkanShaderMTDenyPattern` is not applied.** TASKS.md T2
  proposed it on the strength of mocktail shipping `"4318:.*"`. Reading mocktail
  for its reason found a workaround for its own libc bridge, which merely used
  NVIDIA's vendor id as a switch; nothing in Sober's tracker involves it. The
  rule in `flags.rs` (`BUILTIN`) applies unchanged: an inferred change belongs
  behind a switch somebody chooses, not in a default. It remains available in
  `flags.json`, and the tester plan measures it.
* **No patching of NVIDIA's library**, which Sober does for one VRAM problem
  (`patch_libnvidiaglcore_overzealous_vram_caching`). ADR-001 is unchanged.
* **No `__GL_*` variables.** They are documented for OpenGL only.
* **No minimum driver version in user documentation.** The evidence supports two
  series with reports and the fact that Pascal stops at 580, and nothing else.

## Why a message is acceptable where a fix is not

An advisory that names its evidence costs a user nothing when it is wrong and
saves an evening when it is right. A retry costs under two seconds on a path that
was ending in a fatal error already and does not run on success. Neither can make
a working install worse. A default switch of renderer or window system can, and
for everybody, on evidence this project cannot test.

## Consequences

* Every NVIDIA behaviour is `INFERRED` until somebody with the hardware runs the
  plan in [`docs/analysis/nvidia-support.md`](https://github.com/luohoa97/cordial/blob/main/docs/analysis/nvidia-support.md), and
  its comment says so. The claim "NVIDIA is supported" is not made anywhere;
  `docs/nvidia.md` opens by saying how little has been run on NVIDIA (two users'
  reports by 2026-10-04).
* The crash page can speak about NVIDIA only when the client's own output shows an
  NVIDIA device, so an unrelated crash on an Intel machine never mentions it.
* If a run on real hardware shows the retry does nothing, delete it, and this ADR
  is amended rather than left describing a behaviour that is not there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.