PolarFire SoC¶

Important

This documentation is deprecated and it’s not recommended to be used on new projects.

Visit https://mi-v-ecosystem.github.io/SoftConsole-Documentation/ instead.

PolarFire SoC boot mode programming support in SoftConsole¶

Required tools¶

SoftConsole v2021.1
Libero SoC v2021.1 or Programming and Debug Tools v2021.1

PolarFire SoC Boot Modes¶

PolarFire SoC supports four boot modes which determine what happens when the device is powered on/reset. In particular, what exactly the RISC-V multi-core CPU Core Complex part of PolarFire SoC’s Microcontroller Subsystem (MSS) does out of reset:

Boot mode 0 “idle boot”: boots and simply waits for a debugger connection.
Boot mode 1 “non-secure boot”: boots and executes a program stored in eNVM which has been linked for storage in and execution from eNVM.
Boot mode 2 “user secure boot”: boots, checks the integrity of an encrypted and/or authenticated program stored in sNVM and, if it is correct, copies it to LIM (Loosely Integrated Memory) RAM and starts executing it from there. The program executed may be a secure boot loader implemented by the user. The program is linked for execution from LIM.
Boot mode 3 “factory secure boot”: boots, verifies a program image stored in eNVM using an Elliptic Curve Digital Signature Algorithm (ECDSA) and, if correct, starts executing the program from eNVM. The program is linked for storage in and execution from eNVM.

Refer to the PolarFire SoC documentation for more detailed information about these boot modes.

https://www.microsemi.com/product-directory/soc-fpgas/5498-polarfire-soc-fpga#documentation

fpgenprog¶

fpgenprog is the tool provided by Libero SoC and Programming and Debug Tools for programming PolarFire SoC boot modes and storing the associated programs in NVM (eNVM or sNVM). fpgenprog calls other programming file generation and programming tools (for example FlashPro Express) in order to perform boot mode programming. fpgenprog and related tools are NOT bundled with SoftConsole so Libero SoC or Programming and Debug Tools must be installed in order to make them available to SoftConsole.

Refer to the website for more information about these tools:

Libero SoC v12.0 and later: https://www.microsemi.com/product-directory/design-resources/1750-libero-soc

Programming and Debug Tools: https://www.microsemi.com/product-directory/dev-tools/5592-programming-and-debug#downloads

By default Libero SoC and Programming and Debug tools v2021.1 install into the following locations:

Windows
- C:\Microsemi\Libero_SoC_v2021.1
- C:\Microsemi\Program_Debug_v2021.1
Linux
- /usr/local/microsemi/Libero_SoC_v2021.1
- /usr/local/microsemi/Program_Debug_v2021.1

So the possible default locations for the fpgenprog tool are:

Windows
- C:\Microsemi\Libero_SoC_v2021.1\Designer\bin64\fpgenprog.exe
- C:\Microsemi\Program_Debug_v2021.1\Program_Debug_Tool\bin64\fpgenprog.exe
Linux
- /usr/local/microsemi/Libero_SoC_v2021.1/Designer/bin64/fpgenprog
- /usr/local/microsemi/Program_Debug_v2021.1/Program_Debug_Tool/bin64/fpgenprog

Note

These are the default locations and the actual location will differ if a non-default install location is specified at install time.

mpfsBootmodeProgrammer¶

In order to simplify boot mode programming, SoftConsole bundles the mpfsBootmodeProgrammer Java program utility:

<softconsole-install-dir>/extras/mpfs/mpfsBootmodeProgrammer.jar

mpfsBootmodeProgrammer takes care of the details of converting a program executable ELF file for use with the selected boot mode and calling fpgenprog to program target with the relevant boot mode data and store the boot program image in NVM (eNVM or sNVM).

Full sources for mpfsBootmodeProgrammer and instructions on how to build it are also bundled with SoftConsole (in the same folder as the JAR file).

Boot mode programming external launch configurations¶

The SoftConsole workspace comes preconfigured with four external tool launch configurations, one for each of the four boot modes, which are accessible from the External Tools toolbar button or Main Menu > External Tools.

PolarFire SoC program idle boot mode 0
PolarFire SoC program non-secure boot mode 1
PolarFire SoC program user secure boot mode 2
PolarFire SoC program factory secure boot mode 3

Each of these external tool launch configurations passes a default set of command line options to the mpfsBootmodeProgrammer utility for the relevant boot mode. These command line options can be adjusted if needed. See below for the mpfsBootmodeProgrammer usage/help text which describes all options.

By default, with the exception of boot mode 0, these external tool launch use, as their working directory, the selected project’s active build configuration directory and attempts to process the ELF file found there.

The project to be used for boot mode programming must be selected in the Project Explorer and the relevant build configuration must be built and the ELF file exist in order for the boot mode 1, 2 and 3 external tool launch configurations to work.

Boot mode 0 does not require a project to be selected/built and, by default, works in the <SoftConsole-install-dir>/extras/mpfs/bootmode0 directory.

A project can be selected in the Project Explorer by clicking on any folder in the project hierarchy. If no project is selected then a message of the following form will be displayed:

Problem Occurred
'Launching PolarFire SoC program ... boot mode ...' has encountered a problem.
Variable references empty selection '${project_loc}'

The active build configuration can be selected in SoftConsole in different ways including by using the “Hammer” build toolbar button dropdown list of available build configurations or by:

$digraph { graph [rankdir="LR", ranksep=.01, bgcolor=transparent]; node [fontname="Verdana", fontsize="9", shape="rectangle", width=.1, height=.2, margin=".04,.01", style=filled, fillcolor=white]; edge [arrowsize=.7]; "Right click on <your_project> in the Project Explorer" -> "Build Configurations" -> "Set Active" -> "<build-configuration>" }$

If the selected build configuration’s directory does not exist then a message of the following form will be displayed:

Problem Occurred
'Launching PolarFire SoC program ... boot mode ...' has encountered a problem.
The working directory ... does not exist for the external tool named PolarFire SoC program ... boot mode ...

If no ELF file exists or other validation checks fail then the mpfsBootmodeProgrammer utility will emit an appropriate warning or error message to the output log.

mpfsBootmodeProgrammer always generated a <workdir>/bootmode<n>/debugLog.txt log file which contains detailed information about the tasks carried out.

Boot program link requirements¶

A boot mode 1 or 3 program must be linked for storage in and execution from PolarFire SoC’s eNVM. The program can be linked for anywhere in the eNVM address range 0x20220100-0x2023FFFF (128KiB - 256 bytes). Because an eNVM page (256 bytes) is required before the program image in order to store the boot mode 1 header or boot mode 3 SBIC (Secure Boot Image Certificate) the program cannot be linked for eNVM page 0 = address 0x20220000. The linker script used to link the program should define eNVM as follows:

/* Boot modes 1 & 3 need an eNVM page before the program image so start eNVM at page 1 not 0 */
eNVM (rx) : ORIGIN = 0x20220100, LENGTH = 128k-256

Boot mode 1/3 programs must also be linked on an eNVM 256 byte page boundary.

SoftConsole/mpfsBootmodeProgrammer cater for boot mode 1/3 programs linked at eNVM pages/addresses higher than 1/0x20220100 but Libero only supports those that are linked for 0x20220100.

Boot mode 2 programs must be linked for LIM (Loosely Integrated Memory) RAM at address range 0x08000000-0x081dffff (1920KiB) and aligned to a 32-bit word address. The program is stored in PolarFire SoC’s sNVM. The theoretical maximum sNVM storage space available is < 56KiB. The actual sNVM storage space available and sNVM start page will be dictated by the Libero designed with which the target is programmed. For example, depending on the MSS configuration and Libero design contents some sNVM clients will be automatically generated precluding the relevant pages from being used for a boot mode 2 program image.

Important

It is critical, when programming boot mode 2 from SoftConsole, that the available sNVM space and relevant start page are checked in the Libero project first. Not doing so could cause corruption of sNVM content required for correct functioning of the target design.

mpfsBootmodeProgrammer does validation checking on the boot program ELF file to ensure that it matches the selected boot mode requirements.

Generated artifacts¶

mpfsBootmodeProgrammer works in the specified workdir and generates artifacts into a bootmodeN (0 <= N <= 3) directory below this.

By default, the preconfigured boot mode 0 external tool launch configuration works in <SoftConsole-install-dir>/extras/mpfs and generates aretefacts into the bootmode0 directory below this.

By default, the preconfigured boot mode 1-3 external tool launch configurations use the selected project’s active build configuration directory as the workdir and generates artifacts into a bootmodeN (1 <= N <= 3) directory below this.

