[PATCH 6/6] nova-core: docs: Document devinit process

[Joel Fernandes <joelagnelf@nvidia.com>]

devinit is mentioned in the code. This patch explains it so it is clear
what it does. devinit is not only essential at boot-time, but also at
runtime due to suspend-resume and things like re-clocking.

Signed-off-by: Joel Fernandes <joelagnelf@nvidia.com>
---
 Documentation/gpu/nova/core/devinit.rst | 54 +++++++++++++++++++++++++
 Documentation/gpu/nova/index.rst        |  2 +
 2 files changed, 56 insertions(+)
 create mode 100644 Documentation/gpu/nova/core/devinit.rst

diff --git a/Documentation/gpu/nova/core/devinit.rst b/Documentation/gpu/nova/core/devinit.rst
new file mode 100644
index 000000000000..e504ed3efe15
--- /dev/null
+++ b/Documentation/gpu/nova/core/devinit.rst
@@ -0,0 +1,54 @@
+.. SPDX-License-Identifier: GPL-2.0
+==================================
+Device Initialization (devinit)
+==================================
+
+Overview
+--------
+Device initialization (devinit) is a crucial sequence of register read/write operations 
+that occur after a GPU reset. The devinit sequence is essential for properly configuring 
+the GPU hardware before it can be used.
+
+The devinit is an interpreter program that typically runs on the PMU (Power Management
+Unit) microcontroller of the GPU. This interpreter executes a "script" of initialization
+commands. The devinit interpreter itself is part of the FWSEC (Firmware Security) 
+component provided by the GPU firmware in the VBIOS ROM (see fwsec.rst and vbios.rst).
+
+Key Functions of devinit
+------------------------
+devinit performs several critical tasks:
+
+1. Programming VRAM memory controller timings
+2. Power sequencing
+3. Clock and PLL (Phase-Locked Loop) configuration
+4. Thermal management
+5. VRAM memory scrubbing (ECC initialization)
+   - On some GPUs, it scrubs only part of memory and then initiates 'async scrubbing'
+
+Firmware Initialization Flow
+---------------------------
+Upon reset, several microcontrollers on the GPU (such as PMU, SEC2, GSP, etc.) run GPU 
+firmware (gfw) code to set up core parameters. Most of the GPU is considered unusable 
+until this initialization process completes.
+
+The GPU firmware components are:
+1. Located in the VBIOS ROM
+2. Executed in sequence on different microcontrollers:
+   - The devinit sequence runs on the PMU
+   - The FWSEC runs on the GSP (Graphics System Processor) in high secure mode
+
+Before the driver can proceed with further initialization, it must wait for a signal 
+indicating that core initialization is complete (known as GFW_BOOT). This signal is
+set up by the FWSEC running on the GSP in high secure mode.
+
+Runtime Considerations
+---------------------
+It's important to note that the devinit sequence also needs to run during suspend/resume 
+operations at runtime, not just during initial boot.
+
+Security and Access Control
+--------------------------
+The initialization process involves careful privilege management. For example, before 
+accessing certain completion status registers, the driver must check privilege level 
+masks. Some registers are only accessible after secure firmware (FWSEC) lowers the 
+privilege level to allow CPU (LS/low-secure) access. 
\ No newline at end of file
diff --git a/Documentation/gpu/nova/index.rst b/Documentation/gpu/nova/index.rst
index c01dcc5657e2..301435c5cf67 100644
--- a/Documentation/gpu/nova/index.rst
+++ b/Documentation/gpu/nova/index.rst
@@ -27,5 +27,7 @@ vGPU manager VFIO driver and the nova-drm driver.
    :titlesonly:
 
    core/guidelines
+   core/vbios
    core/fwsec
+   core/devinit
    core/todo
-- 
2.43.0