Overview of PMU Firmware

Modules

1. ROM Services API
2. Reset Services API
3. BSP/Utility API

Inter-Processor Interrupts(IPI) Handling in PMUFW

IPI-1 is used for the callbacks from PMU to other masters and for communication initiated by PMUFW.

Currently, PM and EM modules use IPIs and this can be taken as reference for implementing custom modules which require IPI messaging.

Building PMU Firmware using Vitis

1. Open Vitis
2. Create a new application with File->New→Application Project...:
   1. Enter project name and click on Next. Eg: pmufw
      
   2. Select platform as "zcu102" from "Create a new platform from hardware (XSA)" tab options. Click on Next
      
   3. Now select the domain option as below and click on next
      1. CPU: psu_pmu_0
      2. OS: standalone
      3. Language: C
         
   4. Select "ZynqMP PMU Firmware" template from Templates list and click on Finish.
      
   5. After this, PMU project will be created. Right click on the project and select "Build Project" to build PMU Firmware.
3. Connect to the local board and test the connection. You should see a pop up showing that the connection was established successfully.
   

4. Connect to the COM port on the terminal to view the UART prints.

   IMPORTANT

   PMUFW uses psu_uart_0 as default STDOUT. This can be changed to other UARTs using the "Modify BSP Settings" dialogue.  To enable debug prints from PMUFW, add DEBUG_MODE and/or XPFW_DEBUG_DETAILED to the defined symbols list in build settings dialog.

   Additionally, Xilinx tools default to loading PMUFW from CBR in which case any early/init prints will not be seen.  See Using FSBL to load PMUFW for more details.

   Attention: When PMUFW logging is enabled, power management for the logging UART port will be disabled. Because of that, some system-wide power management operations will also be affected (e.g. suspend/resume operations may not work properly.) Therefore, PMUFW logging should be enabled only when necessary.

5. 
6. On XSCT Console, Connect to the board and Run the PMU firmware.
   
7. View the PMU firmware prints on the Terminal console

Debugging PMU FW using Vitis

1. Right click on the application to "Debug As" and click on “Debug Configurations”.
2. Right click on System Debugger and Click "New". You get a "New Configuration". Click on Debug.
   
3. You will now see the debug perspective and PMU firmware will run.
4. Place the break points to control the flow and rerun for debugging.

Loading PMU Firmware in JTAG boot mode

1. For Silicon v3.0 and above, PMU Microblaze is not visible in xsdb. Hence disable security gates to view PMU Microblaze
2. Load PMU FW and run
3. Load FSBL and run
4. Continue with U-Boot/Linux/user specific application

#Disable Security gates to view PMU MB target
targets -set -filter {name =~ "PSU"}
mwr 0xffca0038 0x1ff
after 500
 
#Load and run PMU FW
targets -set -filter {name =~ "MicroBlaze PMU"}
dow xpfw.elf
con
after 500
 
#Reset A53, load and run FSBL
targets -set -filter {name =~ "Cortex-A53 #0"}
rst -processor
dow fsbl_a53.elf
con
 
#Give FSBL time to run
after 5000
stop
 
#Other SW...
dow u-boot.elf
dow bl31.elf
con

Loading PMU Firmware in SD boot mode

Using FSBL to load PMU FW

1. We already have pmufw.elf with us. ( See building PMU FW at the top of this page)
2. Build an FSBL in the Vitis for A53. ( R5 can also be used)
3. Create a hello_world example for A53. Right Click on the "hello_world example" project and select "Create a boot image"
4. Create a new bif file. Choose
   1. Architecture : ZynqMP
   2. You will see A53 fsbl and hello_world example by default in partitions. We need pmufw too.
   3. Click on Add, then provide pmufw.elf path. Also Partition type: datafile, Destination device : PS, Destination CPU : PMU
   4. Click OK.
      
   5. After adding pmufw as partition. Click on pmufw partition and click UP bottom.
   6. Make sure partition order
      1. A53 fsbl
      2. pmufw
      3. hello world App
   7. Click on Create Image. You will see BOOT.bin created in a new folder "bootimage" in your example project.
   8. View the .BIF file to confirm the partition order.
      
   9. Now copy this BOOT.bin into SD card.
   10. Boot the ZCU102 board in SD boot mode. You can see the fsbl -> pmufw ->hello_world example prints in a sequence.

Using CBR to load PMU FW

