Adding custom Platform Management API in Firmware and Linux driver

This document describes the end-to-end flow for adding new PM API in versal firmware and how it can be used in any Linux driver.

Table of Contents

Overview

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.

Adding a new PM API

To add a new API, changes in the below components are required.

  • XilPM server

  • ATF

  • Linux ZynqMP Firmware driver

ZynqMP Firmware Driver is used for both ZynqMP and Versal Platform.

Changes in XilPM server

Define new PM (Platform Management) API ID

First, user needs to define new PM API ID.

Implement the PM API function

Once a new PM API ID is defined, implement the API function.

Add new PM API as valid feature in XilPM

Feature check API is used to determine compatibility between firmware, ATF and Linux. If there is a change in the existing PM API interface such as arguments, version of that API should be updated in the feature check, otherwise the client (i.e. ATF/Linux) would be using different argument so the PM API may not work properly. To identify this version gap, feature check is an important function that takes care of this check. So, it is required to add new PM API as a valid feature and its version.

Changes in ATF

Add PM API ID in ATF

Add the same PM API ID defined in xilpm/server.

Implement the PM API function

Once the PM API ID is defined, implement the API function.

Add new PM API as valid feature in ATF

As explained in https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/1346535541/Adding+custom+Platform+Management+API+in+Firmware+and+Linux+driver#Add-new-PM-API-as-Valid-feature section 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.

  • Add the newly added API as a valid feature and return the appropriate API version in pm_feature_check()

  • Example of Marking PM_IOCTL as valid feature in ATF: PM_IOCTL

Changes in Linux ZynqMP Firmware Driver

Add PM API ID in Linux

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

Declaration

Declare a function which can be used by another driver to call PM API.

Right now there is also eemi_ops (zynqmp_eemi_ops structure which holds callback to functions which can be used by other driver to call PM API), will be removed so do not use it.

  • Example of Function declaration: ioctl (Please note that, here it is used as callback function but in new Linux kernel v5. 10 and there after it will be direct call)

  • Examples for declaring a function which can be called directly by another driver: zynqmp_pm_clock_enable()

Definition

Define a function to send the PM API request to ATF via SMC. Functions are defined in zynqmp.c.

Example of PM API usage by another driver

Example for end-to-end implementation of PM IOCTL API

Adding a new IOCTL in PM IOCTL API

Many times, it is not required to add a whole new PM API for minimal operations such as providing access to a register from secure register space to the Non-Secure Application or OS, which might not have direct access to such registers. For these trivial tasks, one can use the existing PM IOCTL API and just add a new IOCTL ID to perform that operation.

For more details, please refer to XPm_DevIoctl Operations.

No change in ATF is required if you are just adding new IOCTL ID.

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy