From 1d6ec86812605a55549f06c72ffdae6ce00944a7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andreas=20F=C3=A4rber?= <afaerber@suse.com>
Date: Tue, 28 May 2024 19:25:58 +0200
Subject: [PATCH] WIP: NVIDIA Jetson flashing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document how to enable NVIDIA Jetson to boot SUSE Linux.

Signed-off-by: Andreas Färber <afaerber@suse.com>
---
 articles/nvidia-jetson.asm.xml   |  9 +++
 tasks/nvidia-jetson-firmware.xml | 97 ++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 tasks/nvidia-jetson-firmware.xml

diff --git a/articles/nvidia-jetson.asm.xml b/articles/nvidia-jetson.asm.xml
index 10c66ddef..e70fea53b 100644
--- a/articles/nvidia-jetson.asm.xml
+++ b/articles/nvidia-jetson.asm.xml
@@ -38,6 +38,9 @@
   </resources>-->
   <!-- Tasks -->
   <resources>
+    <resource xml:id="_nvidia-jetson-firmware" href="../tasks/nvidia-jetson-firmware.xml">
+      <description>Firmware</description>
+    </resource>
     <resource xml:id="_nvidia-jetson-sidecar-kmp" href="../tasks/nvidia-jetson-kmp.xml">
       <description>KMP</description>
     </resource>
@@ -72,6 +75,11 @@
           <revdescription>
             <itemizedlist>
               <!-- Group by type of change (added/removed/changed)-->
+              <listitem><para>Added sections:</para>
+                <itemizedlist>
+                  <listitem><para>Added section on flashing</para></listitem>
+                </itemizedlist>
+              </listitem>
               <listitem><para>Changed sections:</para>
                 <itemizedlist>
                   <listitem><para>Updated section on KMP with more detailed uname -r output</para></listitem>
@@ -206,6 +214,7 @@
         <title>You are a very special concept now!</title>
       </merge>
     </module>-->
+    <module resourceref="_nvidia-jetson-firmware" renderas="section"/>
     <module resourceref="_nvidia-jetson-sidecar-kmp" renderas="section"/>
     <module resourceref="_nvidia-jetson-sidecar-libs" renderas="section"/>
     <!--<module resourceref="_reference-example" renderas="section"/>
diff --git a/tasks/nvidia-jetson-firmware.xml b/tasks/nvidia-jetson-firmware.xml
new file mode 100644
index 000000000..5847e2e51
--- /dev/null
+++ b/tasks/nvidia-jetson-firmware.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="nvidia-jetson-firmware"
+ role="task" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Preparing firmware for NVIDIA Jetson platforms</title><!-- can be changed via merge
+in the assembly -->
+    <!-- add author's e-mail -->
+    <meta name="maintainer" content="andreas.faerber@suse.com" its:translate="no"/>
+    <abstract><!-- can be changed via merge in the assembly -->
+      <para>
+       UEFI system firmware allows &suse; Linux media and installations to boot.
+      </para>
+    </abstract>
+  </info>
+  <section xml:id="nvidia-jetson-firmware-introduction">
+    <title>Introduction</title>
+    <para>
+      &suse; Linux installation media are formatted as UEFI Removable Media
+      and require &arm; EBBR compliant boot firmware on the system.
+    </para>
+  </section>
+  <section xml:id="nvidia-jetson-firmware-requirements">
+    <title>Requirements</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          &nvidia; &jetson; &xavier;, &orin; or later System-on-Module or &nvidia; IGX &orin; based system
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Second system (e.g., notebook) with USB connection to your &nvidia; based system
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="nvidia-jetson-firmware-flash">
+    <title>Flashing the firmware</title>
+    <para>
+      Follow &nvidia; or OEM provided instructions for flashing your system.
+      &suse; Linux installation will be easiest if boot firmware and operating system
+      do not share the same storage device, i.e., SPI flash for firmware.
+    </para>
+    <procedure>
+      <step>
+        <para>
+          Power on the &nvidia; system and enter recovery mode
+          according to its vendor instructions.
+        </para>
+      </step>
+      <step>
+        <para>
+          Flash the boot firmware via USB from the secondary system:
+        </para>
+<screen>&prompt.sudo;<command>./flash.sh <replaceable>p3740-0002-p3701-0008-qspi</replaceable> external</command></screen>
+        <note>
+          <para>
+            The exact system profile depends on your system and your intended usage.
+            Above example is for an &nvidia; IGX &orin; Developer Kit,
+            using QSPI flash for firmware, leaving eMMC storage for the operating system.
+          </para>
+        </note>
+      </step>
+    </procedure>
+  </section>
+  <section xml:id="nvidia-jetson-firmware-summary">
+    <title>Summary</title>
+    <para>
+      You have updated the boot firmware and possibly changed its storage location.
+      During system boot it should identify on serial console similar to:
+    </para>
+    <screen>Jetson System firmware version 36.3.0-gcid-35925539 date 2024-04-04T17:32:50+00:</screen>
+    <!-- TODO update this -->
+  </section>
+  <section xml:id="nvidia-jetson-firmware-troubleshooting">
+    <title>Troubleshooting</title>
+    <para>
+      Refer to &nvidia; documentation.
+    </para>
+  </section>
+</topic>