1. To make CBR load pmufw, we just need to change the BOOT.bin boot partitions.
2. Now steps listed above (1 -> 3) are same.
3. Create a new bif file. Choose
   1. Architecture : ZynqMP
   2. You will see A53 fsbl and hello_world example by default in partitions. We need pmufw too.
   3. Click on Add, then provide pmufw.elf path. Also Partition type: pmu (loaded by bootrom).
   4. Click OK.
      
   5. Click on Create Image. You will see BOOT.bin created in a new folder "bootimage" in your example project.
   6. You can also view .BIF to confirm the partition order.
      
   7. Now copy this BOOT.bin into SD card.
   8. Boot the ZCU102 board in SD boot mode. You can see the pmufw -> fsbl ->hello_world example prints in a sequence.

PMU FW Build Flags

Power Management in PMU FW

PM Configuration Object

• List of masters available in the system
• All the slave nodes the master is currently using and current requirement of the master for the slave configuration
• All the slave nodes the master is allowed to use and default requirement of the master for the slave configuration
• For each power node, which masters are allowed to request/release/power down
• For each reset line, which masters are allowed to request the change of a reset line value
• Which shutdown mode the master is allowed to request and shutdown timeout value for the master
• Which masters are allowed to set configuration after the configuration is already set upon the system boot by the FSBL

PM Configuration Object Generation

1. The user specifies their custom PM framework Configuration using the PCW tool
2. PCW generates the HDF file
3. At build time, the HDF Parser parses the HDF file and insert the config object into the FSBL code

1. Open Vitis.
2. Click on File -> New -> Application Project. "New Project" window will appear
3. Enter project name and click on Next. Eg: test
4. Select platform as "zcu102" from "Create a new platform from hardware (XSA)" tab options. Click on Next
5. Now select the domain option as below and click on next
   
   1. CPU: psu_cortexa53_0
   2. OS: standalone
   3. Language: C
6. Select "Hello World" template application. Click Finish.
7. Click on "Modify BSP settings". BSP settings window appears as below. Select "xilpm" library and click on "Ok"
   
8. Now the BSP and application will get regenerated with xilpm library.
9. Now configuration object is generated as part of xilpm library. To verify the same, please check bsp -> psu_cortexa53_0 -> libsrc -> xilpm_v2_4 -> pm_cfg_obj.c

Initial Configuration at Boot

1. FSBL sends the config object to PMU with the Set Configuration API
2. PMU parses config object and configures
3. PMU powers off all nodes which are unused after all the masters have finished initialization

Error Handling in PMU FW

Error Management Hardware

Error Management in PMU Firmware

/**
 * Set action to be taken when specific error occurs
 *
 * @param ErrorId is the ID for error as defined in this file
 * @param ActionId is one of the actions defined in this file
 * @param ErrorHandler is the handler to be called in case custom action
 *
 * @return XST_SUCCESS if the action was successfully registerd
 *         XST_FAILURE if the registration fails
 */
s32 XPfw_EmSetAction(u8 ErrorId, u8 ActionId, XPfw_ErrorHandler_t ErrorHandler);
 

Example for Error Management (Custom Handler)

Add the OCM error handler to the xpfw_mod_em.c file as below:

/* OCM Uncorrectable Error Handler */ 
static void OcmErrHandler(u8 ErrorId) 
{ 
	XPfw_Printf(DEBUG_DETAILED, "EM: OCM ECC error detected\n"); 
	/* Clear the Error Status in OCM registers */ 
	XPfw_Write32(0xFF960004, BBIT(7)); 
}

And the OCM ECC error action is set to PS Error out by default. To change this, make the following change for EM_ERR_ID_OCM_ECC entry in ErrorTable structure in xpfw_error_manager.c file

Original:
[EM_ERR_ID_OCM_ECC] = { .Type = EM_ERR_TYPE_1, .RegMask = PMU_GLOBAL_ERROR_STATUS_1_OCM_ECC_MASK, .Action = EM_ACTION_PSERR, .Handler = NullHandler},

Modify the code to change the error action to "Interrupt to PMU":
[EM_ERR_ID_OCM_ECC] = { .Type = EM_ERR_TYPE_1, .RegMask = PMU_GLOBAL_ERROR_STATUS_1_OCM_ECC_MASK, .Action = EM_ACTION_CUSTOM, .Handler = OcmErrHandler},

;# Enable ECC UE interrupt in OCM_IEN
mwr -force 0xFF96000C [expr 1<<7]
 
;# Write to Fault Injection Data 0 Register OCM_FI_D0
;# Errors will be injected in the bits which are set, here its bit0, bit1
mwr -force 0xFF96004C 3
 
