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

Bagas Sanjaya
2025-05-05T03:52:11Z

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/nouveau/attachments/20250505/40d96535/attachment-0001.sig>