Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added notes regarding load ordering and prints

...

Overview of PMU Firmware

The Platform Management Unit (PMU) in Zynq MPSoC has a Microblaze with 32 KB of ROM and 128 KB of RAM. The ROM is pre-loaded with PMU Boot ROM (PBR) which performs pre-boot tasks and enters a service mode. For more details on PMU, PBR and PMUFW load sequence, refer to Platform Management Unit (Chapter-6) in Zynq MPSoC TRM (UG1085). PMU RAM can be loaded with a firmware (PMU Firmware) at run-time and can be used to extend or customize the functionality of PMU. Some part of the RAM is reserved for PBR, leaving around 125.7 KB for PMU Firmware.

Here is the memory layout of PMU RAM:

The PMU Firmware provided in Vitis, comes with a default linker script which aligns with this memory layout and there is no specific customization required from user.

Modules

PMU Firmware is designed to be modular and enables adding new functionality in the form of modules. Each functionally distinct feature is designed in as a module, so that PMUFW can be configured to include only the required functionality for a user application. This type of modular design allows easy addition of new features and as well as optimizes memory footprint by disabling unused modules.

All the common functions that may be required by the modules are organized as separate libraries in PMUFW with APIs clearly specified. The included APIs in PMU Firmware are given below:
  1. ROM Services API
  2. Reset Services API
  3. BSP/Utility API

These APIs can be used by the modules in PMUFW to perform the specified actions as required.

