...
Versal ACAP Platform Management Unit provides centralized power state handling, clock management, reset management, pin control management. Platform Management (PM) services are used by calling PM API via IPI to firmware. The PM interface can be used to access secure resources by implementing custom PM APIs in firmware. This document describes the end-to-end flow for adding new PM API in firmware and how it can be used in any Linux driver.
Source code links mentioned in this document are from the 2020.2 release. So, you may not find the same source code on the same line in another release.
Prerequisites
Knowledge of Versal ACAP Platform Management Software Architecture. Please refer to the following sections from Versal ACAP system software developers guide.
...
Versal PM API IDs are defined in xpm_defs.h
Example: API ID: PM_IOCTL
Add new PM API ID at the end of list like PM_ACTIVATE_SUBSYSTEM in list.
Update PM_API_MAX as per new PM API ID in xpm_defs.h.
Implement the PM API function
...
Declare a function prototype in xpm_api.h.
Example of function declaration: XPm_DevIoctl().
Define the function in xpm_api.c.
Example of function definition: XPm_DevIoctl() and XPm_Ioctl().
Add a new switch case in XPm_ProcessCmd() of xpm_api.c and call implemented function from there.
Example of processing IPI request came for PM_IOCTL API: PM_IOCTL.
Add new PM API as valid feature in XilPM
...
Add the newly added PM API as a valid feature and return API version in XPm_FeatureCheck().
Example of marking PM_IOCTL as valid feature: PM_IOCTL in XPm_FeatureCheck().
Changes in ATF
Add PM API ID in ATF
Add the same PM API ID defined in xilpm/server.
Versal API IDs in ATF are defined at pm_defs.h
Add new API ID at the end of list in pm_defs.h
Example API ID: PM_IOCTL in pm_defs.h
...
Add new PM API as valid feature in ATF
As explained in https://xilinx-wiki.atlassian.net/wiki/spaces/XWUC/pages/1346535541/Adding+custom+Platform+Management+API+in+Firmware+and+Linux+driver#Add-new-PM-API-as-Valid-feature section , it is important add new PM API and to make sure the API in firmware, ATF and Linux are in sync, newly added PM API needs be added as valid feature in ATF also.
Add the newly added API as a valid feature and return the appropriate API version in pm_feature_check().The feature check function in ATF provides the version of the PM API defined in ATF. This is to make sure the API in firmware, ATF and Linux are in sync.
Example of Marking PM_IOCTL as valid feature in ATF: PM_IOCTL
Changes in Linux ZynqMP Firmware Driver
...
Add same PM API ID defined in xilpm/server and ATF.
PM API IDs are defined in xlnx-zynqmp.h
Add the new PM API ID at the end of the list before PM_API_MAX as enum in pm_api_id{}
As per Linux guideline from mainline communityy, enum values should be assigned explicitly.
Function to be used by another driver to call PM API
...
No change in ATF is required if you are just adding new IOCTL ID.