mpfsBootmodeProgrammer generates a <workdir>/bootmodeN/debugLog.txt (0 <= N <= 3) log file which can be useful for checking what operations were carried out especially in the case of a programming failure.

For boot modes 1-3 mpfsBootmodeProgrammer generates the boot mode program image Intel Hex file that can be used in Libero:

digraph {
graph [rankdir="LR", ranksep=.01, bgcolor=transparent];
node [fontname="Verdana", fontsize="9", shape="rectangle", width=.1, height=.2, margin=".04,.01", style=filled, fillcolor=white];
edge [arrowsize=.7];
"Design Flow" -> "Program Design" -> "Configure Design Initialization Data and Memories" -> "eNVM/sNVM configurators"
}

The name of this file includes

the ELF file basename - for example “mpfs-blinky” for “mpfs-blinky.elf”
“bmN” (1 <= N <= 3) indicating the boot mode
“pM” (where M is an NVM page number) indicating the NVM (eNVM or sNVM) page at which the boot mode program image (including prepended “header” data) is stored.

For boot mode 2 the filename also contains ap or ac indicating whether the boot program is stored in authenticated plaintext or authenticated ciphertext sNVM pages respectively.

Examples of boot mode program image Intel Hex file names include:

Boot mode 1: mpfs-blinky-bm1-p0.hex
Boot mode 2: mpfs-blinky-bm2-ap-p20.hex (authenticated plaintext)
Boot mode 2: mpfs-blinky-bm2-ac-p32.hex (authenticated encrypted ciphertext)
Boot mode 3: mpfs-blinky-bm3-p0.hex

For boot mode 2 the USK (User sNVM/Secret Key) used is stored in <elf-file-basename>-bm2-usk.txt. This or another USK is required when configuring the boot mode 2 program image sNVM client in Libero.

For boot mode 3 the ECC (Elliptic Curve Cryptography) public key x and y values are stored in <elf-file-basename>-bm3-public-key-xy.txt and these details are required when configuring the boot mode 3 program image eNVM client in Libero.

Troubleshooting¶

If boot mode programming fails then the Console log should indicate the nature of the problem. If necessary also check the debugLog.txt log file that mpfsBootmodeProgrammer generates for more details.

If mpfsBootmodeProgrammer cannot find fpgenprog or the required RISC-V GCC/binutils tools then check that the FPGENPROG and SC_INSTALL_DIR environment variables are configured correctly. Both environment variables are set from the softconsole.{cmd|sh} start script but the FPGENPROG variable may require adjustment depending on where Libero SoC or Programming and Debug Tools are installed. This can be set by configuring the variable in the OS environment, by editing the softconsole.{cmd|sh} script itself or in the Environment tab of the boot mode programming external tool launch configurations.

If boot mode programming succeeds but the program does not execute as expected from reset then check that the program itself executes correctly under debug from RAM (LIM) with the same optimization and debug options.

If boot mode 2 is programmed from Libero, necessitating the enabling of security options including debug locking, then debugging and boot mode programming from SoftConsole will not be possible. Boot mode programming will fail with messages similar to those below. Debugging and boot mode programming will only be possible by erasing the device and reprogramming it with security disabled.

Note

The boot mode 2 can be programmed from SoftConsole only with security disabled and only from Libero with security enabled.

Programmer '1C21ED74' : JTAG TCK frequency = 4 MHz
Error: Failed to read data from eFP6 USB buffer. Err = -1
Error: Failed to send data to eFP6. Err = -1
Error: eFP6 connection failed.
Error: programmer '1C21ED74' : device 'MPFS250T_ES' : Executing action PROGRAM FAILED.
Error: Failed to send data to eFP6. Err = -1
Error: programmer '1C21ED74' : Error: eFP6 connection failed.
Error: Failed to send data to eFP6. Err = -1
Error: programmer '1C21ED74' : Error: Failed to disable eFP6 programmer
Error: programmer '1C21ED74' : Chain programming FAILED.
Chain Programming Finished: Mon Mar 1 10:49:54 2021 (Elapsed time 00:00:06)
Error: Failed to run Action.
Exported log file D:\sandbox\icicle-kit\MPFS_ICICLE_eMMC\designer\MPFS_ICICLE_eMMC\MPFS_ICICLE_eMMC_fp\MPFS_ICICLE_eMMC.log.
Error: The command 'run_selected_actions' failed.
Error: Failure when executing Tcl script. [ Line 5 ]
Error: The Execute Script command failed.