Each module can be provided with three handlers which are called in during the respective phases as described below:
Module HandlerPurposeAPI for Registering the Handlerexecution context
InitCalled during the init of the core to configure the module, register for events or add scheduler tasks. This can be used to load the configuration data into the module if required.XPfw_CoreSetCfgHandler(const XPfw_Module_t *ModPtr, XPfwModCfgInitHandler_t CfgHandler);StartUp
Event HandlerCalled when an event occurs (module should have registered for this event, preferably during the init phaseXPfw_CoreSetEventHandler(const XPfw_Module_t *ModPtr, XPfwModEventHandler_t EventHandler);Interrupt
IPI HandlerCalled when an IPI message with respective module-id arrivesXPfw_CoreSetIpiHandler(const XPfw_Module_t *ModPtr, XPfwModIpiHandler_t IpiHandler, u16 IpiId);Interrupt
PMUFW has a default set of modules which address most of the common use case for Power Management and Error Management. these modules can be taken as references for implementation of custom modules.

Inter-Processor Interrupts(IPI) Handling in PMUFW

PMU has 4 Inter-Processor Interrupts(IPI) assigned to it and one set of buffers. By default, PMUFW uses IPI-0 and associated buffers for all message exchange with other processors on the SoC. PMUFW uses IPI driver to send and receive messages. An IPI manager layer is implemented over the driver and it takes care of dispatching the IPI message to the registered module handlers based on IPI ID in the first word of the message. The message format for IPI is given below:
WordContentDescription
0Header<target_module_id, api_id>
1PAYLOADModule dependent payload
2
3
4
5
6RESERVEDRESERVED – for future use
7Checksum

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


Info

For tips configuring PMU firmware builds in PetaLinux see PetaLinux Yocto Tips.


  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.

    Note:
    -
    Info
    titleIMPORTANT

    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

    .- [Important] When

    .

    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. On XSCT Console, Connect to the board and Run the PMU firmware.
  6. View the PMU firmware prints on the Terminal console

Debugging PMU FW using Vitis


Info

PMU FW will be built with -Os and LTO optimizations by default.


If the user need to disable the optimization (for debugging), two things need to be done:
Since removing optimization results in increase of code size and can result in not being able to build PMU FW, some of the features that the user don’t use, need to be disabled by removing build flags from project settings. And to further disable some features, it can be disabled in xpfw_config.h file of PMU FW
To disable/modify Optimizations, below changes need to be done:
PMU FW application: In "Miscellaneous" section, need to remove/modify highlighted options below:

...


Info

Note: When PMUFW is loaded in a non-JTAG Boot mode on a 1.0 Silicon, an error message "Error: Unhandled IPI received" may be logged by PMUFW at startup, which can be safely ignored. This is due to the IPI0 ISR not being cleared by PMU ROM which is fixed in 2.0 and later versions of Silicon.


PMU Firmware can be loaded by either FSBL or by CSU BootROM (CBR). Both these flows are supported by Xilinx. PMU Firmware loading by CBR will be needed in the cases where the customer board has an onboard regulator that needs to be programmed to bring up the boot processor's power rail. Loading PMU Firmware using FSBL has these benefits: (i) Possible quick boot time, when PMUFW is loaded after bit-stream, (ii) In use cases where the user want two BIN files - stable and up-gradable, PMUFW can be part of the up-gradable (by FSBL) image.

Using FSBL to load PMU FW

Info

Note: This method of loadind PMUFW (versus loading by CBR) is necessary to see any early prints issued by PMUFW during initialization.


  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

Info

Note: When PMUFW is loaded by CBR, it is executed prior to FSBL. So the MIOs, Clocks and other initializations are not done at this point and this means that the PMUFW banner and other prints may not be seen prior to FSBL.
Post FSBL execution, the PMUFW prints can be seen as usual.


  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

FlagDescriptionRequires these flags/build options to be enabledDefault setting
XPFW_DEBUG_DETAILED

Enables detailed debug prints in PMU Firmware

This feature is supported in 2017.3 release and above

Additionally, see Using FSBL to load PMUFW regarding necessary configuration to see early prints during initialization.


Disabled
PM_LOG_LEVEL

This enables print based debug functions for PM module. Possible values are:

  • 1: Alerts
  • 2: Errors
  • 3: Warnings
  • 4: Information

Higher numbers include the debug scope of lower number, i.e: enabling 3 (warnings) also enables 1 (alerts) and 2 (errors)

Additionally, see Using FSBL to load PMUFW regarding necessary configuration to see early prints during initialization.


Disabled
ENABLE_EMEnables Error Management ModuleENABLE_SCHEDULERDisabled
ENABLE_ESCALATIONEnables escalation of sub-system restart to SRST/PS-Only if the first restart attempt failsENABLE_RECOVERYDisabled
ENABLE_RECOVERYEnables WDT based restart of APU sub-systemENABLE_EM, ENABLE_SCHEDULER, ENABLE_PMDisabled
ENABLE_NODE_IDLINGEnables idling and reset of nodes before force shutdown of a sub-system
Disabled
ENABLE_PMEnables Power Management Module
Enabled
ENABLE_SCHEDULEREnables Scheduler Module
Enabled
ENABLE_WDTEnables WDT based restart functionality for PMU using CSU WDTENABLE_SCHEDULER, ENABLE_EMDisabled
ENABLE_STLEnables STL Module
Disabled
ENABLE_RTC_TESTEnables RTC Event Handler Test Module
Disabled
ENABLE_SAFETYEnables CRC calculation for IPI messages
Disabled
ENABLE_FPGA_LOADEnables FPGA bitstream loadingENABLE_PMEnabled
ENABLE_SECUREEnables security featuresENABLE_PMEnabled
XPU_INTR_DEBUG_PRINT_ENABLE

Enables debug prints for XMPU/XPPU error handling

see Using FSBL to load PMUFW regarding necessary configuration to see early prints during initialization.

ENABLE_EMDisabled
DEBUG_MODE

Enable debug logging and prints

See Using FSBL to load PMUFW regarding necessary configuration to see early prints during initialization.


Disabled
DEBUG_CLKEnables dumping clock and PLL state functionsENABLE_PMDisabled
DEBUG_PMEnables debug functions for PMENABLE_PMDisabled
IDLE_PERIPHERALSEnables idling peripherals before PS or System resetENABLE_PMDisabled
ENABLE_POSEnables Power Off Suspend featureENABLE_PMDisabled
EFUSE_ACCESSEnables eFuse access featureENABLE_PMDisabled
ENABLE_MOD_ULTRA96Enable power button functionality for ULTRA96 boardENABLE_PM, ENABLE_SCHEDULERDisabled

Power Management in PMU FW

Zynq MPSoC Power Management framework is based on an implementation of the Embedded Energy Management Interface (EEMI). This framework allows software components running across different processing units (PUs) on a chip or device to issue or respond to requests for power management.

...