# intel/pfr-wilson-city architecture

> Architecture diagram of the GitHub repository intel/pfr-wilson-city, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intel/pfr-wilson-city
- Repository: https://github.com/intel/pfr-wilson-city

## Overview

1. This repository is an Intel Platform Firmware Resiliency (PFR) reference design for an Intel MAX 10 FPGA. It is not a single app, but a hardware-and-embedded-firmware system that protects and recovers platform firmware for the host platform.

2. The repo is split into three architectural layers:
   - FPGA RTL at the root and under `src/`
   - Embedded Nios firmware under `fw/code/`
   - C++ test harnesses and mocks under `fw/test/`
   That boundary is important for any diagram: the FPGA logic enforces protection in hardware, while the Nios software performs policy, validation, and update orchestration.

3. There are three top-level FPGA configurations: `pfr`, `non_pfr`, and `recovery`. The files `pfr_top.sv`, `non_pfr_top.sv`, and `recovery_top.sv` plus their corresponding cores/QSFs show that the design can be built into different modes, with `recovery` as a distinct minimal rescue path.

4. The central hardware subsystem is the PFR core in `src/core_cpld/wilson_city/Source/`. This contains the platform-specific sequencing and protection logic for power, reset, thermal, and fault handling, including modules like `Pch_Seq`, `Bmc_Seq`, `Cpu_Seq`, `PwrgdLogic`, `Prochot`, `SmaRT`, and `PFR_ByPass`. This is the logic that sits between the board and the protected platform signals.

5. Firmware-facing control and data paths are implemented as FPGA IP blocks under `src/`:
   - `smbus_mailbox` for host/management communication over SMBus/I2C
   - `smbus_filtered_relay` for gating or relaying bus traffic
   - `spi_control` for flash access and filtering
   - `rfnvram_smbus_master` for reading/writing protected nonvolatile state over SMBus/I2C
   - `timer_bank` for timing/timeout infrastructure
   - `jtag_lock_controller` for limiting debug access
   These blocks are the main interfaces between the embedded firmware and the board environment.

6. The embedded firmware in `fw/code/` is the policy and orchestration layer running on Nios II inside `pfr_sys` or `recovery_sys`. Its headers show the major responsibilities: authentication, capsule validation, decompression, firmware update/recovery, flash validation, key cancellation, PFM handling, UFM/RFNVRAM access, mailbox handling, and watchdog/timing. The firmware is organized around those security and lifecycle functions rather than a general-purpose application model.

7. The security pipeline is anchored by the crypto and validation modules. Under `src/crypto/` there is dedicated SHA-256 and ECDSA-256 RTL, while the firmware headers `authentication.h`, `capsule_validation.h`, `pfm_validation.h`, and `flash_validation.h` show how signatures, hashes, and image structure checks are composed. The update path therefore depends on hardware crypto plus firmware policy enforcement.

8. The update and recovery flow is image-centric. Test data and headers reference signed capsules, PFM images, anti-rollback cases, key-cancellation certificates, and full PFR images. This indicates the system validates signed update capsules, checks rollback/version rules, and then writes to protected flash partitions or staging areas through `spi_control`. If validation fails or the system is in a degraded state, recovery logic can restore known-good images from protected storage.

9. Persistent security state is split across protected storage domains. `ufm`/`ufm_rw_utils` suggests FPGA UFM is used for secrets, keys, or provisioning data, while `rfnvram`/`rfnvram_utils` indicates additional retained configuration or state stored externally and accessed through the SMBus master. `keychain`, `keychain_utils`, and `key_cancellation` show that trust anchors are managed explicitly, not embedded as static constants only.

10. The platform-specific design is parameterized for the “Wilson City” board family. The board wrappers under `fw/code/hw/wilson_city_fab2` and `src/core_cpld/wilson_city/` contain the board-specific pin/control logic, while generated packages like `gen_gpi_signals_pkg`, `gen_gpo_controls_pkg`, and `gen_smbus_relay_config_pkg` indicate that board I/O and relay behavior are generated from configuration. This is the boundary where a generic PFR architecture becomes a specific board implementation.

