Re: [PATCH v8 07/25] docs: gpu: nova-core: Document the PRAMIN aperture mechanism

[Alexandre Courbot]

On Wed Feb 25, 2026 at 7:53 AM JST, Joel Fernandes wrote:
> Add documentation for the PRAMIN aperture mechanism used by nova-core
> for direct VRAM access.
>
> Nova only uses TARGET=VID_MEM for VRAM access. The SYS_MEM target values
> are documented for completeness but not used by the driver.
>
> Cc: Nikola Djukic <ndjukic@xxxxxxxxxx>
> Signed-off-by: Joel Fernandes <joelagnelf@xxxxxxxxxx>
> ---
>  Documentation/gpu/nova/core/pramin.rst | 125 +++++++++++++++++++++++++
>  Documentation/gpu/nova/index.rst       |   1 +
>  2 files changed, 126 insertions(+)
>  create mode 100644 Documentation/gpu/nova/core/pramin.rst
>
> diff --git a/Documentation/gpu/nova/core/pramin.rst b/Documentation/gpu/nova/core/pramin.rst
> new file mode 100644
> index 000000000000..55ec9d920629
> --- /dev/null
> +++ b/Documentation/gpu/nova/core/pramin.rst
> @@ -0,0 +1,125 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=========================
> +PRAMIN aperture mechanism
> +=========================
> +
> +.. note::
> +   The following description is approximate and current as of the Ampere family.
> +   It may change for future generations and is intended to assist in understanding
> +   the driver code.
> +
> +Introduction
> +============
> +
> +PRAMIN is a hardware aperture mechanism that provides CPU access to GPU Video RAM (VRAM) before
> +the GPU's Memory Management Unit (MMU) and page tables are initialized. This 1MB sliding window,
> +located at a fixed offset within BAR0, is essential for setting up page tables and other critical
> +GPU data structures without relying on the GPU's MMU.
> +
> +Architecture Overview
> +=====================
> +
> +The PRAMIN aperture mechanism is logically implemented by the GPU's PBUS (PCIe Bus Controller Unit)
> +and provides a CPU-accessible window into VRAM through the PCIe interface::
> +
> +    +-----------------+    PCIe     +------------------------------+
> +    |      CPU        |<----------->|           GPU                |
> +    +-----------------+             |                              |
> +                                    |  +----------------------+    |
> +                                    |  |       PBUS           |    |
> +                                    |  |  (Bus Controller)    |    |
> +                                    |  |                      |    |
> +                                    |  |  +--------------+<------------ (window starts at
> +                                    |  |  |   PRAMIN     |    |    |     BAR0 + 0x700000)
> +                                    |  |  |   Window     |    |    |
> +                                    |  |  |   (1MB)      |    |    |
> +                                    |  |  +--------------+    |    |
> +                                    |  |         |            |    |
> +                                    |  +---------|------------+    |
> +                                    |            |                 |
> +                                    |            v                 |
> +                                    |  +----------------------+<------------ (Program PRAMIN to any
> +                                    |  |       VRAM           |    |    64KB-aligned VRAM boundary)
> +                                    |  |    (Several GBs)     |    |
> +                                    |  |                      |    |
> +                                    |  |  FB[0x000000000000]  |    |
> +                                    |  |          ...         |    |
> +                                    |  |  FB[0x7FFFFFFFFFF]   |    |
> +                                    |  +----------------------+    |
> +                                    +------------------------------+
> +
> +PBUS (PCIe Bus Controller) is responsible for, among other things, handling MMIO
> +accesses to the BAR registers.
> +
> +PRAMIN Window Operation
> +=======================
> +
> +The PRAMIN window provides a 1MB sliding aperture that can be repositioned over
> +the entire VRAM address space using the ``NV_PBUS_BAR0_WINDOW`` register.
> +
> +Window Control Mechanism
> +-------------------------
> +
> +The window position is controlled via the PBUS ``BAR0_WINDOW`` register::

This repeats the sentence of `PRAMIN Window Operation`. Let's remove
that sentence.

> +
> +    NV_PBUS_BAR0_WINDOW Register (0x1700):
> +    +-------+--------+--------------------------------------+
> +    | 31:26 | 25:24  |               23:0                   |
> +    | RSVD  | TARGET |            BASE_ADDR                 |
> +    |       |        |        (bits 39:16 of VRAM address)  |
> +    +-------+--------+--------------------------------------+
> +
> +    BASE_ADDR field (bits 23:0):
> +    - Contains bits [39:16] of the target VRAM address
> +    - Provides 40-bit (1TB) address space coverage
> +    - Must be programmed with 64KB-aligned addresses

This reads a bit like filler - let's turn this into a single sentence,
of just keep the first point - the other two are deducible from it.