linux-toradex.git/Documentation/gpu/nova, branch master Linux kernel for Apalis and Colibri modules gpu: nova-core: document the GIN interrupt controller and GSP events 2026-10-02T12:57:05+00:00 John Hubbard jhubbard@nvidia.com 2026-09-30T03:41:48+00:00 df718311a84188e26d499301c3921e4c392d557e The interrupt code rests on hardware behavior that the code cannot show on its own: how GIN, the GPU's interrupt controller, records and delivers interrupts, what edge-triggered delivery requires of a handler, and how the GSP signals the CPU. Some of those requirements come from OpenRM rather than from the hardware manuals. Add a design document that records that behavior, the rules that nova-core follows because of it, and the terms that the code uses for it. The code comments cite the document by section rather than repeating it. Assisted-by: LLM Signed-off-by: John Hubbard <jhubbard@nvidia.com> Acked-by: Danilo Krummrich <dakr@kernel.org> Link: https://patch.msgid.link/20260930034148.590687-16-jhubbard@nvidia.com [acourbot: cut the last 3 sections.] Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
The interrupt code rests on hardware behavior that the code cannot show
on its own: how GIN, the GPU's interrupt controller, records and
delivers interrupts, what edge-triggered delivery requires of a handler,
and how the GSP signals the CPU. Some of those requirements come from
OpenRM rather than from the hardware manuals.

Add a design document that records that behavior, the rules that
nova-core follows because of it, and the terms that the code uses for
it. The code comments cite the document by section rather than repeating
it.

Assisted-by: LLM
Signed-off-by: John Hubbard <jhubbard@nvidia.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://patch.msgid.link/20260930034148.590687-16-jhubbard@nvidia.com
[acourbot: cut the last 3 sections.]
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
gpu: nova-core: set MCTP transport header version to 1 2026-09-22T13:07:43+00:00 John Hubbard jhubbard@nvidia.com 2026-09-18T01:06:48+00:00 6f0bdccfff6c84bd33f0385517c6f1f331a5ea04 FSP, the GPU's Foundation Security Processor, receives the driver's messages as packets of MCTP, the Management Component Transport Protocol. It requires header version 1 in bits 3:0 of the MCTP transport header. Nova-core left those bits at zero, so every Chain of Trust request and every Product Reconfiguration Control request that it sent carried an invalid transport header. Declare the version field and set it. Declare the destination endpoint ID field as well. The driver leaves that field at zero. Assisted-by: LLM Signed-off-by: John Hubbard <jhubbard@nvidia.com> Reviewed-by: Timur Tabi <ttabi@nvidia.com> Reviewed-by: Zhi Wang <zhiw@nvidia.com> Link: https://patch.msgid.link/20260918010719.1176945-3-jhubbard@nvidia.com [acourbot: explicitly set deid field] Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
FSP, the GPU's Foundation Security Processor, receives the driver's
messages as packets of MCTP, the Management Component Transport
Protocol. It requires header version 1 in bits 3:0 of the MCTP transport
header.

Nova-core left those bits at zero, so every Chain of Trust request and
every Product Reconfiguration Control request that it sent carried an
invalid transport header.

Declare the version field and set it. Declare the destination endpoint
ID field as well. The driver leaves that field at zero.

Assisted-by: LLM
Signed-off-by: John Hubbard <jhubbard@nvidia.com>
Reviewed-by: Timur Tabi <ttabi@nvidia.com>
Reviewed-by: Zhi Wang <zhiw@nvidia.com>
Link: https://patch.msgid.link/20260918010719.1176945-3-jhubbard@nvidia.com
[acourbot: explicitly set deid field]
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
Documentation: nova: Fix bracket 2026-09-13T01:39:59+00:00 Manuel Ebner manuelebnerli@mailbox.org 2026-09-09T13:53:19+00:00 66a2c223b620d844fe26c6bd4844d2a6a8c9dffc Add missing ')'. Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://patch.msgid.link/20260909135319.1364776-3-manuelebnerli@mailbox.org [acourbot: add missing `:` in commit title] Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
Add missing ')'.

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://patch.msgid.link/20260909135319.1364776-3-manuelebnerli@mailbox.org
[acourbot: add missing `:` in commit title]
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
docs: gpu: nova-core: Document the PRAMIN aperture mechanism 2026-09-07T02:55:43+00:00 Joel Fernandes joelagnelf@nvidia.com 2026-08-27T08:51:48+00:00 b4481b9e3b5a3e1b45b5a70880cc2b730bc3700a Add documentation for the PRAMIN aperture mechanism used by nova-core for direct VRAM access. Nova only uses TARGET=VRAM for VRAM access. The SYS_MEM target values are documented for completeness but not used by the driver. Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com> [ecourtney: fix the TARGET encodings, KiB/MiB units, wording nits] [ecourtney: wrap at 80 columns] Signed-off-by: Eliot Courtney <ecourtney@nvidia.com> Acked-by: Danilo Krummrich <dakr@kernel.org> Link: https://patch.msgid.link/20260827-pramin-split-v3-7-24b24d7afc52@nvidia.com Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
Add documentation for the PRAMIN aperture mechanism used by nova-core
for direct VRAM access.