;# Enable ECC and Fault Injection
mwr -force 0xFF960014 1
;
# Clear the Count Register : OCM_FI_CNTR
mwr -force 0xFF960074 0
;# Now write data to OCM for the fault to be injected
# Since OCM does a RMW for 32-bit transactions, it should trigger error here
mwr -force 0xFFFE0000 0x1234
 
;# Read back to trigger error again
mrd -force 0xFFFE0000

Example for Error Management ( PoR as a response to Error)

To change OCM ECC error action to PoR, make the following change for EM_ERR_ID_OCM_ECC entry in ErrorTable structure in xpfw_error_manager.c file

Original:
[EM_ERR_ID_OCM_ECC] = { .Type = EM_ERR_TYPE_1, .RegMask = PMU_GLOBAL_ERROR_STATUS_1_OCM_ECC_MASK, .Action = EM_ACTION_PSERR, .Handler = NullHandler},

Modify the code to change the error action to "Power on Reset":
[EM_ERR_ID_OCM_ECC] = { .Type = EM_ERR_TYPE_1, .RegMask = PMU_GLOBAL_ERROR_STATUS_1_OCM_ECC_MASK, .Action = EM_ACTION_POR, .Handler = NullHandler},

Adding a Custom Module

Creating a New Module

PmModPtr = XPfw_CoreCreateMod();
(void)XPfw_CoreSetCfgHandler(PmModPtr, PmCfgInit);
(void)XPfw_CoreSetEventHandler(PmModPtr, PmEventHandler);
(void)XPfw_CoreSetIpiHandler(PmModPtr, PmIpiHandler,0U)

Adding a Task to Scheduler

void TaskPrintMsg(void)
{
    xil_printf("Task has been triggered\r\n");
}
 

