[PATCH] Documentation: gpu: nova-core: document the IFR header layout

[Timur Tabi <ttabi@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>
---
 Documentation/gpu/nova/core/vbios.rst | 63 ++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/nova/core/vbios.rst b/Documentation/gpu/nova/core/vbios.rst
index efd40087480c..c9c25264f45d 100644
--- a/Documentation/gpu/nova/core/vbios.rst
+++ b/Documentation/gpu/nova/core/vbios.rst
@@ -46,12 +46,71 @@ region is only accessible to heavy-secure ucode.
    are of type 0xE0 and can be identified as such. This could be subject to change
    in future generations.
 
+IFR Header
+----------
+On Kepler and later GPUs, the ROM begins with an Init-from-ROM (IFR) header
+rather than a standard PCI ROM signature (0xAA55). The driver must parse the
+IFR header to find where the PCI ROM images actually start.
+
+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 a header that precedes the
+VBIOS PCI Expansion ROM.
+
+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.
+
+The driver should first check for the standard 0xAA55 signature at offset 0.
+If found, there is no IFR header and the PCI ROM images start at
+offset 0. If not found, check for the IFR signature and parse the header to
+determine the PCI ROM image offset.
+
+Fixed Header Format
+~~~~~~~~~~~~~~~~~~~
+
+The IFR header begins with four 32-bit words at fixed offsets::
+
+    Offset  Name     Fields
+    ------  -------  ------
+    0x00    FIXED0   bits 31:0  - Signature (must be 0x4947564E, ASCII "NVGI")
+    0x04    FIXED1   bit  31    - Reserved
+                     bits 30:16 - FIXED_DATA_SIZE Fixed data size (offset to extended section)
+                     bits 15:8  - VERSIONSW Software version
+                     bits 7:0   - Reserved
+    0x08    FIXED2   bit  31    - Reserved
+                     bits 30:20 - Reserved (zero)
+                     bits 19:0  - Total data size
+
+Finding the PCI ROM Image Offset
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The method to find this offset depends on `VERSIONSW`.
+
+- **Version 1 and 2**: Read `FIXED_DATA_SIZE` from `FIXED1` to get the extended
+  section offset. The PCI ROM image is the 32-bit value at `FIXED_DATA_SIZE + 4`.
+
+- **Version 3**: Read `TOTAL_DATA_SIZE` from `FIXED2`. The 32-bit value at that
+  offset is a flash status offset. Add 4096 to get the ROM directory offset,
+  `ROM_DIRECTORY_OFFSET`.  The ROM directory must have signature 0x44524652
+  (ASCII "RFRD"). The PCI ROM image offset is the 32-bit value at
+  `ROM_DIRECTORY_OFFSET + 8`.
+
+The PCI ROM image offset must be 4-byte aligned. All offsets are relative to the
+start of ROM (BAR0 + 0x300000).
+
 VBIOS ROM Layout
 ----------------
-The VBIOS layout is roughly a series of concatenated images laid out as follows::
+The VBIOS (PCI Expansion ROM) is a series of concatenated images laid out as
+follows. On GPUs with an IFR header, this layout begins at the image offset
+determined by parsing the IFR header. On older GPUs, it begins at offset 0::
 
     +----------------------------------------------------------------------------+
-    | VBIOS (Starting at ROM_OFFSET: 0x300000)                                   |
+    | VBIOS (Starting at ROM_OFFSET: 0x300000 + IFR image offset)                |
     +----------------------------------------------------------------------------+
     | +-----------------------------------------------+                          |
     | | PciAt Image (Type 0x00)                       |                          |

base-commit: b20a9b5f9c4baeae0b2e143046b195b910c59714
-- 
2.53.0