[PATCH v2 4/7] nova-core: docs: Document fwsec operation and layout

Bagas Sanjaya bagasdotme at gmail.com
Mon May 5 03:52:11 UTC 2025


On Sat, May 03, 2025 at 12:07:56AM -0400, Joel Fernandes wrote:
> +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> +=========================
> +FWSEC (Firmware Security)
> +=========================

Separate SPDX line from title heading.

> +Here is a block diagram of the FWSEC memory layout::

Add blank line before actual diagram below.

> + ┌───────────────────────────────────────────────────────────────┐
> + │                         FWSEC ROM 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 ─────────┼────┼────┼───┐ look up FWSEC   │
> + │  │  └─────────────────────────┘    │    │   │ application.    │
> + │  └─────────────────────────────────┘    │   │                 │
> + │                                         │   │                 │
> + │                                         │   │                 │
> + │  ┌─────────────────────────────────┐    │   │                 │
> + │  │     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 --------------+          │         │
> + │  │  └─────────────────────────┘    │     │          │         │
> + │  │         (no gap)                │     │          │         │
> + │  │  ┌─────────────────────────┐    │     │          │         │
> + │  │  │ Signatures Section      │<───┼─────┘          │         │
> + │  │  │ (384 bytes per sig)     │    │                │         │
> + │  │  │ - RSA-3K Signature 1    │    │                │         │
> + │  │  │ - RSA-3K Signature 2    │    │                │         │
> + │  │  │   ...                   │    │                │         │
> + │  │  └─────────────────────────┘    │                │         │
> + │  │                                 │                │         │
> + │  │  ┌─────────────────────────┐    │                │         │
> + │  │  │ IMEM Section (Code)     │    │                │         │
> + │  │  │                         │    │                │         │
> + │  │  │ Contains 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      │ │ │    │ Used only for DevInit    │
> + │  │  │ │ │  (NVFW_FALCON_  │ │ │    │ application (not FWSEC)  │
> + │  │  │ │ │   APPIF_ID_DMEMMAPPER)   │                          │
> + │  │  │ │ │ - dmemOffset Y ─┼─┼─┼────┼─────┐                    │
> + │  │  │ │ └─────────────────┘ │ │    │     │                    │
> + │  │  │ └─────────────────────┘ │    │     │                    │
> + │  │  │                         │    │     │                    │
> + │  │  │ ┌─────────────────────┐ │    │     │                    │
> + │  │  │ │ DEVINIT Engine      │<┼────┘     │ Used by FWSEC      │
> + │  │  │ │ Interface           │ │    │     │         app.       │
> + │  │  │ └─────────────────────┘ │    │     │                    │
> + │  │  │                         │    │     │                    │
> + │  │  │ ┌─────────────────────┐ │    │     │                    │
> + │  │  │ │ 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       │ │    │            │     │       │
> + │  │  │ └─────────────────────┘ │    │            │     │       │
> + │  │  │                         │    │            │     │       │
> + │  │  │ ┌─────────────────────┐ │    │            │     │       │
> + │  │  │ │ Command Input Buffer│<┼────┼────────────┘     │       │
> + │  │  │ │ - Command data      │ │    │                  │       │
> + │  │  │ │ - Arguments         │ │    │                  │       │
> + │  │  │ └─────────────────────┘ │    │                  │       │
> + │  │  │                         │    │                  │       │
> + │  │  │ ┌─────────────────────┐ │    │                  │       │
> + │  │  │ │ Command Output      │<┼────┼──────────────────┘       │
> + │  │  │ │ Buffer              │ │    │                          │
> + │  │  │ │ - Results           │ │    │                          │
> + │  │  │ │ - Status            │ │    │                          │
> + │  │  │ └─────────────────────┘ │    │                          │
> + │  │  └─────────────────────────┘    │                          │
> + │  └─────────────────────────────────┘                          │
> + │                                                               │
> + └───────────────────────────────────────────────────────────────┘

The diagram can look messy on certain fonts in htmldocs output. Please
use ASCII dash (-) and vertical bar (|) instead of Unicode box decoration
variant (─ and │).

Thanks.

-- 
An old man doll... just what I always wanted! - Clara
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20250505/40d96535/attachment-0001.sig>


More information about the dri-devel mailing list