Status = XPfw_CoreScheduleTask(TaskModPtr, 500U, TaskPrintMsg);
if(XST_SUCCESS == Status) {
    xil_printf("Task has been added successfully !\r\n");
}
else {
    xil_printf(Ërror: Failed to add Task.!\r\n");
}
 

Registering for an Event

Status = XPfw_CoreRegisterEvent(ModPtr,XPFW_EV_RTC_SECONDS);

Example of an EventHandler

void RtcEventHandler(const XPfw_Module_t *ModPtr, u32 EventId)
{
    xil_printf("MOD%d:EVENTID: %d\r\n", ModPtr->ModId, EventId);
    if(XPFW_EV_RTC_SECONDS == EventId){
            /* Ack the Int in RTC Module */
            Xil_Out32(RTC_RTC_INT_STATUS,1U);
            xil_printf("RTC: %d \r\n", Xil_In32(RTC_CURRENT_TIME));
    }
}

PMU Firmware Memory Footprint

• PM and FPGA modules are enabled by default. FPGA block in PMU Firmware does the xilfpga and xilsecure functionality which performs loading of bitstream to PL, loading of secure image to memory and reading FPGA status. FPGA block does not have a separate build flag for itself and is part of PM module.
• Error Management and Restart modules are not enabled by default

Examples to enable/disable modules

1. PM module is enabled by default with ENABLE_PM build flag. This build flag is defined in <PMU Firmware Application>/src/xpfw_config.h file. To disable PM Module, user need to make changes to xpfw_config.h file by removing/commenting defined ENABLE_PM flag.
2. All other build flags can be enabled by following the below steps.
   1. Right click on the PMU Firmware project and select "C/C++ Build Settings" option. Properties window appears
   2. Select "Settings" from "C/C++ Build" options. In "Tool Settings" tab, select "Symbols" from "Microblaze gcc compiler" option
   3. Click on "Add" under "Defined symbols (-D)"
   4. Enter flag name to define and click "Ok"
      
   5. Again click "Ok" on properties window and the application will start building with the new compile flags defined

Registers reserved for PMU Firmware

1. 0xFFD80034 (PMU_GLOBAL_GLOBAL_GEN_STORAGE2) → Since 2018.1 if POS is enabled, FSBL waits till PMU has finished resuming by polling this register. Users are free to use this register after reset so it can still be considered as "reserved for customers".
2. 0xFFD80038 (PMU_GLOBAL_GLOBAL_GEN_STORAGE3) → Since 2018.1 if POS is enabled, PMU waits till FSBL has finished reading the boot type. This additional handshake step is required in boot scenarios where FSBL is started by CSU. PFW must wait for CSU to trigger FSBL start otherwise there may be race condition where PFW is trying to restore state of processor as part of resume from Power Off Suspend sequence while CSU is trying to run FSBL on that same processor. Users are free to use this register after reset so it can still be considered as "reserved for customers".
3. 0xFFD80040 (PMU_GLOBAL_GLOBAL_GEN_STORAGE4 - bit 0) → This register bit needs to be written by upper layer APU applications. So that, in case of FPD WDT error (and when ENABLE_RECOVERY and CHECK_HEALTHY_BOOT macros are defined), PMU checks this register to find out if previous boot was successful and does subsystem restart only if last boot was successful.
4. 0xFFD80040 (PMU_GLOBAL_GLOBAL_GEN_STORAGE4 - bits 1 and 2) → Since 2018.3, these bits are used to know the status of RPU 0 and RPU 1 usage which will be updated by FSBL. Based on this information, PMU will decide whether to shutdown the unused RPU cores or not.
5. 0xFFD80040 (PMU_GLOBAL_GLOBAL_GEN_STORAGE4 - bits 3 and 4) → Since 2018.3, these bits are used to set the restart scope to ATF in case of WDT restart.
6. 0XFFD80040 (PMU_GLOBAL_GLOBAL_GEN_STORAGE4 - bit 16) → Written by PMU Firmware, FSBL uses this register bit to know if reset is APU only reset.
7. 0XFFD80044 (PMU_GLOBAL_GLOBAL_GEN_STORAGE5 - bit 0) → Written by FSBL, PMU Firmware uses this register to know if FSBL has completed its execution. Since 2018.1, this check is performed to initialize and start the CSU WDT timer when ENABLE_WDT macro is defined.
8. 0XFFD80044 (PMU_GLOBAL_GLOBAL_GEN_STORAGE5 - bits 1 and 2) → Written by FSBL. PMU Firmware uses these bits to know if FSBL is running on which processor. 01: APU, 10: RPU0, 11: RPU LS
9. 0xFFD80044 (PMU_GLOBAL_GLOBAL_GEN_STORAGE5 - bits 16 to 23) → Since 2018.3, XilFPGA library in PMU uses these bits to store the PL state to know whether secure bit-stream or non-secure bit-stream or no bit-stream loaded. This information is used by XilFPGA Readback feature to dis-allow readback in case secure bit-stream is loaded.
10. 0xFFD8006C (PMU_GLOBAL_PERS_GLOBAL_GEN_STORAGE7 - bit 3) → Since 2018.3, PMU is using this bit to indicate FSBL whether DDR is in self-refresh mode or not. PMU will set this bit if DDR is in self-refresh during warm-restart and clears after the restart.

And 0xFFD8004C (PMU_GLOBAL_GLOBAL_GEN_STORAGE7) is used by PMU_ROM. This register is used in case we encounter problems with the PL Power Up routine in which ROM does not wait long enough for the PL to come out of reset. The time ROM waits can be extended by increasing the value of this register.

What's new in 2019.2 release

Following are the new features added in PMU Firmware in 2019.2 release:

1. Change power state of power domain or island only if it is powered up by checking PWR_STATUS register
2. Change WDT timeout when performing secure operations which take more time
3. Added power down permission check for processor and PLL nodes in PmForcePowerDown()
4. Added support for RPU only subsystem restart case

What's new in 2019.1 release

Following are the new features added in PMU Firmware in 2019.1 release:

1. Idle nodes only once even if they are assigned to multiple masters
2. Add support to idle and reset all twelve TTCs
3. Support for APU only reset even if secure bitstream loading via OCM feature is executed
4. Updates to XilFPGA APIs to support latest 5.0 version
5. Add checksum support for IPI messages
6. Add permission check for modifying error actions over IPI
7. Bypass DDR related code if DDR is not present in the design
8. Register handler and trigger FW error when Assert occurs
9. Add hook for custom module in PMU Firmware
10. Add handler for EMIO get reset status
11. Add PMU RAM ECC error injection STL during PMU startup
12. Add check for number of users for vpll
13. Add support for Ultra96 power button

What's new in 2018.3 release

1. PMU Firmware support for PL Configuration Readback
2. PMU Firmware support for AES encryption and decryption
3. Put DDR in self refresh before warm-restart
4. Implementation of clock EEMI APIs
5. Addition of CSU/PMU global register access via MMIO calls
6. Support to set restart scope during WDT restart
7. PMU Firmware support for eFUSE access
8. Implementation of pin mux functionality in PMU Firmware

What's new in 2018.2 release

Related Links

• PetaLinux Yocto Tips
• FSBL
• Zynq UltraScale Plus MPSoC - IPI Messaging Example
• Zynq UltraScale Plus MPSoC - PL Temperature and Voltage Monitor
• Zynq UltraScale Plus MPSoC - PS Temperature and Voltage Monitor