Known issues/limitations¶

The following known issues and limitations will be addressed in a future release.

There is no facility to select a specific FlashPro programmer when there is more than one connected. For best results ensure that only one FlashPro programmer is connected.

Boot mode 0 overwrites page 0 of eNVM because the boot mode cannot be changed without at least one NVM (eNVM or sNVM) client being specified at the moment.

mpfsBootmodeProgrammer does not initialize or reset the SMK (sNVM Master Key) and assumes that this has been previously configured appropriately. If this is not the case (for example, for a new device) then an attempt to program boot mode 2 from SoftConsole will result in messages similar to the following and the SMK will need to be configured/initialized from Libero by programming an appropriate design that causes the SMK to be (re)generated:

programmer 'S201QVSUE' : device 'target' : EXPORT BITS component bitstream digest[256] = 25295f0d1d592a90b333e26e85149708208e9f8e8bc18f6c77bd62f8ad7a6866
programmer 'S201QVSUE' : device 'target' : Programming Error.
programmer 'S201QVSUE' : device 'target' : Bitstream or data is corrupted or noisy.
programmer 'S201QVSUE' : device 'target' : componentNo: 3
programmer 'S201QVSUE' : device 'target' : blockNo: 155
programmer 'S201QVSUE' : device 'target' : EXPORT DATA_STATUS_RESULT: [64] = 0002000900008407
programmer 'S201QVSUE' : device 'target' : EXPORT READ_DEBUG_INFO[752] = >  0000000000030003017f00000080040001000000000000000000000000000000001a0000001e000000db000003000002000900008400fc5e52012dd402010000000000000000000000000084071309c709c709c700280028002824000000
programmer 'S201QVSUE' : device 'target' : EXPORT ERROR_CODE[16] = 801f
programmer 'S201QVSUE' : device 'target' : ===================================================================================
programmer 'S201QVSUE' : device 'target' : EXPORT DSN[128] = 4883b6958cf34738ba77807d1bb91b7f
programmer 'S201QVSUE' : device 'target' : ===================================================================================
programmer 'S201QVSUE' : device 'target' : Finished: Sat Mar 20 01:45:56 2021 (Elapsed time 00:00:01)
Error: [80609294]:  programmer 'S201QVSUE' : device 'target' : Executing action PROGRAM FAILED, EXIT -22, refer to FlashPro online help for details.
@@ACTIVITY 101
Error:  programmer 'S201QVSUE' : Chain programming FAILED.

Elliptic Curve Cryptography private and public keys for boot mode 3 are automatically generated and there is no facility to pass an external key file yet.

Note

Support for “advanced” options such as U_MSS_BOOTCFG:U_MSS_REVOCATION_ENABLE, SBIC:OPTIONS[7:0], SBIC:VERSION and SBIC:DSN is not yet available.

Warning

Boot mode programming assumes that the full capacity of eNVM and sNVM is available for storing the boot loader program and does not have any knowledge of any eNVM/sNVM clients configured via other tools (e.g. PolarFire SoC MSS Configurator, Libero SoC etc.). It is important, especially for boot mode 2, to check that only unused/available NVM is used from SoftConsole when programming boot modes.

mpfsBootmodeProgrammer assumes that the base address of the program image is identical to the program start address (_start) which is true when using the PolarFire SoC HAL example linker scripts but may not be so in the general case.

mpfsBootmodeProgrammer usage/help¶