Nova only uses TARGET=VRAM for VRAM access. The SYS_MEM target values
are documented for completeness but not used by the driver.

Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>
[ecourtney: fix the TARGET encodings, KiB/MiB units, wording nits]
[ecourtney: wrap at 80 columns]
Signed-off-by: Eliot Courtney <ecourtney@nvidia.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://patch.msgid.link/20260827-pramin-split-v3-7-24b24d7afc52@nvidia.com
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
gpu: nova-core: add TLV parser for firmware files 2026-08-05T23:54:12+00:00 Timur Tabi ttabi@nvidia.com 2026-07-31T20:10:12+00:00 33f40117c0c53c88536936f14f87fc06279f1f2c TLV (type, length, value) files are the new image format used by Nova to encapsulate firmware images and their metadata. Unlike the firmware files for previous versions of the firmware, TLV filenames are not versioned, and they have a .tlv suffix. Add function request_tlv() to load TLV firmware images. Add the Tlv struct and supporting types for parsing TLV firmware images. TLV files begin with a 4-byte magic header, which must be "NVFW" for Nvidia firmware files. This is followed by a sequence of blocks each containing a 4-byte ASCII tag, a 4-byte little-endian length, and a payload padded to a 4-byte boundary. Tlv::new() validates the entire image up front, so that the iterator can subsequently yield blocks without fallible parsing. Also add accessor methods for the various encoded types that will be used by the driver. Signed-off-by: Timur Tabi <ttabi@nvidia.com> Reviewed-by: Alexandre Courbot <acourbot@nvidia.com> Tested-by: Alexandre Courbot <acourbot@nvidia.com> Link: https://patch.msgid.link/20260731201017.2580713-4-ttabi@nvidia.com [ Drop unnecessary payload.is_empty() check in Tlv::new(), use EINVAL instead of ENODATA in Tlv::get_bytes() and add a corresponding TODO comment. - Danilo ] Signed-off-by: Danilo Krummrich <dakr@kernel.org> 
TLV (type, length, value) files are the new image format used by Nova
to encapsulate firmware images and their metadata.  Unlike the firmware
files for previous versions of the firmware, TLV filenames are not
versioned, and they have a .tlv suffix.

Add function request_tlv() to load TLV firmware images.

Add the Tlv struct and supporting types for parsing TLV firmware images.
TLV files begin with a 4-byte magic header, which must be "NVFW" for
Nvidia firmware files.  This is followed by a sequence of blocks each
containing a 4-byte ASCII tag, a 4-byte little-endian length, and a
payload padded to a 4-byte boundary.

Tlv::new() validates the entire image up front, so that the iterator can
subsequently yield blocks without fallible parsing.

Also add accessor methods for the various encoded types that will be used
by the driver.

