EEMI API のバージョン管理を使用した実行時のデカップリング - 2023.2 日本語

EEMI プロトコル内での変更は、前方互換性と下位互換性を確保することが重要です。互換性のない変更が発生した場合に備えて、システムの実行を中断することなく正しい手順で呼び出しを終了する方法が必要です。これには EEMI API のバージョン管理を使用します。

正常に動作するには、PLM クライアントは、PLM サーバーと同じペイロードと応答のフォーマットを使用する必要があります。EEMI API のペイロードと応答のフォーマットは、PLM サーバー内の各 API のバージョン番号に対応付けられています。したがって、PLM クライアントは、EEMI 呼び出しを実行する前に PLM 内の EEMI API のバージョン番号を確認し、それに従ってペイロードの送信と応答の解析を実行する必要があります。

EEMI インターフェイスとそのバージョンは、PLM ファームウェア内の XilPM モジュールでインプリメントされます。EEMI API インターフェイスとバージョン番号の対応関係を確認するためのコードを次に示します。

PLM ファームウェア内の EEMI API とバージョンのマップ:

file: lib/sw_services/xilpm/src/versal/server/xpm_api.c
function: XPm_FeatureCheck

EEMI API インターフェイス シグネチャ:

file: lib/sw_services/xilpm/src/versal/server/xpm_api.h

PLM クライアントは、EEMI API を使用する前に、PM_FEATURE_CHECK 呼び出しを使用して、ファームウェアに実装されている EEMI API の現在のバージョン番号を確認する必要があります。クライアントがサーバーと同じバージョンの EEMI 呼び出しを使用していない場合、サーバーとクライアントの間で EEMI 呼び出しのペイロードと応答のフォーマットが異なることがあります。この場合、PLM クライアントは EEMI 呼び出しを中止し、正しい手順で終了する必要があります。PM_FEATURE_CHECK 呼び出しを使用すると、PM_FEATURE_CHECK それ自体のバージョンも確認できます。

PM_FEATURE_CHECK のバージョン 1 は、各 EEMI API のバージョンを取得できます。ただし、PM_IOCTL や PM_QUERY_DATA などの EEMI API については、バージョン番号を確認するだけでは不十分です。これらの EEMI API には複数のサブ機能が含まれ、各サブ機能にそれぞれの ID が割り当てられています。したがって、各サブ機能にはそれぞれのペイロードと応答のフォーマットがあります。EEMI API のバージョン以外に、そのサブ機能が PLM ファームウェアで利用可能かを確認する必要があります。PM_FEATURE_CHECK のバージョン 2 は、この情報も提供します。PM_FEATURE_CHECK 呼び出しの応答には、4 ワード (32 ビット) の変数が含まれます。応答バッファーのフォーマットはリトル エンディアンです。

バージョン 1 の PM_FEATURE_CHECK 呼び出しの応答フォーマットを次に示します。

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.

バージョン 2 の PM_FEATURE_CHECK 呼び出しの応答フォーマットを次に示します。

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). 

PM_IOCTL と PM_QUERY_DATA の場合、バージョン 1 とバージョン 2 のいずれも、応答フォーマットにビットマスク値が含まれ、各サブ機能の ID 番号がそれぞれのビット番号に対応付けられます。ID=1 のサブ機能が利用可能な場合、bit-1 がセットされます。利用できない場合、bit-1 は 0 になります。PM クライアントは、同じ EEMI API に対して PM_FEATURE_CHECK 呼び出しを複数回実行しないようにするためのメカニズムを実装する必要があります。次のアクティビティ図に、サーバーとクライアント間の PM_FEATURE_CHECK 呼び出しシーケンスを示します。