intel/pfr-wilson-city

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.