10:18:44 INFO  - mpfsBootmodeProgrammer v3.2 started.
Usage: java -jar mpfsBootmodeProgrammer.jar [--workdir directory] [--die device-die] [--package device-package] [--bootmode mode] [--snvm_page page] [--usk key] [--encrypt] [--dryrun] [--verify] [--help] [elf-file]

  --workdir directory
    Description:
      Working directory
    Default if not specified:
      Current working directory

  --die device-die
    Description:
      device-die is the target device die designator
    Allowed values:
      MPFS025T
      MPFS095T
      MPFS160T
      MPFS250T
      MPFS460T
      MPFS025T_ES
      MPFS095T_ES
      MPFS160T_ES
      MPFS250T_ES
      MPFS460T_ES
    Default if not specified:
      MPFS250T_ES

  --package device-package
    Description:
      device-package is the target device package designator
    Allowed values:
      FCG1152
      FCSG325
      FCSG536
      FCVG484
      FCVG784
    Default if not specified:
      FCVG484

  --bootmode mode
    Description:
      mode is the boot mode to be programmed
      0 = idle boot
      1 = non-secure boot from eNVM
      2 = user secure boot from sNVM
      3 = factory secure boot from eNVM
    Allowed values:
      0 to 3
    Default if not specified:
      0 = idle boot 

  --snvm_page page
    Description:
      For boot mode 2 only, page is the sNVM page number starting from which the program image will be stored
    Allowed values:
      0 to 211
    Default if not specified:
      0

  --usk key
    Description:
      For boot mode 2 only, key is the User sNVM Key specified as a 12 byte hex string; if 0 then a random USK is generated and used
    Allowed values:
      any 12 byte hex string or 0, for example: 0x0b841d7a16f5542cda541eeb or 0b841d7a16f5542cda541eeb or 0
    Default if not specified:
      0

  --encrypt
    Description:
      For boot mode 2 only, use sNVM encryption to store the image as authenticated ciphertext rather than as authenticated plaintext

  --dryrun
    Description:
      Perform all tasks except target programming/verification

  --verify
    Description:
      Verify the target after programming

  --help
    Description:
      Print this help

  elf-file
    Description:
      Boot program ELF file
    Allowed values:
      Any valid ELF file matching the selected boot mode linkage requirements
    Default if not specified:
      If not specified then the working directory is searched for an ELF file

fpgenprog fails to program the board¶

Sometimes user can experience program failures even when running PolarFire SoC program idle boot mode 0 external launcher:

Warning:  Unable to find file: 'C:\Microchip\SoftConsole-v2021.1\extras\mpfs\bootmode0\fpgenprogProject\target.pdb'.
Warning: [80609481]:  Using local backup copy: 'C:\Microchip\SoftConsole-v2021.1\extras\mpfs\bootmode0\fpgenprogProject\proj_fp\projectData\target.pdb'.
PDB file 'C:\Microchip\SoftConsole-v2021.1\extras\mpfs\bootmode0\fpgenprogProject\proj_fp\projectData\target.pdb' has been loaded successfully.
DESIGN : TOP;  CHECKSUM : 0000;  PDB_VERSION : 1.9
===============================================================
Programmer: Embedded FP6 '082D3559' : Version = EF9B
===============================================================
programmer '082D3559' : Embedded FlashPro6
Opened 'C:\Microchip\SoftConsole-v2021.1\extras\mpfs\bootmode0\fpgenprogProject\proj_fp\proj_fp.pro'
The 'open_project' command succeeded.
Info:  Programming is already enabled for device 'target'.
The 'enable_device' command succeeded.
PPD file 'C:/Microchip/SoftConsole-v2021.1/extras/mpfs/bootmode0/fpgenprogProject/proj_fp/target.ppd' has been loaded successfully.
DESIGN : TOP;  CHECKSUM : 0000;  PDB_VERSION : 1.0
The 'set_programming_file' command succeeded.
The 'set_programming_action' command succeeded.
programmer '082D3559' : Scan Chain...
programmer '082D3559' : Check Chain...
programmer '082D3559' : Scan and Check Chain PASSED.
@@ACTIVITY 1
programmer '082D3559' : device 'target' : Executing action PROGRAM
Performing FPGA action. Please wait...
eFP6 acceleration mode enabled with PPD file. Please wait...
@@ACTIVITY 2
 
16:45:46 ERROR - Running the fpgenprog.exe PROGRAM action failed.

To see more verbose errors it’s good to run the last fpgenprog invocation again from the command line. To see the log file, for example for boot mode 0 it’s in the <SC_INSTALL_DIR>/extras/mpfs/bootmode0/debugLog.txt. The last fpgenprog invocation should look similar like to: c:\microchip\libero\Program_Debug_v2021.2\Program_Debug_Tool\bin64\fpgenprog.exe run_action --location c:/microchip/SoftConsole-2021.1/extras\mpfs/bootmode0/fpgenprogProject --action PROGRAM

If invoking the fpgenprog from command line shows the following error: Error: Failed to run action. Return code = -1073741819. Then contact support for Libero or Program and Debug tolls as this issue is outside SoftConsole’s scope.