It is important that modifications within the EEMI protocol are backward and forward compatible. In case of incompatible modifications, there must be a way for a graceful exit without breaking system execution. This is achieved using version control of EEMI APIs.
For proper operation, PLM clients must use the same payload and response format that is used in the PLM server. EEMI API payload format and response format is mapped to the version number of each API in the PLM server. Therefore, PLM clients should know the version number of the EEMI API in the PLM before making an EEMI call and it should send payload and parse response accordingly.
The XilPM module within PLM firmware implements the EEMI interface and its versions. Code reference how EEMI API interface is mapped to version number is shown below:
EEMI API version mapping in PLM firmware:
file: lib/sw_services/xilpm/src/versal/server/xpm_api.c
function: XPm_FeatureCheck
EEMI API Interface signature:
file: lib/sw_services/xilpm/src/versal/server/xpm_api.h
The PLM client should use the PM_FEATURE_CHECK call to know the current version number of the EEMI API implemented in the firmware before using it. If the client is not using the same version of EEMI call as the server, then the payload and response format of EEMI call between the server and the client could differ. In this case, PLM clients should avoid using that EEMI call and make a graceful exit. You can also use the PM_FEATURE_CHECK call to know the version of the PM_FEATURE_CHECK itself.
Version 1 of PM_FEATURE_CHECK can retrieve the version of each EEMI API. However, for EEMI APIs like PM_IOCTL and PM_QUERY_DATA, knowing the version number is not enough. These EEMI APIs multiplex multiple sub-functionalities, and each sub-functionality has its own ID assigned. So, each sub-functionality has its own payload and response format. In addition to EEMI API version, you should know whether that sub-functionality is available in the PLM firmware. Version 2 of PM_FEATURE_CHECK also provides this information. The response of the PM_FEATURE_CHECK call contains 4-word (32-bit) variable. The response buffer is in little endian format.
The response format of PM_FEATURE_CHECK call is as following for version 1:
Response [0] -> Status of command. Value 0 is success. Non-zero value indicates error code.
Response [1] -> EEMI API ID version.
Response [2] -> Ignored by PLM clients.
Response [3] -> Ignored by PLM clients.
The response format of PM_FEATURE_CHECK call is as following for version 2:
Response [0] -> Status of Command, Value 0 is Success. Non-zero value indicates error code.
Response [1] -> EEMI API ID version.
Response [2] -> Lower 32-bit mask of sub-functionality of EEMI call (for some EEMI call only).
Response [3] -> Upper 32-bit mask of sub-functionality of EEMI call (for some EEMI call only).
In case of PM_IOCTL and PM_QUERY_DATA, the response formats for both version 1 and version 2 will also contain the bitmask value where each sub-functionality ID number is mapped to respective bit number. If sub-functionality with ID=1 is available then, bit-1 will be set otherwise that bit will be 0. PM clients should implement mechanism to avoid PM_FEATURE_CHECK call multiple times for the same EEMI API. The following activity diagram illustrates the PM_FEATURE_CHECK call sequence between server and client.