Signed-off-by: Timur Tabi <ttabi@nvidia.com>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Tested-by: Alexandre Courbot <acourbot@nvidia.com>
Link: https://patch.msgid.link/20260731201017.2580713-4-ttabi@nvidia.com
[ Drop unnecessary payload.is_empty() check in Tlv::new(), use EINVAL
  instead of ENODATA in Tlv::get_bytes() and add a corresponding TODO
  comment. - Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
gpu: nova-core: add FSP and PRC protocol documentation 2026-06-17T12:30:17+00:00 Zhi Wang zhiw@nvidia.com 2026-06-04T11:43:35+00:00 9b81ca3c96d217891a612c1d72ac17cb356ad4ac Add documentation for the Foundation Security Processor (FSP) interface covering the simplified Hopper/Blackwell boot flow, the Chain of Trust (COT) message protocol, the MCTP/NVDM message format, and the Product Reconfiguration Control (PRC) protocol used to query device configuration knobs such as vGPU mode. Signed-off-by: Zhi Wang <zhiw@nvidia.com> Link: https://patch.msgid.link/20260604114339.1565660-6-zhiw@nvidia.com Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
Add documentation for the Foundation Security Processor (FSP) interface
covering the simplified Hopper/Blackwell boot flow, the Chain of Trust
(COT) message protocol, the MCTP/NVDM message format, and the Product
Reconfiguration Control (PRC) protocol used to query device configuration
knobs such as vGPU mode.

Signed-off-by: Zhi Wang <zhiw@nvidia.com>
Link: https://patch.msgid.link/20260604114339.1565660-6-zhiw@nvidia.com
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
gpu: nova-core: vbios: move constants and functions to be associated 2026-05-25T18:18:08+00:00 Eliot Courtney ecourtney@nvidia.com 2026-05-25T13:57:39+00:00 c70fe8b2bacf6208263b728a742538f74c5da1ec Move constants and functions to be inside the impls of the types they are related to. This makes it more obvious what each type and value is for. Signed-off-by: Eliot Courtney <ecourtney@nvidia.com> Link: https://patch.msgid.link/20260525-fix-vbios-v5-21-e5e455251537@nvidia.com Signed-off-by: Danilo Krummrich <dakr@kernel.org> 
Move constants and functions to be inside the impls of the types they
are related to. This makes it more obvious what each type and value is
for.

Signed-off-by: Eliot Courtney <ecourtney@nvidia.com>
Link: https://patch.msgid.link/20260525-fix-vbios-v5-21-e5e455251537@nvidia.com
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
Documentation: gpu: nova: document the IFR header layout 2026-04-28T23:13:55+00:00 Timur Tabi ttabi@nvidia.com 2026-04-08T14:21:32+00:00 d8198971dc72808c7aa29b3556bcaac76702848b Init-from-ROM (IFR) is a special GPU feature used for power management on some Nvidia GPUs. It references data in the VBIOS for its operation, but for drivers the important piece is the header that precedes the VBIOS PCI Expansion ROM. Parsing VBIOS is necessary to boot GSP-RM on Turing, Ampere, and Ada GPUs. Most such GPUs do not need to parse the IFR header in order to find the VBIOS, but the Nvidia GA100 is the exception. GA100 lacks a display engine, so the PRAMIN method (which reads the VBIOS from VRAM via display hardware) is unavailable, forcing the driver to read the ROM directly via PROM. On other similar GPUs, either PRAMIN succeeds before PROM is tried, or the IFR hardware has already applied the ROM offset so that PROM reads transparently skip the IFR header. Note that GH100 also does not have a display engine, but it uses a completely different method to boot GSP-RM. This information is derived from NVIDIA's open-source GPU kernel module driver (aka OpenRM), specifically the NV_PBUS_IFR_FMT_FIXEDx definitions in dev_bus.h and the parsing logic in s_romImgFindPciHeader_TU102(). Signed-off-by: Timur Tabi <ttabi@nvidia.com> Reviewed-by: Joel Fernandes <joelagnelf@nvidia.com> Link: https://patch.msgid.link/20260408142132.3911466-1-ttabi@nvidia.com [acourbot: fix TOTAL_DATA_SIZE definition.] Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
Init-from-ROM (IFR) is a special GPU feature used for power management
on some Nvidia GPUs.  It references data in the VBIOS for its operation,
but for drivers the important piece is the header that precedes the
VBIOS PCI Expansion ROM.  Parsing VBIOS is necessary to boot GSP-RM on
Turing, Ampere, and Ada GPUs.

Most such GPUs do not need to parse the IFR header in order to find the
VBIOS, but the Nvidia GA100 is the exception.  GA100 lacks a display
engine, so the PRAMIN method (which reads the VBIOS from VRAM via
display hardware) is unavailable, forcing the driver to read the ROM
directly via PROM.  On other similar GPUs, either PRAMIN succeeds before
PROM is tried, or the IFR hardware has already applied the ROM offset
so that PROM reads transparently skip the IFR header.

Note that GH100 also does not have a display engine, but it uses a
completely different method to boot GSP-RM.

This information is derived from NVIDIA's open-source GPU kernel module
driver (aka OpenRM), specifically the NV_PBUS_IFR_FMT_FIXEDx definitions
in dev_bus.h and the parsing logic in s_romImgFindPciHeader_TU102().

Signed-off-by: Timur Tabi <ttabi@nvidia.com>
Reviewed-by: Joel Fernandes <joelagnelf@nvidia.com>
Link: https://patch.msgid.link/20260408142132.3911466-1-ttabi@nvidia.com
[acourbot: fix TOTAL_DATA_SIZE definition.]
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
Documentation: nova: remove register abstraction task 2026-03-26T06:10:29+00:00 Alexandre Courbot acourbot@nvidia.com 2026-03-25T02:46:23+00:00 1998e6be8239cd37817e05bdc21439de17b904df The `register!` macro has been implemented and all nova-core code converted to use it. Remove the corresponding task in todo.rst. Reviewed-by: Eliot Courtney <ecourtney@nvidia.com> Reviewed-by: Gary Guo <gary@garyguo.net> Acked-by: Danilo Krummrich <dakr@kernel.org> Link: https://patch.msgid.link/20260325-b4-nova-register-v4-10-bdf172f0f6ca@nvidia.com Signed-off-by: Alexandre Courbot <acourbot@nvidia.com> 
The `register!` macro has been implemented and all nova-core code
converted to use it. Remove the corresponding task in todo.rst.

Reviewed-by: Eliot Courtney <ecourtney@nvidia.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://patch.msgid.link/20260325-b4-nova-register-v4-10-bdf172f0f6ca@nvidia.com
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
Documentation: nova: update pending tasks 2026-01-26T17:16:14+00:00 Danilo Krummrich dakr@kernel.org 2026-01-19T15:31:05+00:00 cea7b66a80412e2a5b74627b89ae25f1d0110a4b Some tasks, while already having some progress, are still pending, hence update them. Link: https://patch.msgid.link/20260119153129.59876-2-dakr@kernel.org [ Remove PCI config space, as it is completed. - Danilo ] Signed-off-by: Danilo Krummrich <dakr@kernel.org> 
Some tasks, while already having some progress, are still pending, hence
update them.

Link: https://patch.msgid.link/20260119153129.59876-2-dakr@kernel.org
[ Remove PCI config space, as it is completed. - Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>