11. The system also includes a recovery-focused subsystem in `src/recovery_sys/` and matching firmware under `fw/code/hw/wilson_city_fab2_recovery`. That path exists so the platform can boot and execute a reduced feature set when the main PFR path is unavailable or compromised.

12. Verification is a major part of the repository architecture. `fw/test/` contains extensive unit and flow tests, plus mocks for SPI, SMBus, UFM, RFNVRAM, timers, crypto, and mailbox interfaces. The test corpus includes many signed-good and signed-bad capsule images, anti-rollback cases, key-cancellation cases, and recovery/update scenarios, which reflects the real system’s state-machine complexity and security-critical branching.

13. In diagram terms, the core data flow is: platform buses and flash traffic enter the FPGA protection layer; the mailbox/SMBus and SPI subsystems hand requests to the Nios firmware; firmware validates images using crypto and policy state from UFM/RFNVRAM; approved updates are written to flash; and recovery paths restore protected images when the active image is invalid or compromised.

14. The build/tooling model reflects the same split: Quartus/Qsys project files define the FPGA systems, Makefiles and shell scripts build the alternate images, and the Nios firmware is compiled separately from the RTL. So the architecture is a tightly coupled hardware/software security appliance, not just an FPGA peripheral.

Main entry points: [`src/pfr_sys/pfr_sys.qsys`](https://github.com/intel/pfr-wilson-city/blob/master/src/pfr_sys/pfr_sys.qsys) (PFR system), [`fw/code/inc/pfr_main.h`](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/pfr_main.h) (Nios firmware), [`src/core_cpld/wilson_city/Source/Wilson_City_Main.v`](https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/Wilson_City_Main.v) (Wilson core), [`fw/test/main.cpp`](https://github.com/intel/pfr-wilson-city/blob/master/fw/test/main.cpp) (Test suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fpga["FPGA RTL"]
  node_top_build["Build/Top<br/>build orchestration"]
  node_pfr_top["PFR top<br/>fpga image<br/>[pfr_top.sv]"]
  node_non_pfr_top["Non-PFR top<br/>fpga image<br/>[non_pfr_top.sv]"]
  node_recovery_top["Recovery top<br/>fpga image<br/>[recovery_top.sv]"]
  node_pfr_sys["PFR system<br/>qsys system<br/>[pfr_sys.qsys]"]
  node_recovery_sys["Recovery sys<br/>qsys system<br/>[recovery_sys.qsys]"]
  node_wilson_core["Wilson core<br/>board CPLD core<br/>[Wilson_City_Main.v]"]
  node_seq_logic["Sequencing<br/>protection logic<br/>[Pch_Seq.v]"]
  node_fault_logic["Fault control<br/>protection logic<br/>[PFR_ByPass.v]"]
  node_smbus_mailbox["Mailbox<br/>smbus interface<br/>[smbus_mailbox.sv]"]
  node_smbus_relay["Relay gate<br/>bus filter"]
  node_spi_control["SPI control<br/>flash control<br/>[spi_control.sv]"]
  node_rfnvram_master["RFNVRAM master<br/>i2c master"]
  node_timer_bank["Timer bank<br/>timing block<br/>[timer_bank.sv]"]
  node_jtag_lock["JTAG lock<br/>debug control"]
  node_crypto["Crypto RTL<br/>sha+ecdsa engine<br/>[crypto256_top.sv]"]
end

subgraph group_fw["Embedded Firmware"]
  node_firmware["Nios firmware<br/>policy engine<br/>[pfr_main.h]"]
  node_fw_update["Update flow<br/>image lifecycle<br/>[firmware_update.h]"]
  node_fw_state["Security state<br/>trust storage<br/>[ufm.h]"]
  node_fw_mailbox["Mailbox policy<br/>command handling<br/>[mailbox_utils.h]"]
  node_fw_validation["Validation<br/>security checks<br/>[authentication.h]"]
  node_fw_recovery["Recovery logic<br/>rescue flow"]
end

subgraph group_test["Verification"]
  node_tests["Test suite<br/>C++ verification<br/>[main.cpp]"]
  node_mocks["Mocks<br/>[system_mock.h]"]
  node_testdata["Test data<br/>signed images"]
end

node_top_build -->|"builds"| node_pfr_top
node_top_build -->|"builds"| node_non_pfr_top
node_top_build -->|"builds"| node_recovery_top
node_pfr_top -->|"integrates"| node_pfr_sys
node_recovery_top -->|"integrates"| node_recovery_sys
node_pfr_top -->|"hosts"| node_wilson_core
node_non_pfr_top -->|"hosts"| node_wilson_core
node_recovery_top -->|"hosts"| node_wilson_core
node_wilson_core -->|"sequencing"| node_seq_logic
node_wilson_core -->|"faults"| node_fault_logic
node_pfr_sys -->|"exposes"| node_smbus_mailbox
node_pfr_sys -->|"routes"| node_smbus_relay
node_pfr_sys -->|"controls"| node_spi_control
node_pfr_sys -->|"reads/writes"| node_rfnvram_master
node_pfr_sys -->|"times"| node_timer_bank
node_pfr_sys -->|"guards"| node_jtag_lock
node_fw_validation -->|"verifies"| node_crypto
node_firmware -->|"uses"| node_fw_validation
node_firmware -->|"orchestrates"| node_fw_update
node_firmware -->|"persists"| node_fw_state
node_firmware -->|"handles"| node_fw_mailbox
node_firmware -->|"recovers"| node_fw_recovery
node_tests -->|"stubs"| node_mocks
node_tests -->|"covers"| node_testdata
node_tests -->|"validates"| node_firmware
node_tests -->|"validates"| node_crypto

click node_top_build "https://github.com/intel/pfr-wilson-city/tree/master/Makefile"
click node_pfr_top "https://github.com/intel/pfr-wilson-city/blob/master/pfr_top.sv"
click node_non_pfr_top "https://github.com/intel/pfr-wilson-city/blob/master/non_pfr_top.sv"
click node_recovery_top "https://github.com/intel/pfr-wilson-city/blob/master/recovery_top.sv"
click node_pfr_sys "https://github.com/intel/pfr-wilson-city/blob/master/src/pfr_sys/pfr_sys.qsys"
click node_recovery_sys "https://github.com/intel/pfr-wilson-city/blob/master/src/recovery_sys/recovery_sys.qsys"
click node_wilson_core "https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/Wilson_City_Main.v"
click node_seq_logic "https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/Pch_Seq.v"
click node_fault_logic "https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/PFR_ByPass.v"
click node_smbus_mailbox "https://github.com/intel/pfr-wilson-city/blob/master/src/smbus_mailbox/smbus_mailbox.sv"
click node_smbus_relay "https://github.com/intel/pfr-wilson-city/blob/master/src/smbus_filtered_relay/smbus_filtered_relay.sv"
click node_spi_control "https://github.com/intel/pfr-wilson-city/blob/master/src/spi_control/spi_control.sv"
click node_rfnvram_master "https://github.com/intel/pfr-wilson-city/blob/master/src/rfnvram_smbus_master/rfnvram_smbus_master.sv"
click node_timer_bank "https://github.com/intel/pfr-wilson-city/blob/master/src/timer_bank/timer_bank.sv"
click node_jtag_lock "https://github.com/intel/pfr-wilson-city/blob/master/src/jtag_lock_controller/jtag_lock_controller.sv"
click node_crypto "https://github.com/intel/pfr-wilson-city/blob/master/src/crypto/crypto256_top.sv"
click node_firmware "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/pfr_main.h"
click node_fw_update "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/firmware_update.h"
click node_fw_state "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/ufm.h"
click node_fw_mailbox "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/mailbox_utils.h"
click node_fw_validation "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/authentication.h"
click node_fw_recovery "https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/firmware_recovery.h"
click node_tests "https://github.com/intel/pfr-wilson-city/blob/master/fw/test/main.cpp"
click node_mocks "https://github.com/intel/pfr-wilson-city/blob/master/fw/test/system/system_mock.h"
click node_testdata "https://github.com/intel/pfr-wilson-city/blob/master/fw/test/testdata/signed_capsule_pch.bin.gz"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_top_build,node_pfr_top,node_non_pfr_top,node_recovery_top,node_pfr_sys,node_recovery_sys,node_wilson_core,node_seq_logic,node_fault_logic,node_smbus_mailbox,node_smbus_relay,node_spi_control,node_rfnvram_master,node_timer_bank,node_jtag_lock,node_crypto toneBlue
class node_firmware,node_fw_update,node_fw_state,node_fw_mailbox,node_fw_validation,node_fw_recovery toneAmber
class node_tests,node_mocks,node_testdata toneMint
```

## Components

### FPGA RTL

Top-level hardware designs, board-specific core logic, and FPGA IP blocks.

- [Build/Top](https://github.com/intel/pfr-wilson-city/tree/master/Makefile): build orchestration · Entry scripts and top-level FPGA configurations for alternate images. · `Makefile`
- [PFR top](https://github.com/intel/pfr-wilson-city/blob/master/pfr_top.sv): fpga image · Main protected platform firmware configuration. · `pfr_top.sv`
- [Non-PFR top](https://github.com/intel/pfr-wilson-city/blob/master/non_pfr_top.sv): fpga image · Alternate non-protected configuration. · `non_pfr_top.sv`
- [Recovery top](https://github.com/intel/pfr-wilson-city/blob/master/recovery_top.sv): fpga image · Minimal rescue configuration for degraded or compromised states. · `recovery_top.sv`
- [PFR system](https://github.com/intel/pfr-wilson-city/blob/master/src/pfr_sys/pfr_sys.qsys): qsys system · Main FPGA system integration for the protected path. · `src/pfr_sys/pfr_sys.qsys`
- [Recovery sys](https://github.com/intel/pfr-wilson-city/blob/master/src/recovery_sys/recovery_sys.qsys): qsys system · Reduced FPGA system used by the recovery path. · `src/recovery_sys/recovery_sys.qsys`
- [Wilson core](https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/Wilson_City_Main.v): board CPLD core · Board-specific protection and sequencing logic for Wilson City. · `src/core_cpld/wilson_city/Source/Wilson_City_Main.v`
- [Sequencing](https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/Pch_Seq.v): protection logic · Power, reset, thermal, and fault sequencing blocks. · `src/core_cpld/wilson_city/Source/Pch_Seq.v`
- [Fault control](https://github.com/intel/pfr-wilson-city/blob/master/src/core_cpld/wilson_city/Source/PFR_ByPass.v): protection logic · Bypass, power-good, prochot, and SmaRT handling. · `src/core_cpld/wilson_city/Source/PFR_ByPass.v`
- [Mailbox](https://github.com/intel/pfr-wilson-city/blob/master/src/smbus_mailbox/smbus_mailbox.sv): smbus interface · Host/management control path over SMBus/I2C. · `src/smbus_mailbox/smbus_mailbox.sv`
- [Relay gate](https://github.com/intel/pfr-wilson-city/blob/master/src/smbus_filtered_relay/smbus_filtered_relay.sv): bus filter · Gates or relays SMBus traffic based on protection state. · `src/smbus_filtered_relay/smbus_filtered_relay.sv`
- [SPI control](https://github.com/intel/pfr-wilson-city/blob/master/src/spi_control/spi_control.sv): flash control · Protected flash access, filtering, and command handling. · `src/spi_control/spi_control.sv`
- [RFNVRAM master](https://github.com/intel/pfr-wilson-city/blob/master/src/rfnvram_smbus_master/rfnvram_smbus_master.sv): i2c master · External retained-state access over SMBus/I2C. · `src/rfnvram_smbus_master/rfnvram_smbus_master.sv`
- [Timer bank](https://github.com/intel/pfr-wilson-city/blob/master/src/timer_bank/timer_bank.sv): timing block · Timing and timeout infrastructure for policy enforcement. · `src/timer_bank/timer_bank.sv`
- [JTAG lock](https://github.com/intel/pfr-wilson-city/blob/master/src/jtag_lock_controller/jtag_lock_controller.sv): debug control · Limits debug access to the platform. · `src/jtag_lock_controller/jtag_lock_controller.sv`
- [Crypto RTL](https://github.com/intel/pfr-wilson-city/blob/master/src/crypto/crypto256_top.sv): sha+ecdsa engine · Hardware SHA-256 and ECDSA-256 used by authentication and image validation. · `src/crypto/crypto256_top.sv`

### Embedded Firmware

Nios II policy, validation, and update orchestration.

- [Nios firmware](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/pfr_main.h): policy engine · Embedded orchestration layer for validation, update, recovery, and provisioning. · `fw/code/inc/pfr_main.h`
- [Update flow](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/firmware_update.h): image lifecycle · Capsule validation, decompression, flash programming, and recovery orchestration. · `fw/code/inc/firmware_update.h`
- [Security state](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/ufm.h): trust storage · UFM, RFNVRAM, keychain, and cancellation state management. · `fw/code/inc/ufm.h`
- [Mailbox policy](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/mailbox_utils.h): command handling · Firmware-side mailbox parsing and command routing. · `fw/code/inc/mailbox_utils.h`
- [Validation](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/authentication.h): security checks · Authentication, capsule, PFM, and flash validation pipeline. · `fw/code/inc/authentication.h`
- [Recovery logic](https://github.com/intel/pfr-wilson-city/blob/master/fw/code/inc/firmware_recovery.h): rescue flow · Recovery entry points for compromised or unavailable active images. · `fw/code/inc/firmware_recovery.h`

### Verification

C++ unit tests, mocks, and security scenario data.

- [Test suite](https://github.com/intel/pfr-wilson-city/blob/master/fw/test/main.cpp): C++ verification · Unit tests, flow tests, fuzz harnesses, and scenario coverage. · `fw/test/main.cpp`
- [Mocks](https://github.com/intel/pfr-wilson-city/blob/master/fw/test/system/system_mock.h): system mocks · SPI, SMBus, UFM, RFNVRAM, timer, crypto, and mailbox mocks. · `fw/test/system/system_mock.h`
- [Test data](https://github.com/intel/pfr-wilson-city/blob/master/fw/test/testdata/signed_capsule_pch.bin.gz): signed images · Signed capsules, PFMs, anti-rollback cases, key-cancellation certs, and recovery images. · `fw/test/testdata/signed_capsule_pch.bin.gz`

## Connections

- Build/Top → PFR top: builds · Build script and top-level artifacts produce the protected image.
- Build/Top → Non-PFR top: builds · Build script can produce a non-protected variant.
- Build/Top → Recovery top: builds · Build script can produce the recovery image.
- PFR top → PFR system: integrates · Main protected top wraps the primary system integration.
- Recovery top → Recovery sys: integrates · Recovery top wraps the minimal recovery system.
- PFR top → Wilson core: hosts · Protected top connects to the Wilson City core CPLD logic.
- Non-PFR top → Wilson core: hosts · Non-PFR top uses the same board core with different mode behavior.
- Recovery top → Wilson core: hosts · Recovery top retains the board-level control boundary.
- Wilson core → Sequencing: sequencing · Core logic sequences power, reset, and platform state.
- Wilson core → Fault control: faults · Core logic handles bypass, power-good, thermal, and fault responses.
- PFR system → Mailbox: exposes · Main system exposes management commands through the mailbox.
- PFR system → Relay gate: routes · System gates SMBus traffic through protection relay logic.
- PFR system → SPI control: controls · System mediates protected flash access through SPI control.
- PFR system → RFNVRAM master: reads/writes · System accesses retained security state over SMBus/I2C.
- PFR system → Timer bank: times · System uses timing and timeout infrastructure.
- PFR system → JTAG lock: guards · System restricts debug access through JTAG lock control.
- Validation → Crypto RTL: verifies · Firmware validation depends on hardware SHA/ECDSA.
- Nios firmware → Validation: uses · Firmware performs authentication and image structure checks.
- Nios firmware → Update flow: orchestrates · Firmware manages update, decompression, and flash programming.
- Nios firmware → Security state: persists · Firmware manages keys, UFM, and RFNVRAM-backed state.
- Nios firmware → Mailbox policy: handles · Firmware implements mailbox command policy.
- Nios firmware → Recovery logic: recovers · Firmware enters recovery flows on failure or compromise.
- Test suite → Mocks: stubs · Verification uses mocks for hardware-facing interfaces.
- Test suite → Test data: covers · Verification exercises signed-good, signed-bad, rollback, and recovery scenarios.
- Test suite → Nios firmware: validates · Test suite targets the firmware policy and lifecycle behavior.
- Test suite → Crypto RTL: validates · Tests cover crypto and authentication behavior.