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 | 59 +++++++++++++++++++++++++
 Documentation/gpu/nova/index.rst        |  1 +
 drivers/gpu/nova-core/devinit.rs        |  6 +--
 3 files changed, 63 insertions(+), 3 deletions(-)
 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..85e7033dd3a7
--- /dev/null
+++ b/Documentation/gpu/nova/core/devinit.rst
@@ -0,0 +1,59 @@
+.. SPDX-License-Identifier: GPL-2.0
+==================================
+Device Initialization (devinit)
+==================================
+Note that devinit itself is a complicated process, subject to change, and this document
+only roughly provides an overview of the process using the Ampere GPU family as an example.
+The idea is to provide a conceptual overview of the process to help understand the kernel
+code that deals with it.
+
+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 engine 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 engine itself is part of the VBIOS ROM in the same ROM image as the
+FWSEC (Firmware Security) image (see fwsec.rst and vbios.rst) and it runs before the
+nova-core driver is even loaded. On an Ampere GPU, the devinit ucode (which is separate
+from the FWSEC ucode), is launched by the FWSEC (FWSEC runs on GSP in heavy-secure mode
+and devinit runs on PMU in light-secure mode).
+
+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
+
+Low-level Firmware Initialization Flow
+--------------------------------------
+Upon reset, several microcontrollers on the GPU (such as PMU, SEC2, GSP, etc.) run GPU 
+firmware (gfw) code to set up the GPU and its core parameters. Most of the GPU is
+considered unusable until this initialization process completes.
+
+These low-level GPU firmware components are typically:
+1. Located in the VBIOS ROM in the same ROM partition (see vbios.rst and fwsec.rst).
+2. Executed in sequence on different microcontrollers:
+   - The devinit engine typically but not necessarily runs on the PMU.
+   - On an Ampere GPU, the FWSEC typically runs on the GSP (GPU System Processor) in
+     heavy-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
+asserted by the FWSEC running on the GSP in heavy-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, as it is critical to power management.
+
+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. For example, to receive the
+GFW_BOOT signal.
\ No newline at end of file
diff --git a/Documentation/gpu/nova/index.rst b/Documentation/gpu/nova/index.rst
index 22e5712ac6b0..301435c5cf67 100644
--- a/Documentation/gpu/nova/index.rst
+++ b/Documentation/gpu/nova/index.rst
@@ -29,4 +29,5 @@ vGPU manager VFIO driver and the nova-drm driver.
    core/guidelines
    core/vbios
    core/fwsec
+   core/devinit
    core/todo
diff --git a/drivers/gpu/nova-core/devinit.rs b/drivers/gpu/nova-core/devinit.rs
index 21fc9b96d498..bd6a5c57c444 100644
--- a/drivers/gpu/nova-core/devinit.rs
+++ b/drivers/gpu/nova-core/devinit.rs
@@ -10,8 +10,8 @@
 //! 3. Clock and PLL configuration.
 //! 4. Thermal management.
 //!
-//! devinit itself is a 'script' which is interpreted by the PMU microcontroller of
-//! the GPU by an interpreter program.
+//! devinit itself is a 'script' which is interpreted by a microcontroller of
+//! the GPU by an interpreter program (typically running on the PMU).
 //!
 //! Note that the devinit sequence also needs to run during suspend/resume at runtime.
 
@@ -30,7 +30,7 @@
 ///
 /// The GPU firmware (gfw) code includes several components that execute before the driver loads.
 /// These components are located in the VBIOS ROM and are executed in a sequence on these different
-/// microcontrollers. The devinit sequence itself runs on the PMU, and the FWSEC runs on the GSP.
+/// microcontrollers. The devinit sequence typically runs on the PMU, and the FWSEC runs on the GSP.
 ///
 /// This function specifically waits for a signal indicating core initialization is complete before
 /// which not much can be done. This signal is setup by the FWSEC running on the GSP in Heavy-secured
-- 
2.43.0

On Sat, May 03, 2025 at 12:07:57AM -0400, Joel Fernandes wrote:
> +.. SPDX-License-Identifier: GPL-2.0
> +==================================
> +Device Initialization (devinit)
> +==================================

Separate SPDX line from title heading.

> +These low-level GPU firmware components are typically:
> +1. Located in the VBIOS ROM in the same ROM partition (see vbios.rst and fwsec.rst).
> +2. Executed in sequence on different microcontrollers:
> +   - The devinit engine typically but not necessarily runs on the PMU.
> +   - On an Ampere GPU, the FWSEC typically runs on the GSP (GPU System Processor) in
> +     heavy-secure mode.

Please separate numbered list from preceding sentence, and the bullet sublist
from parent numbered list by a line.

> +Runtime Considerations
> +---------------------
> <snipped>...
> +Security and Access Control
> +--------------------------

Match section underline length with the text.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

On 5/5/2025 12:04 AM, Bagas Sanjaya wrote:
> On Sat, May 03, 2025 at 12:07:57AM -0400, Joel Fernandes wrote:
>> +.. SPDX-License-Identifier: GPL-2.0
>> +==================================
>> +Device Initialization (devinit)
>> +==================================
> 
> Separate SPDX line from title heading.
> 
>> +These low-level GPU firmware components are typically:
>> +1. Located in the VBIOS ROM in the same ROM partition (see vbios.rst and fwsec.rst).
>> +2. Executed in sequence on different microcontrollers:
>> +   - The devinit engine typically but not necessarily runs on the PMU.
>> +   - On an Ampere GPU, the FWSEC typically runs on the GSP (GPU System Processor) in
>> +     heavy-secure mode.
> 
> Please separate numbered list from preceding sentence, and the bullet sublist
> from parent numbered list by a line.
> 
>> +Runtime Considerations
>> +---------------------
>> <snipped>...
>> +Security and Access Control
>> +--------------------------
> 
> Match section underline length with the text.
Thanks a lot for finding these issues. I have fixed everything and will re-post
patches end of the week. Please let me know if I can add your Tested-by tag.

Also here is my tree with the changes for a preview (top 7 patches):
https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova-docs

thanks,

 - Joel