Requesting and Releasing a Node - 2020.2 English

Versal ACAP System Software Developers Guide (UG1304)

Document ID
Release Date
2020.2 English

When a subsystem requires a device node, either peripheral or memory, the device must be requested using the power management API. After the device node has performed its function and is no longer required, it should be released, so the device can be powered off or used by other subsystems.

When you call the XPm_InitFinalize() API, the platform management firmware turns off devices (such as a peripheral or memory) that are not requested by any subsystem.

You must pass the PM_CAP_ACCESS argument to the REQUEST_NODE API to access the particular peripheral/memory, as otherwise it is not powered ON.

The device, clock, and the reset operation are also not allowed if the device is not requested.

Device Request Permission

The PLM firmware checks permissions for any subsystem that requests a device. While creating a subsystem in the Vivado tool, you can assign a single peripheral to multiple subsystems, or to a single subsystem. This information is exported to PMC CDO, and the access for requesting a device is allowed based on this information from the CDO. By default, this permission is shared for all subsystems, that is, a single device can be requested by multiple subsystems. The exceptions are clock, reset and the power operation that are allowed only if a single subsystem has requested any of these resources.

Note: All subsystems must call the XPm_InitFinalize() API when they have finished initializing all their devices and requested devices using XPm_RequestNode(). Otherwise, the PLM firmware does not power down any device.

The following sequence is the ideal sequence for calling using the PM API for device management is as follows:

  1. Call XPm_RequestNode() on all required devices.
  2. Initialize devices.
  3. Call XPM_InitFinalize() to inform PLM firmware that all required devices are requested and initialized

It is not mandatory that XPm_RequestNode() has to be called before XPm_InitFinalize(). If XPm_InitFinalize() is called before XPm_RequestNode(), the PLM firmware powers down that device (as initial state is ON). If XPm_RequestNode() is called after XPm_InitFinalize(), the PLM firmware powers up the device.

Some device initialization is done through CDO. Therefore, if XPm_InitFinalize() is called before XPm_RequestNode(), it is possible that initialization is lost as device is powered down first and then powered up again. It is recommended that you call XPm_InitFinalize() once it has requested all required devices. Otherwise, you need to take care of initialization again.

When you call XPm_ReleaseNode(), be mindful that the device powers down, and initialization configuration might be lost.

Request and Release a Device From a Standalone Application

The application needs to call XPm_RequestNode(). to request usage of peripheral/device. For example:

XStatus XPm_RequestNode (const u32 DeviceId, const u32 Capabilities, const u32 QoS, const u32 Ack);

The arguments are as follows:

Device ID
Device ID of the PM device to be requested.
Device-specific capabilities are required, and can be combined. The capabilities include:
  • PM_CAP_ACCESS: Full access / functionality
  • PM_CAP_CONTEXT: Preserve context
  • PM_CAP_WAKEUP: Emit wake interrupts
  • PM_CAP_UNUSABLE: Runtime suspend (Device is requested for a subsystem but the device is clock disabled)

For more information, see OS and Libraries Document Collection (UG643).

Quality of Service (0-100) is required.
Note: Currently, this argument is not available.
Requested acknowledge type.
Note: This argument is used only for ZynqMP. For Versal devices, this argument value is always set to blocking.

If a device is already requested by a subsystem, you can call XPm_SetRequirement() to change its requirement. For example:

XStatus XPm_SetRequirement (const u32 DeviceId, const u32 Capabilities, const u32 QoS, const u32 Ack);

The application must release the device when it is no longer required. To release the device, call XPm_ReleaseNode(). For example:

XStatus XPm_ReleaseNode (const u32 DeviceId);