Add explanation of fwsec with diagrams. This helps clarify how the
nova-core falcon boot works.
Signed-off-by: Joel Fernandes <joelagn...@nvidia.com>
---
Documentation/gpu/nova/core/fwsec.rst | 173 ++++++++++++++++++++++++++
Documentation/gpu/nova/core/vbios.rst | 3 +-
Documentation/gpu/nova/index.rst | 1 +
3 files changed, 176 insertions(+), 1 deletion(-)
create mode 100644 Documentation/gpu/nova/core/fwsec.rst
diff --git a/Documentation/gpu/nova/core/fwsec.rst
b/Documentation/gpu/nova/core/fwsec.rst
new file mode 100644
index 000000000000..03d1f0d67414
--- /dev/null
+++ b/Documentation/gpu/nova/core/fwsec.rst
@@ -0,0 +1,173 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+=========================
+FWSEC (Firmware Security)
+=========================
+
+The role of FWSEC to provide firmware verification and perform secure
operations
+such as carving out the WPR2 region (Write protected region). It is critical to
+the boot sequence of the GPU.
+
+The FWSEC image is located in the VBIOS ROM. For how it is extracted, see
vbios.rst
+and the vbios.rs source code.
+
+The Falcon data in the FWSEC image is a combination of headers, data sections
+(DMEM) and instruction code sections (IMEM).
+
+FWSEC itself is a central location for all microcodes in the VBIOS that run on
+various microcontrollers (PMU, SEC, GSP etc) some of which (such as devinit)
are
+executed after GPU power-on before the nova-core driver is even loaded.
+
+For the purposes of nova-core driver, the FWSEC contains microcode called
+DMEMMAPPER which executes the "FWSEC-FRTS" command (among other commands it is
+capable of executing) that is executed on the GSP to carve out the WPR2 region
+(Write protected region).
+
+FWSEC Memory Layout
+-------------------
+
+The memory layout of the FWSEC image is as follows (this is using an GA-102
+Ampere GPU as an example and could vary for future GPUs):
+
+┌───────────────────────────────────────────────────────────────┐
+│ FWSEC image (type 0xE0) │
+│ │
+│ ┌─────────────────────────────────┐ │
+│ │ PMU Falcon Ucode Table │ │
+│ │ (PmuLookupTable) │ │
+│ │ ┌─────────────────────────┐ │ │
+│ │ │ Table Header │ │ │
+│ │ │ - version: 0x01 │ │ │
+│ │ │ - header_size: 6 │ │ │
+│ │ │ - entry_size: 6 │ │ │
+│ │ │ - entry_count: N │ │ │
+│ │ │ - desc_version:3(unused)│ │ │
+│ │ └─────────────────────────┘ │ │
+│ │ ... │ │
+│ │ ┌─────────────────────────┐ │ │
+│ │ │ Entry for FWSEC (0x85) │ │ │
+│ │ │ (PmuLookupTableEntry) │ │ │
+│ │ │ - app_id: 0x85 (FWSEC) │ ───┼────┐ │
+│ │ │ - target_id: 0x01 (PMU) │ │ │ │
+│ │ │ - data: offset ─────────┼────┼────┼───┐ │
+│ │ └─────────────────────────┘ │ │ │ │
+│ └─────────────────────────────────┘ │ │ │
+│ │ │ │
+│ │ │ │
+│ ┌─────────────────────────────────┐ │ │ │
+│ │ FWSEC Ucode Component │<───┘ │ │
+│ │ (aka Falcon data) │ │ │
+│ │ ┌─────────────────────────┐ │ │ │
+│ │ │ FalconUCodeDescV3 │<───┼────────┘ │
+│ │ │ - hdr │ │ │
+│ │ │ - stored_size │ │ │
+│ │ │ - pkc_data_offset │ │ │
+│ │ │ - interface_offset ─────┼────┼────────────────┐ │
+│ │ │ - imem_phys_base │ │ │ │
+│ │ │ - imem_load_size │ │ │ │
+│ │ │ - imem_virt_base │ │ │ │
+│ │ │ - dmem_phys_base │ │ │ │
+│ │ │ - dmem_load_size │ │ │ │
+│ │ │ - engine_id_mask │ │ │ │
+│ │ │ - ucode_id │ │ │ │
+│ │ │ - signature_count │ │ look up sig │ │
+│ │ │ - signature_versions ───┼────┼─────┐using hal │ │
+│ │ └─────────────────────────┘ │ │ │ │
+│ │ (no gap) │ │ │ │
+│ │ ┌─────────────────────────┐ │ │ │ │
+│ │ │ Signatures Section │<───┼─────┘ │ │
+│ │ │ (384 bytes per sig) │ │ │ │
+│ │ │ - RSA-3K Signature 1 │ │ │ │
+│ │ │ - RSA-3K Signature 2 │ │ │ │
+│ │ │ ... │ │ │ │
+│ │ └─────────────────────────┘ │ │ │
+│ │ │ │ │
+│ │ ┌─────────────────────────┐ │ │ │
+│ │ │ IMEM Section (Code) │ │ │ │
+│ │ │ │ │ │ │
+│ │ │ Contains devinit, fwsec │ │ │ │
+│ │ │ instruction code etc. │ │ │ │
+│ │ └─────────────────────────┘ │ │ │
+│ │ │ │ │
+│ │ ┌─────────────────────────┐ │ │ │
+│ │ │ DMEM Section (Data) │ │ │ │
+│ │ │ │ │ │ │
+│ │ │ ┌─────────────────────┐ │ │ │ │
+│ │ │ │ Application │ │<───┼────────────────┘ │
+│ │ │ │ Interface Table │ │ │ │
+│ │ │ │ (FalconAppifHdrV1) │ │ │ │
+│ │ │ │ Header: │ │ │ │
+│ │ │ │ - version: 0x01 │ │ │ │
+│ │ │ │ - header_size: 4 │ │ │ │
+│ │ │ │ - entry_size: 8 │ │ │ │
+│ │ │ │ - entry_count: N │ │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ │ Entries: │ │ │ │
+│ │ │ │ ┌─────────────────┐ │ │ │ │
+│ │ │ │ │ DEVINIT (ID 1) │ │ │ │ │
+│ │ │ │ │ - id: 0x01 │ │ │ │ │
+│ │ │ │ │ - dmemOffset X ─┼─┼─┼────┐ │
+│ │ │ │ └─────────────────┘ │ │ │ │
+│ │ │ │ ┌─────────────────┐ │ │ │ │
+│ │ │ │ │ DMEMMAPPER(ID 4)│ │ │ │ │
+│ │ │ │ │ - id: 0x04 │ │ │ │ │
+| | | | | (NVFW_FALCON_ | | | | |
+| | | | | APPIF_ID_DMEMMAPPER) | |
+│ │ │ │ │ - dmemOffset Y ─┼─┼─┼────┼─────┐ │
+│ │ │ │ └─────────────────┘ │ │ │ │ │
+│ │ │ │ ┌─────────────────┐ │ │ │ │ │
+│ │ │ │ │ MULTI_FALCON (5)│ │ │ │ │ │
+│ │ │ │ │ - id: 0x05 │ │ │ │ │ (See note [1]) │
+│ │ │ │ │ - dmemOffset Z ─┼─┼─┼────┼─────┼────────────────┐ │
+│ │ │ │ └─────────────────┘ │ │ │ │ │ │
+│ │ │ └─────────────────────┘ │ │ │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ ┌─────────────────────┐ │ │ │ │ │
+│ │ │ │ DEVINIT Engine │<┼────┘ │ │ │
+│ │ │ │ Interface │ │ │ │ │ │
+│ │ │ └─────────────────────┘ │ │ │ │ │
+│ │ │ │ │ │ │ │
+│ │ │ ┌─────────────────────┐ │ │ │ │ │
+│ │ │ │ DMEM Mapper (ID 4) │<┼────+─────┘ │ │
+│ │ │ │ (FalconAppifDmemmapperV3) | | |
+│ │ │ │ - signature: "DMAP" │ │ │ | |
+│ │ │ │ - version: 0x0003 │ │ │ | |
+│ │ │ │ - Size: 64 bytes │ │ │ | |
+│ │ │ │ - cmd_in_buffer_off │ │────┼────────────┐ | |
+│ │ │ │ - cmd_in_buffer_size│ │ │ │ | |
+│ │ │ │ - cmd_out_buffer_off│ │────┼────────────┼─────┐ | |
+│ │ │ │ - cmd_out_buffer_sz │ │ │ │ │ | |
+│ │ │ │ - init_cmd │ │ │ │ │ | |
+│ │ │ │ - features │ │ │ │ │ | |
+│ │ │ │ - cmd_mask0/1 │ │ │ │ │ V |
+│ │ │ │ - multiTgtTbl-------┼─┼────+────────────+─────+────┐ │
+│ │ │ └─────────────────────┘ │ │ │ │ │ │
+│ │ │ │ │ │ │ │ │
+│ │ │ ┌─────────────────────┐ │ │ │ │ │ │
+│ │ │ │ MULTI_FALCON │<┼────+────────────+─────+────┘ │
+│ │ │ │ - version │ │ │ │ │ |
+│ │ │ │ - targetId (PMU/SEC)│ │ │ │ │ |
+│ │ │ │ - loadType │ │ │ │ │ |
+│ │ │ │ - initStack │ │ │ │ │ |
+│ │ │ └─────────────────────┘ │ │ │ │ |
+│ │ │ │ │ │ │ |
+│ │ │ ┌─────────────────────┐ │ │ │ │ |
+│ │ │ │ Command Input Buffer│<┼────┼────────────┘ │ |
+│ │ │ │ - Command data │ │ │ │ |
+│ │ │ │ - Arguments │ │ │ │ |
+│ │ │ └─────────────────────┘ │ │ │ |
+│ │ │ │ │ │ |
+│ │ │ ┌─────────────────────┐ │ │ │ |
+│ │ │ │ Command Output │<┼────┼──────────────────┘ |
+│ │ │ │ Buffer │ │ │ |
+│ │ │ │ - Results │ │ │ |
+│ │ │ │ - Status │ │ │ |
+│ │ │ └─────────────────────┘ │ │ |
+│ │ └─────────────────────────┘ │ |
+│ └─────────────────────────────────┘ |
+│ │
+└───────────────────────────────────────────────────────────────┘
+
+Note:
+[1] MULTI_FALCON section in DMEM can either be looked up by
+ MULTI_FALCON App Interface, or from multi_tgt_table entry
+ in DMEM_MAPPER's App Interface.
\ No newline at end of file
diff --git a/Documentation/gpu/nova/core/vbios.rst
b/Documentation/gpu/nova/core/vbios.rst
index 17411f21b410..da759b56fb2d 100644
--- a/Documentation/gpu/nova/core/vbios.rst
+++ b/Documentation/gpu/nova/core/vbios.rst
@@ -44,7 +44,8 @@ VBIOS ROM Layout
The VBIOS layout is roughly a series of concatenated images as follows:
(For more explanations of acronyms, see the detailed descriptions in vbios.rs).
-
+Note: this diagram is using an GA-102 Ampere GPU as an example and could vary
+ for future GPUs.
┌────────────────────────────────────────────────────────────────────────┐
│ VBIOS (Starting at ROM_OFFSET: 0x300000) │
├────────────────────────────────────────────────────────────────────────┤
diff --git a/Documentation/gpu/nova/index.rst b/Documentation/gpu/nova/index.rst
index 2701b3f4af35..c01dcc5657e2 100644
--- a/Documentation/gpu/nova/index.rst
+++ b/Documentation/gpu/nova/index.rst
@@ -27,4 +27,5 @@ vGPU manager VFIO driver and the nova-drm driver.
:titlesonly:
core/guidelines
+ core/fwsec
core/todo
--
2.43.0
