Zynq UltraScale+ MPSoC ソフトウェア開発者向けガイド (UG1137)

Transcription

1 Zynq UltraScale+ MPSoC ソフトウェア開発者向けガイド この資料は表記のバージョンの英語版を翻訳したもので 内容に相違が生じる場合には原文を優先します 資料によっては英語版の更新に対応していないものがあります 日本語版は参考用としてご使用の上 最新情報につきましては 必ず最新英語版をご参照ください

2 改訂履歴 次の表に この文書の改訂履歴を示します 日付バージョン改訂内容 2017 年 5 月 3 日 v4.0 第 2 章 : APU および RPU で設定可能なメモリ領域 を追加 第 4 章 : 図 4-2 を更新 Linux ソフトウェアスタックの例外レベル EL0 ~ EL3 に関する情報を追加 第 5 章 : 図 5-1 を更新 第 7 章 : ブートフロー を第 2 章から第 7 章へ移動 QSPI32 ブートモード および emmc18 ブートモード を追加 JTAG ブートモード に詳細な情報を追加 USB ブートモード を追加 図 7-8 を更新 FSBL_USB_EXCLUDE を表 7-3 に追加 第 8 章 : セキュアブートフローチャートを削除 ライブラリサポート を削除 このセクションは付録 H XilSKey Library v6.2 で説明 暗号化 に例を追加 認証 に詳細な情報を追加 外部メモリを使用するビットストリーム認証 を追加 システムメモリ管理ユニット を追加 A53 メモリ管理ユニット を追加 R5 メモリ保護ユニット を追加 第 9 章 電力管理フレームワークの概要 を追加 この内容は以前 Zynq UltraScale+ MPSoC 電力管理フレームワークユーザーガイド (UG1199) に含まれていた 第 15 章 : 表 15-1 に パラメーターおよび説明を追加 ブートイメージのフォーマット を追加 表 15-7 に追加ビットの説明を追加 OS およびライブラリの内容に関する付録を追加 ( 付録 A ~ 付録 K) 2

3 2016 年 12 月 15 日 v3.0 第 1 章の はじめに に説明を追加 第 7 章の ブートモード の説明を修正 Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) への参照リンクを変更 付録 L その他のリソースおよび法的通知 を修正してリンクを追加 2016 年 10 月 5 日 v2.0 第 2 章 : 図 2-2 から JTAG および MDM を削除 第 2 章の のセキュアおよび非セキュア ブートモードの説明を明確化 割り込み機能を削除 2015 年 11 月 18 日 v1.0 初版 第 3 章 : ハードウェア IDE 機能リストを追加 Vivado Design Suite を追加 ザイリンクスのソフトウェア開発キット のサポートされる機能を変更 SDK_Download へのリンクを追加 PetaLinux の図を表 3-3 に差し替え 第 4 章 : 図 4-2 を差し替え FreeRTOS ソフトウェアスタック を追加 第 5 章 : オープンソースによるソフトウェア開発を削除 第 6 章 : 第 6 章 ソフトウェアデザインのパラダイム のタイトルを変更 マルチプロセッサ開発用フレームワーク を追加 第 7 章 : 図 7-5 の SD モードの図 および図 7-7 の NAND モードの図を変更 第 7 章 システムブートおよびコンフィギュレーション の CSU の主な組織を削除 第 7 章 システムブートおよびコンフィギュレーション の復帰メカニズムを削除 第 7 章の プリブートシーケンス を追加 第 8 章 : 第 8 章 セキュリティ機能 のタイトルを変更し セクションを再構築 ザイリンクスペリフェラル保護ユニット の説明を修正し タイトル名を変更 暗号化 の説明を修正 暗号キーの種類およびキーレジスタの表を削除 Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) への相互参照を変更 ARM トラステッドファームウェア を変更 XMPU によるメモリ保護 から説明を削除 セキュリティ機能 から 保護チェック エラー処理 ペリフェラル保護の使用 セクションを削除 ライブラリサポート を追加 第 9 章 : ATF [ 参照 37] への参照を追加 復帰メカニズムの説明を削除 電力管理フレームワーク を追加 カスタム PMU ファームウェアの使用 を変更 第 12 章 DMA を削除 第 13 章 : QEMU 機能表を削除 ボード / キット に説明を追加 第 15 章 : システムコヒーレンシを削除 第 15 章 Bootgen イメージの生成 に付録 A を移動 BootGen コマンドオプション から -interface オプションを削除 仮想化 を削除 Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) への参照を変更 フィールドおよびオフセットテーブルを削除 Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) への参照を変更 ブートアクセスがプログラム可能であることを追加 付録 L その他のリソースおよび法的通知 から Wiki サイトを削除 3

4 目次 改訂履歴 第 1 章 : このユーザーガイドについてはじめに 対象者および内容 前提条件 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビューはじめに ハードウェアアーキテクチャの概要 APU および RPU で設定可能なメモリ領域 ブートプロセス 仮想化 リセット セキュリティ機能 安全性と信頼性 第 3 章 : 開発ツールはじめに Vivado Design Suite ザイリンクスのソフトウェア開発キット PetaLinux ツール オープンソース Yocto ツールを使用した Linux ソフトウェア開発ツール 第 4 章 : ソフトウェアスタックはじめに ベアメタルソフトウェアスタック Linux ソフトウェアスタック サードパーティソフトウェア 第 5 章 : ソフトウェア開発フローソフトウェア開発フローの概要 ベアメタルアプリケーションの開発 PetaLinux を使用したソフトウェア開発 SDK を使用した Linux アプリケーションの開発 第 6 章 : ソフトウェアデザインのパラダイムはじめに マルチプロセッサ開発用フレームワーク 対称型マルチプロセッシング (SMP)

5 非対称型マルチプロセッシング (AMP) 第 7 章 : システムブートおよびコンフィギュレーションはじめに ブートフロー ブートイメージの生成 ブートモード ブートフローの詳細 FSBL コンパイルフラグの設定 第 8 章 : セキュリティ機能はじめに ブート時のセキュリティ 外部メモリを使用するビットストリーム認証 実行時セキュリティ ARM トラステッドファームウェア ザイリンクスメモリ保護ユニット ザイリンクスペリフェラル保護ユニット システムメモリ管理ユニット A53 メモリ管理ユニット R5 メモリ保護ユニット 第 9 章 : 電力管理フレームワークの概要はじめに Zynq UltraScale+ MPSoC の電力管理の概要 Zynq UltraScale+ MPSoC の電力管理ソフトウェアアーキテクチャ 電力管理に API を使用 XilPM の実装の詳細 Linux ARM トラステッドファームウェア (ATF) PMU ファームウェア 第 10 章 : プラットフォーム管理はじめに PS のプラットフォーム管理 第 11 章 : リセットはじめに システムレベルリセット ブロックレベルリセット APU リセット RPU リセット FPD リセット 第 12 章 : 高速バスインターフェイスはじめに USB ギガビットイーサネットコントローラー PCI Express

6 第 13 章 : クロックおよび周波数管理はじめに ペリフェラルの周波数変更 第 14 章 : ターゲット開発プラットフォームはじめに QEMU ボード / キット 第 15 章 : Bootgen イメージの生成はじめに BIF ファイルのパラメーター Bootgen コマンドラインのオプション Bootgen コマンドの例 ブートイメージのフォーマット ブートヘッダーテーブル レジスタ初期化テーブル イメージヘッダーテーブル パーティションヘッダーテーブル 認証証明 認証証明のヘッダー 付録 A: Power Management Framework Appendix XilPM Argument Value Definitions XilPM Error Codes 付録 B: Xilinx Standard C Libraries Xilinx Standard C Libraries 付録 C: Standalone Library Reference v6.2 Xilinx Hardware Abstraction Layer API 付録 D: XilFlash Library v4.3 Overview 付録 E: XilIsf Library v5.8 Overview 付録 F: XilFFS Library Reference 3.6 Overview 付録 G: XilRSA Library v1.3 Overview 付録 H: XilSKey Library v6.2 Overview 付録 I: XilPM Library v2.1 Overview

7 付録 J: XilFPGA Library v2.0 Overview 付録 K: XilSecure Library Reference Overview 付録 L: その他のリソースおよび法的通知ザイリンクスリソース ソリューションセンター Xilinx Documentation Navigator およびデザインハブ 参考資料 法的通知

8 第 1 章 このユーザーガイドについて はじめに このガイドでは ザイリンクス Zynq UltraScale+ MPSoC デバイス用のシステムソフトウェアおよびアプリケーションを設計 開発する上で必要なソフトウェア関連情報を提供します Zynq UltraScale+ MPSoC ファミリには 次のシステム機能に基づいたさまざまな製品があります アプリケーションプロセッシングユニット (APU) デュアルコアまたはクワッドコア ARM Cortex -A53 MPCore CPU 周波数は最大 1.5GHz リアルタイムプロセッシングユニット (RPU) デュアルコア ARM Cortex-R5 MPCore CPU 周波数は最大 600MHz グラフィックスプロセッシングユニット (GPU) ARM Mali -400 MP2 GPU 周波数は最大 667MHz ビデオコーデックユニット (VCU) 別々のコアを介してエンコードとデコードの同時実行 H.264 ハイプロファイル レベル 5.2 (4Kx2K-60 レート ) H.265 (HEVC) メイン 10 プロファイル レベル 5.1 ハイティア 4Kx2K-60 の最大レート 8 ビットおよび 10 ビットのエンコーディング 4:2:0 および 4:2:2 のクロマサンプリング 詳細は Zynq UltraScale+ MPSoC の製品表 [ 参照 5] および製品の長所 [ 参照 6] を参照してください 8

9 第 1 章 : このユーザーガイドについて 対象者および内容 このガイドは ソフトウェア開発者およびシステムアーキテクトを対象に 次の内容について説明しています ザイリンクスのソフトウェア開発ツール 利用可能なプログラミングオプション デバイスドライバー ミドルウェアスタック フレームワーク サンプルアプリケーションなどザイリンクスのソフトウェアコンポーネント プラットフォーム管理ユニットファームウェア (PMUFW) ARM トラステッドファームウェア (ATF) OpenAMP PetaLinux ツール Xen Hypervisor Zynq UltraScale+ MPSoC デバイス向けに開発されたその他のツール 前提条件 このガイドは 次の経験 知識があることを前提としています エンベデッドソフトウェアの開発経験 ARMv7 および ARMv8 アーキテクチャに関する知識 Vivado 統合設計環境 (IDE) ザイリンクスソフトウェア開発キット (SDK) コンパイラ デバッガー オペレーティングシステムなどの開発ツールに関する知識 このガイドは次の章で構成されます 第 2 章 Zynq UltraScale+ MPSoC デバイスのプログラミングビュー : Zynq UltraScale+ MPSoC ハードウェアのアーキテクチャについて簡単に説明します すべてのユーザーには 各機能を理解するためにこの章をご一読いただくことを推奨しています 第 3 章 開発ツール : Zynq UltraScale+ MPSoC デバイスを使用したシステム開発を支援するためにザイリンクスが提供する各種ソフトウェアスタックとして ベアメタルソフトウェアスタック RTOS ベースソフトウェアスタック および完全な Linux スタックについて説明します 第 4 章 ソフトウェアスタック : ザイリンクスのソフトウェア開発ツールについて簡単に説明します ソフトウェア開発ツールの機能に対する理解を深めていただけます ソフトウェア開発者の方は必ずこの章を最後までお読みになり ソフトウェアアプリケーションのビルドおよびデバッグの手順をご確認ください 第 5 章 ソフトウェア開発フロー : ソフトウェア開発プロセスの各手順について説明します Linux OS およびベアメタルでサポートされる API およびドライバーについても簡単に説明します 第 6 章 ソフトウェアデザインのパラダイム : ヘテロジニアスプロセッシングシステム上でのいくつかのソフトウェア開発アプローチについて説明します 特に対称型マルチプロセッシング (SMP) 非対称形マルチプロセッシング (AMP) 仮想化 および SMP と AMP を組み合わせたハイブリッドモードなど さまざまなプロセッサモードでのプログラミングについて詳しく説明します 第 7 章 システムブートおよびコンフィギュレーション : セキュアモードと非セキュアモードの両方において各種ブートデバイスを使用したブートプロセスについて説明します 第 8 章 セキュリティ機能 : アプリケーションのブート時および実行時のセキュリティを確保するための Zynq UltraScale+ MPSoC デバイスの機能について説明します 第 10 章 プラットフォーム管理 : 消費電力の管理に関する機能 およびソフトウェアを使用して各種パワーモードを制御する方法について説明します 9

10 第 1 章 : このユーザーガイドについて 第 11 章 リセット : システムレベルおよびモジュールレベルのリセットについて説明します 第 12 章 高速バスインターフェイス : 高速インターフェイスプロトコルのコンフィギュレーションフローについて説明します 第 13 章 クロックおよび周波数管理 : Zynq UltraScale+ MPSoC デバイスのペリフェラルのクロックおよび周波数管理について簡単に説明します 第 14 章 ターゲット開発プラットフォーム : Zynq UltraScale+ MPSoC デバイス向けに提供される各種開発プラットフォームとして Quick Emulator (QEMU) および Zynq UltraScale+ MPSoC ボード / キットについて説明します 第 15 章 Bootgen イメージの生成 : Zynq UltraScale+ MPSoC デバイスのブータブルイメージを作成するためのスタンドアロンツール Bootgen について説明します Bootgen は SDK に含まれています 付録 A ~ 付録 K では ソフトウェアプラットフォームの開発に役立つ利用可能なライブラリおよびボードサポートパッケージについて説明しています 付録 L その他のリソースおよび法的通知 : このガイドで参考資料として示した文書へのリンクをまとめます 10

11 第 2 章 Zynq UltraScale+ MPSoC デバイスのプログラミングビュー はじめに Zynq UltraScale+ MPSoC デバイスは ヘテロジニアスマルチプロセッシングを必要とするアプリケーションを幅広くサポートします このデバイスは次の機能をサポートしています 複数レベルのセキュリティ 高度な安全性 高度な電力管理 広帯域のプロセッサ I/O およびメモリ ヘテロジニアスマルチプロセッシングに基づくアプローチで直面する設計には 次のような課題があります 消費電力の仕様を満たしながらアプリケーションパフォーマンスの要件を満たすこと 種類の異なる複数のプロセッサからのメモリアクセスを最適化すること プロセッシングエンジン間で低レイテンシかつコヒーレントな通信を行うこと すべての動作モードでシステム消費電力を管理および最適化すること ザイリンクスは Zynq UltraScale+ MPSoC デバイスでのハードウェア / ソフトウェア開発やオペレーティングシステム ヘテロジニアスシステムソフトウェア セキュリティ管理モジュールなどのさまざまなソフトウェアモジュールに対応できる包括的なツールを提供しています Zynq UltraScale+ MPSoC デバイスは ARM v8 ベースの高性能で高エネルギー効率の 64 ビットアプリケーションプロセッサである Cortex -A53 および 32 ビットの ARM Cortex-R5 MPCore リアルタイムプロセッサを搭載するヘテロジニアスデバイスです ハードウェアアーキテクチャの概要 Zynq UltraScale+ MPSoC デバイスは 消費電力の削減 プログラマブルアクセラレーション I/O およびメモリ帯域幅が強化されており ヘテロジニアスプロセッシングを必要とするアプリケーションに最適です 図 2-1 に 次世代のプログラマブルエンジン セキュリティ 安全性 信頼性 および 32 ビットから 64 ビットへのスケーラビリティを備えた Zynq UltraScale+ MPSoC アーキテクチャのブロック図を示します 11

12 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー X-Ref Target - Figure 2-1 Processing System GIC RPU LLLP Cortex-R5 32 KB I/D 128 KB TCM GIC LLLP Cortex-R5 32 KB I/D 128 KB TCM APU Cortex-A53 32 KB I/D Cortex-A53 32 KB I/D SCU Cortex-A53 32 KB I/D Cortex-A53 32 KB I/D GPU Mali-400 MP2 64 KB L2 ACP 1 MB L2 Low Power Switch 256 KB OCM SMMU/CCI PCIe Gen2 x1, x2, or x4 RGMII 4 x 1GE ULPI 2 x USB x SATA v3.0 SGMII USB 3.0 PS-GTR NAND x8 ONFI x SD3.0/ emmc4.51 DisplayPort v1.2 x1, x2 MIO CSU SHA3 AES-GCM RSA Quad-SPI x 8 2 x SPI 2 x CAN 2 x I2C 2 x UART GPIOs SYSMON PMU Processor System 128 KB RAM BPU LPD-DMA Central Switch FPD-DMA DDRC (DDR4/3/3L, LPDDR3/4) GFC To ACP ACE LPD_PL PL_LPD HP HPM HPC Programmable Logic Interlaken GTY Quad VCU H.264/H.265 DisplayPort Video and Audio Interface 100G Ethernet GTH Quad PCIe Gen4 Battery Power Low Power Full Power 32-bit/64-bit M 64-bit S M 128-bit S UG1085_c1_01_ 図 2-1: Zynq UltraScale+ MPSoC デバイスのハードウェアアーキテクチャ 12

13 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー Zynq UltraScale+ MPSoC デバイスには次の機能があります Cortex-R5 デュアルコアリアルタイムプロセッシングユニット (RPU) ARM Cortex-A53 64 ビットクワッド / デュアルコアアプリケーションプロセッシングユニット (APU) Mali-400 MP2 グラフィックスプロセッシングユニット (GPU) 外部メモリインターフェイス (I/F): DDR4 LPDDR4 DDR3 DDR3L LPDDR3 2x クワッド SPI および NAND 汎用コネクティビティ : 2x USB 2.0 2x SD/SDIO 2x UART 2x CAN 2.0B 2x I2C 2x SPI 4x 1GE および GPIO セキュリティ : AES (Advanced Encryption Security) RSA (Rivest Shamir Adleman) および SHA3 (Secure Hash Algorithm 3) AMS システムモニター : 10 ビット 1 MSPS ADC 温度 電圧 および電流モニター プロセッシングシステム (PS) には 5 つの高速シリアル I/O (HSSIO) インターフェイスがあり 次に示す必須プロトコルをサポートします PS PCIe インターフェイス用統合ブロック : ベース仕様バージョン 2.1 準拠 Gen2x4 SATA 3.0 仕様に準拠したインターフェイス DisplayPort インターフェイス : 最大ビデオ解像度 4k x 2k に対応した DisplayPort インターフェイス ( ソースのみ ) を実装 USB 3.0 インターフェイス : USB 3.0 仕様に準拠し 5Gb/s ラインレートを実装 シリアル GMII インターフェイス : 1Gb/s SGMII インターフェイスをサポート 電源シーケンス 安全性 セキュリティ およびデバッグの機能を支えるプラットフォーム管理ユニット (PMU) 詳細は Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) の第 3 章 アプリケーションプロセッシングユニット (APU) 第 4 章 リアルタイムプロセッシングユニット (RPU) 第 6 章 プラットフォーム管理ユニット (PMU) 第 5 章 グラフィックスプロセッシングユニット (GPU) および第 13 章 割り込み のプロセッサ間の割り込み (IPI) に関する説明を参照してください その他のコンポーネントについては Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] を参照してください 13

14 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー APU および RPU で設定可能なメモリ領域 APU および RPU で設定可能なメモリ領域を次の各表に示します 表 2-1: APU で設定可能なメモリ領域 メモリタイプ 開始アドレス サイズ DDR Low 0x GB DDR High 0x GB OCM 0xFFFC KB QSPI 0xC MB 表 2-2: RPU ( ロックステップモード ) で設定可能なメモリ領域 メモリタイプ 開始アドレス サイズ DDR Low 0x MB OCM 0xFFFC KB QSPI 0xC MB R5_0_ATCM_MEM_0 0x KB R5_0_BTCM_MEM_0 0x KB R5_TCM_RAM_0_MEM 0x KB 表 2-3: RPU ( スプリットモード ) で設定可能なメモリ領域 メモリタイプ 開始アドレス サイズ R5_0 DDR Low 0x MB OCM 0xFFFC KB QSPI 0xC MB R5_0_ATCM_MEM_0 0x KB R5_0_BTCM_MEM_0 0x KB R5_1 DDR Low 0x MB OCM 0xFFFC KB QSPI 0xC MB R5_1_ATCM_MEM_0 0x KB R5_1_BTCM_MEM_0 0x KB 14

15 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー 次に注意事項を示します ロックステップモードの RPU では R5_0_ATCM_MEM_0 および R5_0_BTCM_MEM_0 メモリアドレスはシステムアドレスマップの R5_0_ATCM_LSTEP および R5_0_BTCM_LSTEP のメモリ範囲にそれぞれマップされます スプリットモードの RPU では R5_x_ATCM_MEM_0 および R5_x_BTCM_MEM_0 のメモリアドレスはシステムアドレスマップの R5_x_ATCM_SPLIT および R5_x_BTCM_SPLIT のメモリ範囲にそれぞれマップされます QSPI コントローラーがリニアモードの場合 QSPI メモリにアクセス可能です 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 10 章 システムアドレス ) を参照してください ブートプロセス 複数ステージからなるブートプロセスは プラットフォーム管理ユニット (PMU) とコンフィギュレーションセキュリティユニット (CSU) で管理および実行されます デバイスはセキュアモードまたは非セキュアモードでブートできます ブートの各ステージは次のとおりです プリコンフィギュレーションステージ : このステージは主に PMU が制御し PMU ROM を実行してシステムをセットアップします リセットおよび復帰に関するプロセスはすべて PMU が処理します コンフィギュレーションステージ : このステージでは PS の FSBL ( 第 1 段階ブートローダー ) コードをオンチップ RAM (OCM) にロードします セキュアモードと非セキュアの両方のブートモードをサポートします ブートヘッダーを介して Cortex-R5 プロセッサと Cortex-A53 プロセッサのいずれかに対して FSBL を実行できます Cortex-R5 プロセッサでは ロックステップモードもサポートされています ポストコンフィギュレーションステージ : FSBL の実行が開始すると Zynq UltraScale+ MPSoC デバイスはポストコンフィギュレーションステージに移行します ブートモード 外部デバイスからのブートでは 次のいずれかのブートモードを使用できます クワッド SPI フラッシュメモリ (QSPI24 QSPI32) emmc18 NAND SD0/SD1 JTAG USB bootrom は SATA イーサネット および PCI Express (PCIe) からのブートを直接サポートしていません 異なるブートモードのブートプロセスの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション ) を参照してください 15

16 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー QSPI24 QSPI ブートモードは 次の機能をサポートします シングル QSPI フラッシュメモリ (QSPI24) では x1 x2 および x4 読み出しモード デュアル QSPI では x8 読み出しモード マルチブートのイメージ検索 注記 : I/O モードは FSBL でサポートされません 詳細は QSPI24 ブートモード を参照してください QSPI32 QSPI32 ブートモードは次の機能をサポートします シングル QSPI フラッシュメモリ (QSPI32) では x1 x2 および x4 読み出しモード デュアル QSPI では x8 読み出しモード マルチブートのイメージ検索 BSP ドライバー用 I/O モード (FSBL ではサポートされない ) 詳細は QSPI32 ブートモード を参照してください emmc18 emmc18 ブートモードは次の機能をサポートします FAT 16/32 ファイルシステムによるブートイメージの読み出し マルチブートのイメージ検索 マルチブートで検索可能なイメージファイルの最大数は 8,191 詳細は emmc18 ブートモード を参照してください NAND NAND ブートモードは 次の機能をサポートします 8 ビット幅でのブートイメージの読み出し マルチブートのイメージ検索 詳細は NAND ブートモード を参照してください SD SD ブートではバージョン 3.0 がサポートされます このバージョンは 次の機能をサポートします FAT 16/32 ファイルシステムによるブートイメージの読み出し マルチブートのイメージ検索 マルチブートで検索可能なイメージファイルの最大数は 8,191 詳細は SD ブートモード を参照してください 16

17 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー JTAG PS に必要なソフトウェアイメージと PL に必要なハードウェアイメージは JTAG を使用してダウンロードできます 重要 : JTAG モードの場合 Zynq UltraScale+ MPSoC デバイスは非セキュアモードでのみブート可能です 詳細は JTAG ブートモード を参照してください USB USB ブートモードは USB 2.0 をサポートします マルチブート イメージフォールバック XIP はサポートしません セキュアと非セキュアの両方のブートモードをサポートします USB ブートモードは DDR サイズの小さいシステムではサポートされません このブートモードはデフォルトで無効となっています 詳細は USB ブートモード を参照してください 仮想化 仮想化により 1 つのプロセッサで複数のソフトウェアスタックを同時実行できるため Zynq UltraScale+ MPSoC デバイスの生産性が向上します 仮想化の役割はシステムによってそれぞれ異なります あるシステムでは 仮想化によってプロセッサの使用率を常に高く維持し 消費電力の削減と性能の最大化を実現しています また別のシステムでは 独立性や冗長性を確保するために各種のソフトウェアスタックを分割する手段として仮想化を利用しています 仮想化サポートは ARM 例外レベル 2 (EL2) を含むインプリメンテーションにのみ該当します ARM v8 は仮想化拡張機能によって完全仮想化をサポートしているため ほぼネイティブなゲストオペレーティングシステムの性能が得られます 仮想化の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の システム仮想化 を参照してください リセット Zynq UltraScale+ MPSoC には パワーオンリセット (POR) システムリセット およびデバッグシステムリセットなど複数のシステムレベルリセットがあり また PS APU RPU FPD および PL 用にブロックレベルのリセットもあります Zynq UltraScale+ MPSoC デバイスのリセットブロックはシステムに対する外部および内部リセット入力を処理し すべてのペリフェラル APU および RPU に対するリセット要件を確実に満たします リセットブロックはデバイスのプログラマブルロジックに対してリセットを生成し プロセッサシステム (PS) ブロックとプロセッサロジック (PL) ブロックに対して個別にリセットのアサートが可能です 17

18 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー セキュリティ機能 Zynq UltraScale+ MPSoC デバイスの主要なセキュリティ機能は 次のブロックによって提供されます コンフィギュレーションセキュリティユニット (CSU) コンフィギュレーションセキュリティユニット (CSU) は 次の図に示す 2 つの主要ブロックで構成されます 左側のブロックは ブート動作を制御する三重冗長プロセッサを備えているセキュアプロセッサブロックです X-Ref Target - Figure 2-2 To/From LPD Main Switch CSU PMU Switch PSTP Tamper Sources INTC ECC Triple Redundant MicroBlaze CSU Local Registers PUF CSU Registers RSA Multiplier CSU DMA Secure Stream Switch ROM Validation SHA AES- GCM 256 PCAP To PL Configuration RAM (32 KB) ROM (128 KB) PMU ROM Validation Key Management BBRAM efuse PUF Operation KUP Family Security Processor Block Crypto Interface Block X 図 2-2: コンフィギュレーションセキュリティユニットのアーキテクチャ また 付属 ROM 小型専用 RAM およびすべてのセキュア動作をサポートするために必要な制御 / ステータスレジスタもあります 右側のブロックは暗号インターフェイスブロック (CIB) で AES-GCM DMA SHA RSA および PCAP インターフェイスを備えています ブート後 CSU はタンパーレスポンスの監視を実行します これらの暗号インターフェイスは動作中に使用できます これら機能の使用方法は 付録 K XilSecure Library Reference を参照してください 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の セキュリティ ) を参照してください 18

19 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー セキュアプロセッサブロック : 三重冗長プロセッサにより シングルイベントアップセット (SEU) が発生してもエラーのない動作を確保します 暗号インターフェイスブロック (CIB): AES-GCM DMA SHA-3/384 RSA および PCAP インターフェイスで構成されます AES-GCM: AES-GCM コアは 32 ビットワードベースのデータインターフェイスを備えており 256 ビットキーをサポートします キー管理 : AES を使用するには AES ブロックにキーを読み込む必要があります キーはソフトウェアまたは CSU のブート ROM で選択します SHA-3/384: SHA-3/384 エンジンは 認証の際に入力イメージのハッシュ値の計算に使用します RSA-4096 アクセラレータ : RSA 認証を高速化します ブートイメージ暗号化または認証の詳細は 次を参照してください 第 7 章 システムブートおよびコンフィギュレーション 第 15 章 Bootgen イメージの生成 Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の セキュリティ Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション システムレベル保護 システムレベル保護メカニズムには 次の領域があります Zynq UltraScale+ MPSoC システムソフトウェアスタックは ARM トラステッドファームウェア (ATF) に基づいたシステムレベルの実行時セキュリティを提供します バグのある または悪意のあるソフトウェア ( 不正なソフトウェア ) によるシステムメモリの破損またはシステム障害の発生を防止します 正しくプログラムされていない または悪意のあるデバイス ( 誤ったハードウェア ) によるシステムメモリの破損またはシステム障害の発生を防止します メモリ (DDR OCM) およびペリフェラル ( ペリフェラル制御 SLCR) を誤ったソフトウェアまたはハードウェアによる不正アクセスから保護してシステムを保護します ザイリンクスメモリ保護ユニット (XMPU): メモリを分割し メモリおよび FPD スレーブに対して TrustZone (TZ) 保護を適用します XMPU は 1 つまたは複数のマスターからのアクセスをプログラム可能なアドレス範囲に限定するように設定できます ザイリンクスペリフェラル保護ユニット (XPPU): LPD ペリフェラルを分離し プロセッサ間割り込み (IPI) を保護します XPPU は ペリフェラルのアドレスアパーチャを知らない 1 つまたは複数のマスターに対して LPD ペリフェラルへのアクセスを許可するように設定できます 19

20 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー 安全性と信頼性 Zynq UltraScale+ MPSoC アーキテクチャは 安全が重視されるアプリケーションの信頼性を確保する機能を備え ユーザーと設計者の双方にとって高いシステム信頼性を実現します 主な機能には 次のものがあります メモリおよびキャッシュのエラー検出と訂正 RPU の安全機能 システム全体の安全機能 これら機能の使用方法は 第 8 章 セキュリティ機能 を参照してください 安全機能 Cortex-A53 MPCore プロセッサは プロセッサ内のすべての RAM インスタンスに対して ECC によるキャッシュ保護をサポートしています 使用する保護方式には次の 2 つがあります SCU-L2 キャッシュ保護 CPU キャッシュ保護 これらのオプションにより Cortex-A53 MPCore プロセッサはすべての RAM で 1 ビットのエラーを検出して訂正でき 2 ビットエラーを検出します Cortex-A53 MPCore の RAM はシングルイベントアップセット (SEU) から保護され プロセッサシステムはエラーを検出してもデータ破損なしに処理を継続できます RAM の種類により パリティによるシングルエラー検出 (SED) に対応したものと ECC によるシングルエラー訂正 ダブルエラー検出 (SECDED) に対応したものがあります RPU には 2 つの主要な安全機能があります ロックステップ動作 ( 図 2-3 参照 ) ECC ( ECC ( エラーチェック訂正 ) 参照 ) ロックステップ動作 Cortex-R5 プロセッサは 2 つの RPU CPU が冗長構成で動作するロックステップ動作をサポートしています これをセーフティモードと呼びます Cortex-R5 プロセッサの動作をロックステップモードに設定した場合 片方の CPU インターフェイスのみを使用します 20

21 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー Cortex-R5 プロセッサはスプリットモードとロックステップモードの動的な変更をサポートしておらず これらモードの切り替えはプロセッサグループがパワーオンリセット (POR) 状態に保持されている間のみ許可されます プロセッサグループの動作モードは 入力信号 SLCLAMP と SLSPLIT で制御します ロックステップモードでは これらの信号によって多重化およびクランプロジックが制御されます 次に示す図のように Cortex-R5 プロセッサがロックステップモードの場合 GIC 内のディストリビューターが CPU0 に対してのみ割り込みを発行するように リセットハンドラーにコードを記述しておく必要があります RPU は Cortex -R5 MPCore プロセッサの専用割り込みコントローラーを備えています ARM PL390 ジェネリック割り込みコントローラー (GIC) は GICv1 規格に基づいています X-Ref Target - Figure 2-3 GIC TCMs Associated with CPU1 TCM A TCM B TCMs Associated with CPU0 TCM A TCM B Shim Shim Cortex-R5 CPU0 Cortex-R5 CPU0 Caches Associated with CPU0 D-Cache I-Cache Comparison and Synchronization Logic 図 2-3: RPU のロックステップ動作 TCM は各 Cortex-R5 プロセッサのローカルアドレス空間にマップされますが 同時にグローバルアドレス空間にもマップされるため すべてのマスターからアクセスできます 次の表に RPU から見たアドレスマップを示します 表 2-4: RPU のアドレスマップ 動作モード スプリットモード メモリ R5_0 から見たマップ ( 開始アドレス ) R5_1 から見たマップ ( 開始アドレス ) R5_0 ATCM (64KB) 0x0000_0000 N/A 0xFFE0_0000 R5_0 BTCM (64KB) 0x0002_0000 N/A 0xFFE2_0000 グローバルアドレスから見たマップ ( 開始アドレス ) R5_0 命令キャッシュ I- キャッシュ N/A 0xFFE4_0000 R5_0 データキャッシュ D- キャッシュ N/A 0xFFE5_0000 スプリットモード R5_1 ATCM (64KB) N/A 0x0000_0000 0xFFE9_0000 R5_1 BTCM (64KB) N/A 0x0002_0000 0xFFEB_0000 R5_1 命令キャッシュ I- キャッシュ N/A 0xFFEC_0000 R5_1 データキャッシュ D- キャッシュ N/A 0xFFED_0000 ロックステップモード R5_0 ATCM (128KB) 0x0000_0000 N/A 0xFFE0_0000 R5_0 BTCM (128KB) 0x0002_0000 N/A 0xFFE2_0000 R5_0 命令キャッシュ I-キャッシュ N/A 0xFFE4_0000 R5_0 データキャッシュ D-キャッシュ N/A 0xFFE5_

22 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー ECC ( エラーチェック訂正 ) Cortex-R5 プロセッサは ECC ( エラーチェック訂正 ) によるデータ保護をサポートしています データの特性は同じですが ECC を適用するデータチャンクのサイズが異なります 境界に揃ったデータチャンクごとにプロセッサが冗長コードビットの数を計算し データと一緒に格納します これにより プロセッサはデータチャンクまたはコードビット内の最大 2 つのエラーを検出し データチャンクまたは関連するコードビット内の 1 つのエラーを訂正できます これは SEC-DED (Single-Error Correction Double-Error Detection) ECC 方式とも呼ばれます システム全体の安全機能 システム全体の安全機能は Zynq UltraScale+ MPSoC の動作でエラーが発生しないように設計されています これらの機能を次に示します プラットフォーム管理ユニット (PMU) PMU の三重冗長プロセッサ 以降のセクションでは これら機能について説明します プラットフォーム管理ユニット Zynq UltraScale+ MPSoC デバイスのプラットフォーム管理ユニット (PMU) は PS の電圧レールに対する改ざん防止を目的とした電源の安全性に関するルーチンを実装しており ロジック BIST (LBIST) の実行やユーザー駆動の電力管理シーケンスへの応答などの処理を担います PMU にはデバイスの動作と安全性に関する重要な機能を制御するレジスタもあります 安全に関連するレジスタには 次のものがあります GLOBAL_RESET: 安全関連ブロックに対するリセットを格納します SAFETY_GATE: ハードウェア機能が誤って有効化されないようにゲーティングします SAFETY_CHK: 安全性アプリケーションのターゲットレジスタに対して周期的に書き込みと読み出しを実行してインターコネクトデータラインのインテグリティをチェックします 三重冗長プロセッサ プラットフォーム管理ユニット (PMU) には三重冗長プロセッサがあり 高度なシステム信頼性と強力な SEU 耐性を実現します PMU は システム全体のリソースに対するパワーアップ パワーダウン および監視を制御します PMU は次に示す各種タスクを実行します ブート時のシステム初期化 各種電源ドメインおよび電源アイランドの電力ゲーティングとリテンションステートの管理 外部電源制御デバイスへの電源設定の通信 ディープスリープモードを含む各種スリープステートの管理および復帰機能の処理 PMU の詳細は 第 10 章 プラットフォーム管理 を参照してください 22

23 第 2 章 : Zynq UltraScale+ MPSoC デバイスのプログラミングビュー 割り込み 割り込みは汎用割り込みコントローラー (GIC) が処理します APU と RPU には 割り込み処理用にそれぞれ専用の GIC があります RPU は 柔軟性と保護機能を考慮して GICv1 仕様に基づく ARM PL390 GIC を実装しています APU は GICv2 コントローラーを実装しています GICv2 は マルチプロセッサシステムで割り込みをサポートおよび管理するためのリソースを集約しています また プロセッサ仮想化をサポートしたシステムでの GIC 実装を可能にする GIC 仮想化拡張をサポートしています Zynq UltraScale+ MPSoC デバイスは ヘテロジニアスプロセッサ間の通信をサポートするプロセッサ間の割り込み (IPI) ブロックを実装しています PMU は種類の異なるプロセッサと同時に通信できるため PMU には 4 つの IPI があり これらは PMU の GIC に接続されます 各種プロセッサに対する IPI の配線の詳細は Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 13 章 割り込み を参照してください 23

24 第 3 章 開発ツール はじめに この章では Zynq UltraScale+ MPSoC デバイスソフトウェアのプログラミングに使用するザイリンクスツールおよびフローについて説明します ザイリンクスツールは Eclipse ベース統合開発環境 (IDE) や GNU コンパイラツールチェーンなどの一般的なコンポーネントを採用しているため この章の内容の多くはサードパーティツールにも当てはまります この章では Zynq UltraScale+ MPSoC デバイスの各種プロセッサを対象にしたオープンソース開発に利用できるオープンソースツールについても簡単に説明します Zynq UltraScale+ MPSoC デバイスで動作するソフトウェアアプリケーションの開発とデバッグには 次のような包括的なツールセットが用意されています ハードウェア IDE ソフトウェア IDE コンパイラツールチェーン デバッグおよびトレースポート エンベデッド OS とソフトウェアライブラリ シミュレータ ( 例 : QEMU) モデルおよびバーチャルプロトタイピングツール ( 例 : エミュレーションボードプラットフォーム ) サードパーティツールソリューションは 統合レベルおよび Zynq UltraScale+ MPSoC デバイスの直接サポートレベルがさまざまです 後続のセクションでは ザイリンクスの開発ツールの概要を説明します 24

25 第 3 章 : 開発ツール Vivado Design Suite ザイリンクスの Vivado Design Suite には Vivado 統合設計環境 (IDE) に含まれるツールがあります IDE は 優れた機能を備えた直感的なグラフィカルユーザーインターフェイス (GUI) を提供します Vivado Design Suite は ザイリンクス ISE ソフトウェアに代わる設計環境ですが システムオンチップ開発や高位合成などの機能が追加されています この環境は システムレベルの統合やインプリメンテーションでの生産性を高めるためにザイリンクスが開発した SoC デバイス対応で IP やシステムを中心とする次世代開発環境です Vivado Design Suite 内のすべてのツールおよびツールオプションは ネイティブツールコマンド言語 (Tcl) で記述されているため Vivado IDE と Vivado Design Suite Tcl シェルの両方で利用可能です 解析や制約の割り当ては 設計プロセス全体で可能です たとえば 合成後 配置後 配線後のいつでもタイミングや消費電力の見積もりを実行できます データベースは Tcl を使用してアクセスできるため インプリメントし直さなくても制約 デザイン構成 およびツール設定をリアルタイムに変更できます Vivado IDE では メモリ内でデザインを開くというコンセプトを導入しています デザインを開くと デザインフローのその特定段階でのネットリストが読み込まれ 制約がデザインに割り当てられ デザインがターゲットデバイスに適用されます これにより デザインを各段階で視覚化して処理できます 重要 : Vivado IDE では 7 シリーズ以降のデバイスをターゲットとするデザインのみがサポートされます Vivado Design Suite の次の機能を利用することで デザインの性能や扱いやすさを向上させることができます グラフィカルユーザーインターフェイスを備えた IP インテグレーターのプロセッサコンフィギュレーションウィザード (PCW) で IP インテグレーターブロックデザイン内で PS の作成および変更が可能です ビデオ : PCW の詳細は QuicTake ビデオ : Vivado Processor Configuration Wizard の概要 をご覧ください レジスタ転送レベル (RTL) デザイン (VHDL Verilog SystemVerilog) Vivado IP インテグレーターでザイリンクスの IP カタログからコアをすばやく統合および設定し ブロックデザインを作成 Vivado 合成 C 言語ベースのソース (C C++ SystemC OpenCL) 配置および配線を実行する Vivado インプリメンテーション デバッグ用の Vivado シリアル I/O およびロジックアナライザー Vivado 消費電力解析 タイミング制約を入力する SDC ベースの XDC (Xilinx Design Constraints) スタティックタイミング解析 柔軟なフロアプランニング 配置および配線の詳細変更 ビットストリーム生成 Vivado Tcl Store - Vivado で簡単に機能を追加したり変更が可能 Vivado Design Suite は ザイリンクスの Vivado Design Suite HLx Editions [ 参照 3] からダウンロード可能です 25

26 第 3 章 : 開発ツール ザイリンクスのソフトウェア開発キット ザイリンクスソフトウェア開発キット (SDK) は ザイリンクスエンベデッドプロセッサをターゲットとするソフトウェアアプリケーションの開発に必要なすべてが揃った完全な環境を提供します この中には GNU ベースのコンパイラツールチェーン JTAG デバッガー フラッシュプログラマ ミドルウェアライブラリ ベアメタル BSP およびザイリンクス IP 用ドライバーが含まれます また C/C++ ベアメタルおよび Linux アプリケーション開発とデバッグ用の強力な IDE も含まれます オープンソースの Eclipse プラットフォームがベースとなる SDK には C/C++ 開発ツールキット (CDT) が統合されています SDK では ARM Cortex -A53 および Cortex-R5 プロセッサ さらにはザイリンクス MicroBlaze プロセッサ * 用に統合されたツールセットを使用してソフトウェアアプリケーションを作成できます また アプリケーションを作成するための 次のようなさまざまな手段を提供しています MicroBlaze 用のベアメタルおよび FreeRTOS アプリケーション APU 用のベアメタル Linux および FreeRTOS アプリケーション RPU 用のベアメタルおよび FreeRTOS アプリケーション PMU ファームウェアのユーザーカスタマイズ 次のライブラリサンプル ( すぐにソースをロードして構築可能 ) - OpenCV - OpenAMP RPC - FreeRTOS HelloWorld - lwip - パフォーマンステスト (Dhrystone メモリテスト ペリフェラルテスト ) - 画像やビットストリームの改ざんや変更を防ぐための RSA 認証 - 第 1 段階ブートローダー (Zynq UltraScale+ MPSoC デバイスの FSBL A53 または R5 (1) ) Vivado の Project Navigator からブロックデザイン ハードウェアデザインファイル およびビットストリームファイルを SDK のエクスポートディレクトリに直接エクスポートできます Vivado Design Suite の詳細は Vivado Design Suite に関する資料 [ 参照 20] を参照してください このエクスポートプロセスを完了させるために必要なすべてのプロセスは自動で実行されます SDK プロセスは 次のファイルを SDK ディレクトリにエクスポートします.project: Vivado のプロジェクトファイル psu_init.tcl psu_init_gpl.c psu_init_gpl.h psu_init.c,psu_init.h: FSBL 作成時に必要な情報を含む psu_init.html: Zynq UltraScale+ MPSoC レジスタサマリビューアー system.hdf: ハードウェア定義ファイル SDK では次のファイルも生成できます 1. Zynq-7000 AP SoC デバイスは Cortex-A9 デバイスをサポートします 詳細は Zynq-7000 All Programmable SoC ソフトウェア開発者向けガイド (UG821) [ 参照 19] を参照してください 26

27 第 3 章 : 開発ツール FSBL ( 第 1 段階ブートローダー ) 次のプロセッサのセキュアおよび非セキュアブート用ブートイメージヘッダー (BOOT.BIN) ARM Cortex-A53 ARM Cortex-R5 MicroBlaze FSBL 作成の詳細は 第 7 章の ブートイメージの生成 を参照してください コンパイラは 次のように切り替え可能です 32 ビットまたは 64 ビット (Cortex-A53 をターゲットとするアプリケーション ) 32 ビットのみ (Cortex-A53 Cortex-R5 およびザイリンクス MicroBlaze をターゲットとするアプリケーション ) ビルド手順の一覧は ザイリンクスソフトウェア開発キットのヘルプ [ 参照 21] を参照してください SDK を起動した後 [ ヘルプ ] からさらなる検索が可能です また SDK には ザイリンクスエンベデッドソフトウェア開発に使用できる次のツールも含まれます Xilinx System Debugger (XSDB): システムデバッガー GUI およびコマンドラインインターフェイス経由でザイリンクスの hw_server を利用できます また SDK では直接利用できない低レベルのデバッグ機能も各種揃っています FPGA プログラマ : ザイリンクスデバイスにビットストリームを書き込みます フラッシュプログラマ : ビットストリームおよびソフトウェアアプリケーションイメージを外部パラレル NOR フラッシュデバイスに書き込みます リンカースクリプトジェネレーター : アプリケーションイメージをハードウェアメモリ空間にマップします ブートイメージジェネレーター : ブートローダー ビットストリーム ユーザーアプリケーションを結合してブートイメージを生成します オプションで認証および暗号化を有効にもできます ザイリンクスソフトウェアコマンドラインツール (XSCT): ザイリンクスソフトウェアコマンドラインツールは Tcl スクリプトをベースとし SDK のインストール時に提供されます ユーザーは このツールで Tcl プロンプトを開き サポートされているすべてのコマンドを使用できます ザイリンクスソフトウェアコマンドラインツールは SDK コマンド XSDB コマンド および HSI コマンドを実行するためのスクリプト操作可能なコマンドラインインターフェイスです XSCT は [ スタート ] メニューから起動できますが <SDK installation directory>/bin フォルダーの xsct.bat ファイルを実行しても起動できます <SDK installation directory>/bin フォルダー XSCT でサポートされているすべてのコマンドは カテゴリ別にグループ化されています 次の表にザイリンクス SDK ツールチェーンを示します 表 3-1: SDK でサポートされているツールチェーン ツール GNU コンパイラツールスイート Bootgen 説明 コンパイルに使用される GCC AS LD BIN UTILS などのツールを含む BOOT.BIN の生成に使用される 27

28 第 3 章 : 開発ツール 表 3-1: SDK でサポートされているツールチェーン ( 続き ) ツール make パフォーマンス解析ツールデバッグ / ダウンロードツール 説明 make ビルドをサポート SPM GPROF OProfile を含む GDB QEMU XSDB フラッシュライターを含む SDK では ソフトウェア開発プロセスを容易にするために 各タスクに対応する個別のパースペクティブを提供します C/C++ 開発で利用可能なパースペクティブには次のものがあります C/C++ パースペクティブビュー : ソフトウェア C/C++ プロジェクトの表示 作成 ビルドに利用します デフォルトでは エディター領域のほか SDK プロジェクト C/C++ プロジェクト ( ワークスペース内のソフトウェアプロジェクトを表示 ) ナビゲーションコンソール プロパティ タスク make ターゲット アウトライン 検索などの各種ビューで構成されます システムデバッガー : ソフトウェアアプリケーションのデバッグに利用します オープンソースのシステムデバッガーをカスタマイズしたものを SDK に統合しています システムパフォーマンスモニター : MicroBlaze デバイス および Zynq UltraScale+ MPSoC デバイスの PL と PS のパフォーマンスサマリビューを利用して ハードウェアおよびソフトウェアシステムのパフォーマンス特性評価が可能です リモートシステムエクスプローラー : 各種リモートシステムに接続して開発が可能です SDK は Linux アプリケーションの開発をサポートしていますが Linux カーネルの開発とデバッグを明示的にターゲットとしていません これらのツールと機能は ザイリンクス PetaLinux ツールおよびサードパーティのパートナーによって提供されます SDK 機能の詳細および Hello World サンプルデザインを使用した SDK デザインフローは ザイリンクスソフトウェア開発キットのヘルプ [ 参照 21] を参照してください SDK ツールは エンベデッド開発 ページ [ 参照 23] からダウンロード可能です PetaLinux ツール PetaLinux ツールには ザイリンクスのプロセッシングシステム向けに組み込み Linux ソリューションをカスタマイズ ビルド および展開するために必要なものがすべて揃っています MPSoC のようなデバイスの設計生産性向上を目指して最適化されたこのソリューションは ザイリンクスのハードウェア設計ツールと協調動作して Zynq UltraScale+ MPSoC デバイス向け Linux システムの開発を支援します PetaLinux には次が含まれます GNU petalinux-build make などカーネルイメージおよびアプリケーションソフトウェアをビルドするためのビルドツール GDB petalinux-boot およびプロファイリング用の oprofile を含むデバッグツール 次の表に サポートされる PetaLinux ツールチェーンを示します 28

29 第 3 章 : 開発ツール 表 3-2: サポートされる PetaLinux ツール GNU PetaLinux-Build make GDB PetaLinux-Boot QEMU OProfile ツール 詳細は 次の資料を参照してください PetaLinux ツール資料 [ 参照 2] ザイリンクス ARM GNU ツール Zynq エンベデッドデザインチュートリアル (UG1165) [ 参照 17] 説明 ソフトウェアイメージファイルの構築に使用される PetaLinux ビルドコマンド アプリケーションをコンパイルするための make ビルド デバッグ用の GDB ツール Linux を起動するために使用する PetaLinux-Boot コマンド Zynq UltraScale+ MPSoC デバイス用のエミュレータープラットフォーム プロファイリングに使用 Zynq UltraScale+ MPSoC OpenAMP スタートアップガイド (UG1186) [ 参照 13] オープンソース ザイリンクスソフトウェア開発プラットフォームには ARM GNU オープンソースツールチェーンが採用されています ザイリンクスソフトウェア開発キット (SDK) には Linux ホスト用 GNU ツールが含まれます このセクションでは Zynq UltraScale+ MPSoC デバイスのプロセッシングクラスターに利用可能なオープンソース GNU ツールおよび Linux ツールについて説明します ザイリンクス ARM GNU ツール 次の表に APU RPU およびエンベデッド MicroBlaze プロセッサのプログラミングに利用可能なザイリンクス ARM GNU ツールの一部を示します 表 3-3: ザイリンクス ARM GNU ツール ツール 説明 aarch64-linux-gnu-gcc GNU C/C++ コンパイラ aarch64-linux-gnu-g++ aarch64-linux-gnu-as GNU アセンブラー aarch64-linux-gnu-ld GNU リンカー aarch64-linux-gnu-ar アーカイブの作成 変更 およびアーカイブからのファイル抽出用 ユーティリティ aarch64-linux-gnu-objcopy オブジェクトファイルのコピーと変換を実行 aarch64-linux-gnu-objdump オブジェクトファイルからの情報を表示 aarch64-linux-gnu-size オブジェクトまたはアーカイブファイルのセクションサイズをリス ト表示 aarch64-linux-gnu-gprof プロファイリング情報を表示 aarch64-linux-gnu-gdb GNU デバッガー 29

30 第 3 章 : 開発ツール Yocto ツールを使用した Linux ソフトウェア開発ツール ザイリンクスは 自社の Yocto ビルドシステムを使用するカスタマーが Zynq UltraScale+ MPSoC デバイス用に Linux を設定 ビルド およびデプロイできるように meta-xilinx Yocto/OpenEmbedded レシピを提供しています meta-xilinx 層には ザイリンクスデバイスを使用した一般的なボードに対する BSP も多数含まれます meta-xilinx 層は各種コンポーネントのレシピを追加しており Yocto/OE をより強力にサポートします 詳細は meta-xilinx リンク [ 参照 30] を参照してください Cortex-A53 上で動作する Linux ソフトウェアは オープンソースの Linux ツールを使用して開発できます このセクションでは Linux Yocto ツールと Yocto Project 開発環境について説明します 次の表に Tocto ツールを示します 表 3-4: Yocto ツール ツールタイプ名前説明 Yocto ビルドツール Bitbake タスク間の複雑な依存制約の中でシェルと Python タスクを効率 的に並列実行できる汎用タスク実行エンジン Yocto プロファイルおよびトレースツール Yocto Project 開発環境 Perf Ftrace Oprofile Sysprof Blktrace Linux カーネルに付属するプロファイリングおよびトレーシングツール ftrace 関数トレーサーを参照します また それ以外の関連する多数のトレーサー およびこれらトレーサーが使用するインフラストラクチャも含みます コマンドラインアプリケーションとしてターゲットシステム上で動作するシステム全体のプロファイラー システム全体のプロファイラーで 1 つのウィンドウに 3 つのペインと複数のボタンが配置され ワンストップでプロファイルの開始 停止 および表示が可能 低レベルディスク I/O のトレースおよびレポート用ツール Yocto Project 開発環境は Xilinx GIT サーバーで提供される Yocto レシピを通じ Zynq UltraScale+ MPSoC デバイス用 Linux ソフトウェアの開発をサポートします Yocto Project のコンポーネントを利用すると Linux を使用したソフトウェアスタックの設計 開発 ビルドが可能です 図 3-1 に 完全な Yocto Project 開発環境を示します Yocto Project は幅広い種類のツールを統合しており 最新のザイリンクスカーネルをダウンロードして ローカルプロジェクト形式で部分的に改良を加えてビルドできます また BSP を利用してビルドおよびハードウェア構成を変更することもできます Yocto は高機能なコンパイラと高品質な解析ツールを組み合わせてイメージのビルドとテストを実行します イメージが品質テストに合格し SDK 生成に必要なパッケージフィードを受け取ると Yocto ツールはアプリケーション開発用に SDK を起動します 30

31 第 3 章 : 開発ツール Yocto Project には次の重要な特長があります 最新の Linux カーネルおよびエンベデッド環境に適したシステムコマンドのセットとライブラリを提供します X11 GTK+ Qt Clutter SDL をはじめとする各種システムコンポーネントを利用できるため ディスプレイハードウェアを備えたデバイスで豊富なユーザー体験を実現できます デバイスにディスプレイがない場合や別の UI フレームワークを使用する場合 これらのコンポーネントはインストール不要です OpenEmbedded プロジェクトと互換性のある安定したコアを 目的に応じて作成します このコアを使用して Linux ソフトウェアを簡単かつ確実にビルドして開発できます Quick Emulator (QEMU) により 幅広い種類のハードウェアおよびデバイスのエミュレーションをサポートします 詳細は Zynq UltraScale+ MPSoC QEMU ユーザーガイド (UG1169) [ 参照 8] を参照してください 重要 : ザイリンクス QEMU は すべての Yocto に対応しているわけではありません X-Ref Target - Figure 3-1 Upstream Project Releases Local Projects SCMs (optional) Upstram Source Metadata/Inputs Build System Output Packages Process steps (Tasks) Output Image Data Source Mirror(s) User Configuration Source Fetching.rpm Generation Package Feeds Metadata (.bb+patches) Machine(BSP) Configuration Patch Application Output Analysis for package splitting plus Package relationships.deb Generation QA Tests image Generation SDK Generation Policy Configuration Configuration / Compile / Autoreconf as needed.ipk Generation Images Application Development SDK X 図 3-1: Yocto Project 開発環境 Yocto ツールおよび Yocto Project 開発環境は Yocto Project のウェブサイト [ 参照 40] からダウンロードできます ザイリンクスがサポートする Yocto 機能の詳細は このセクション ( PetaLinux ツール資料 : リファレンスガイド (UG1144) [ 参照 24] の第 2 章 Yocto の機能 ) を参照してください 31

32 第 4 章 ソフトウェアスタック はじめに この章では Zynq UltraScale+ MPSoC デバイスで利用可能な各種ソフトウェアスタックの概要を紹介します このデバイスで使用する各種ソフトウェア開発ツールの詳細は 第 3 章 開発ツール を参照してください ベアメタルおよび Linux ソフトウェアアプリケーション開発の詳細は 第 5 章 ソフトウェア開発フロー を参照してください ベアメタルソフトウェアスタック ザイリンクスは ザイリンクス SDK ツールの一部としてスタンドアロン BSP ( ボードサポートパッケージ ) と呼ばれるベアメタルソフトウェアスタックを提供しています スタンドアロン BSP は 標準入出力やプロセッサハードウェア機能へのアクセスなどの基本機能を備えたシンプルなシングルスレッド環境を提供します この BSP および付属のライブラリは非常に柔軟な設定が可能で 必要な機能を最小限のオーバーヘッドで提供します 詳細は 第 3 章 開発ツール の ザイリンクスのソフトウェア開発キット で説明しています スタンドアロンドライバーは 次のパスにあります <Xilinx Installation Directory>\SDK\<version>\data\embeddedsw\XilinxProcessorIPLib\drivers ライブラリは 次のパスにあります <Xilinx Installation Directory>\SDK\<version>\data\embeddedsw\lib\sw_services 32

33 第 4 章 : ソフトウェアスタック 次の図に APU のベアメタルソフトウェアスタックを示します X-Ref Target - Figure 4-1 Zynq UltraScale+ MPSoC Hardware 注記 : RPU のベアメタル用ライブラリおよびドライバーのソフトウェアスタックは APU と同じです ベアメタルスタックは 主に次のコンポーネントで構成されます libc 図 4-1: ベアメタルソフトウェア開発スタック ペリフェラル用のソフトウェアドライバー : PS の ARM Cortex -A53 ARM Cortex-R5 プロセッサ および PL のザイリンクス MicroBlaze プロセッサを使用する上で必要なコアルーチンなど PS のペリフェラルおよびオプションの PL ペリフェラル用ベアメタルドライバー 標準 C ライブラリ : オープンソースの Newlib ライブラリを ARM Cortex-A53 ARM Cortex-R5 および MicroBlaze プロセッサにポーティングした libc および libm その他のミドルウェアライブラリ : ネットワーキング ファイルシステム 暗号化をサポート サンプルアプリケーション : FSBL ( 第 1 段階ブートローダー ) テストアプリケーションなど libc ライブラリにはすべての C プログラムで使用できる標準関数が含まれます 次の表に libc のモジュールを示します 表 4-1: libc.a の関数と説明 ヘッダーファイル alloca.h assert.h ctype.h errno.h inttypes.h math.h setjmp.h 説明スタック内の空間確保診断コード文字に関する操作システムエラー整数型の変換数学関数ローカル外の goto コード 33

34 第 4 章 : ソフトウェアスタック 表 4-1: libc.a の関数と説明 (Cont d) ヘッダーファイル stdint.h stdio.h stdlib.h time.h 説明標準整数型標準 I/O 機能一般的なユーティリティ関数タイム関数 libm 次の表に libm 数学 C モジュールを示します 表 4-2: libm.a の関数タイプと関数一覧 代数関数 関数タイプ cbrt hypot sqrt サポートされる関数 初等超越関数 asin acos atan atan2 asinh acosh atanh exp expm1 pow log log1p log10 sin cos tan sinh cosh tanh 高等超越関数 j0 j1 jn y0 y1 yn erf erfc gamma lgamma gamma_ramma_r 整数丸め関数 IEEE 標準推奨関数 IEEE 分類関数浮動小数点関数ユーザー定義のエラー処理ルーチン eil floor rint copysign fmod ilogb nextafter remainder scalbn fabs isnan logb scalb significand matherr スタンドアロン BSP スタンドアロン BSP には 次のライブラリが用意されています XilFatFS: ザイリンクスシステム ACE コンパクトフラッシュに格納されたファイルへの読み出し / 書き込みアクセスを提供する LibXil FATFile システム XilFFS: 汎用 FAT ファイルシステムライブラリ XilFlash: Intel/AMD CFI 準拠パラレルフラッシュ用ザイリンクスフラッシュライブラリ XilISF: ザイリンクスインシステムフラッシュハードウェアをサポートしたインシステムフラッシュライブラリ XilMFS: メモリファイルシステム XilRSA: ザイリンクス RSA ライブラリ XilSkey: ザイリンクスセキュアキーライブラリ lwip ライブラリ : コア lwip スタック およびこのスタックへの BSD (Berkeley Software Distribution) ソケットスタイルインターフェイスへのアクセスを提供するオープンソース TCP/IP プロトコルスイート 付録 B Xilinx Standard C Libraries にこれらのライブラリを示します 34

35 第 4 章 : ソフトウェアスタック Linux ソフトウェアスタック Linux OS は Zynq UltraScale+ MPSoC デバイスをサポートしています 唯一の例外である ARM GPU を除いて ザイリンクスは PS のすべてのペリフェラル および PL の主要ペリフェラルのオープンソースドライバーを開発して提供しています 次の図に APU の Linux ソフトウェアスタックを示します X-Ref Target - Figure 4-2 Non-secure World Secure World EL0 App1 App2 App3 App4 EL1 Linux SMP Third Party Secure OS EL2 Hypervisor EL3 ARM Trusted Firmware PMU Firmware 図 4-2: Linux ソフトウェア開発スタック ARM v8 例外モデルは 次に示す EL0 ~ EL3 の例外レベルを定義しています EL0 は最も低いソフトウェア実行特権レベルです EL0 での実行は特権なし実行と呼ばれます 例外レベルが 1 から 3 へと大きくなるにつれ ソフトウェア実行特権レベルが上がります EL2 はプロセッサ仮想化をサポートします EL3 はセキュアステートをサポートします Cortex-A53 MPCore プロセッサは EL0 ~ EL3 のすべての例外レベルを実装し 各例外レベルで AArch64 と AArch32 の両方の実行ステートをサポートしています 35

36 第 4 章 : ソフトウェアスタック Zynq UltraScale+ MPSoC デバイスの Linux ソフトウェアスタックはいくつかの方法で利用できます オプションは次のとおりです PetaLinux ツール : PetaLinux ツールには Linux ソースツリーのテスト済みブランチ U-Boot および Yocto ベースツールが含まれ カーネル root ファイルシステム デバイスツリー およびアプリケーションを含む完全な Linux イメージを簡単にビルドできます PetaLinux ツールの製品ページ [ 参照 2] を参照してください オープンソース Linux および U-Boot: ドライバー ボードコンフィギュレーション U-Boot アップデートを含む Zynq UltraScale+ MPSoC デバイス用の Linux カーネルアップデートは ザイリンクスの Github リンク [ 参照 28] から入手できます また メイン Linux カーネルおよび U-Boot ツリーからも継続的に提供されます Yocto ボードサポートパッケージもメイン Yocto ツリーにあります 商用 Linux ディストリビューション : 一部の商用ディストリビューションもザイリンクスの UtlraScale+ MPSoC デバイスをサポートしており Linux の設定 最適化 およびデバッグのための高度なツールを備えています 詳細はザイリンクスのエンベデッドコンピューティングのページ [ 参照 29] を参照してください マルチメディアスタックの概要 このセクションでは Zynq UltraScale+ MPSoC デバイスのマルチメディアソフトウェアスタックについて説明します グラフィックスアプリケーションは GPU および高性能 DisplayPort によって高速に処理されます GPU は 2D/3D グラフィックスに対するハードウェアアクセラレーションを提供します GPU には 1 つのジオメトリプロセッサ (GP) と 2 つのピクセルプロセッサ (PP0 PP1) があり それぞれが専用のメモリ管理ユニット (MMU) を備えています APU と GPU のキャッシュコヒーレンシは キャッシュコヒーレントインターコネクト (CCI) によって確保されます CCI は ACE (AXI Coherency Extension) のみをサポートします APU と GPU は CCI を経由して DDR コントローラーに接続され ここで DDR アクセスのアービトレーションが実行されます 36

37 第 4 章 : ソフトウェアスタック 次の図に マルチメディアスタックを示します X-Ref Target - Figure 4-3 Graphics Application Graphic Libraries Ex: Open GLES1, Open GLES 2, Open VG Gstreamer ffmpeg pipeline Display Server Ex: XII, Wayland Mali common Libraries Video Codecs Linux Kernel Drivers Frame Buffer Driver DRM Mali Graphic Drivers Video Drivers Ex: V4L2 Display Drivers Cache Coherent Interconnect ARM MALI GPU APU GPO PPO PP1 Display Port DDR Controller Memory 図 4-3: マルチメディアスタック プロセッサ上で動作するアプリケーションは マルチメディア用 Linux カーネルドライバーを利用してハードウェアにアクセスします アプリケーションは 次の表に示すライブラリおよびフレームワークコンポーネントで構成されるミドルウェアスタックを介してマルチメディアドライバーを利用します 37

38 第 4 章 : ソフトウェアスタック 表 4-3: ライブラリおよびフレームワークコンポーネント コンポーネントディスプレイサーバーグラフィックスライブラリ Mali-400 MP2 共通ライブラリ Gstreamer ビデオコーデック 説明 アプリケーションからオペレーティングシステムに対する入出力を調整します Zynq UltraScale+ MPSoC デバイスアーキテクチャは OpenGL ES 1.1/2.2 および OpenVG 1.1 をサポートしています Mali-400 MP2 グラフィックライブラリです プログラマが各種メディア処理コンポーネントを作成するためのフリーウェアのマルチメディアフレームワークです ビデオエンコーダーおよびデコーダー 次の表に Linux カーネルグラフィックスドライバーを示します 表 4-4: Linux カーネルドライバー ドライバー フレームバッファードライバー ダイレクトレンダリングマネージャー (DRM) MALI-400 MP2 グラフィックスドライバー ビデオドライバー DisplayPort ドライバー 説明 /dev/fb* 経由のインターフェイスで外部からアクセス可能なカーネルグラフィックスドライバーです このインターフェイスはビデオモードの設定やリニアフレームバッファーへの描画など 一部の機能のみを実装しています 複数のユーザー空間コンポーネント間でハードウェアのレンダリングを実行します GPU ハードウェアへのアクセスを提供します V4L2 フレームワークに基づくビデオキャプチャおよび出力デバイスパイプラインドライバーです ザイリンクス Linux V4L2 パイプラインドライバーは 複数のサブデバイスを持つパイプライン全体を指します パイプラインはメディアノード経由で設定でき ストリームオン / オフなどの制御はビデオノード経由で実行できます デバイスノードはパイプラインドライバーによって作成されます パイプラインドライバーには DMA エンジン API のラッパー層も含まれ RAM からのフレーム読み出し / 書き込みが可能です DRM フレームワークに基づいて DisplayPort へのハードウェアアクセスを許可します 38

39 第 4 章 : ソフトウェアスタック FreeRTOS ソフトウェアスタック ザイリンクスは ザイリンクス SDK ツールの一部として FreeRTOS BSP ( ボードサポートパッケージ ) を提供しています FreeRTOS BSP は 標準入出力やプロセッサハードウェア機能へのアクセスなどの基本機能を備えたシンプルなマルチスレッド環境を提供します この BSP および付属のライブラリは非常に柔軟な設定が可能で 必要な機能を最小限のオーバーヘッドで提供します FreeRTOS ソフトウェアスタックは FreeRTOS ライブラリを含むこと以外は ベアメタルソフトウェアスタックと同じです 次の図に RPU の FreeRTOS ソフトウェアスタックを示します X-Ref Target - Figure 4-4 図 4-4: FreeRTOS ソフトウェアスタック 注記 : APU の FreeRTOS ソフトウェアスタックは ライブラリが 32 ビットと 64 ビットの両方をサポートすること以外は RPU のソフトウェアスタックと同じです サードパーティソフトウェア 既述以外に多くのエンベデッドソフトウェアソリューションがザイリンクスパートナーエコシステムから提供されています 詳細は ザイリンクスのウェブサイト エンベデッド開発 [ 参照 29] および サードパーティツール [ 参照 4] を参照してください 39

40 第 5 章 ソフトウェア開発フロー ソフトウェア開発フローの概要 この章では ザイリンクスソフトウェア開発キット (SDK) を使用した RPU および APU 用のベアメタルソフトウェア開発 ならびに PetaLinux ツールおよび SDK ツールを使用した APU 用の Linux ソフトウェア開発について説明します 次の図に Zynq UltraScale+ MPSoC デバイスの最上位ソフトウェアアーキテクチャを示します X-Ref Target - Figure 5-1 Vivado Configure PS Integrate IP Export Hardware to SDK Software Stack Applications Software Development Tools IDE Hardware Handoff Middleware Stack (Ex: Graphics, File system) OS Kernel Drivers Build Tools Compiler Assembler Linker System Software (Ex: Hypervisor, OpenAMP) Debug Tools Security Management Software Debugger Profiler Simulator Flash Writer Boot Loader Ex: U-Boot Power Management Firmware Software OS Kernel Zynq UltraScale+ MPSoC Hardware Hardware Quad core ARM-A53 APU Dual core ARM Cortex-R5 RPU ARM Mali400 GPU Platform Management Unit Peripherals System Configuration and Security Unit Enhanced DSP and AXI DDR Memory Controller Programmable Logic X 図 5-1: ソフトウェア開発アーキテクチャ 40

41 第 5 章 : ソフトウェア開発フロー ベアメタルアプリケーションの開発 このセクションでは APU および RPU 用のベアメタルアプリケーションをザイリンクス SDK を使用して開発する場合のデザインフローについて説明します 次の図に SDK の最上位のデザインフローを示します X-Ref Target - Figure 5-2 Invoke SDK Hardware Specification Files Open/ Create SDK workspace Create Board Support Package Create Application Project Build Application Project Download Hardware Bitstream to FPGA Profiling Improvements in Software Application Debug Performance met? No No Functionality achieved? Yes Create Boot Image Yes Download To Boot device 図 5-2: ベアメタルアプリケーションの開発フロー 41

42 第 5 章 : ソフトウェア開発フロー ベアメタルアプリケーションの開発は 次の手順で行います 1. ベアメタルアプリケーション用の SDK ワークスペースを開く / 作成する Creating a Standalone Application Project 参照 2. ハードウェアプラットフォーム情報をインポートする Importing a Hardware Platform Specification File 参照 3. ターゲットプロセッサ (A53 R5 PMU MicroBlaze ) を選択する 4. ボードサポートパッケージ (BSP) を作成する Creating a Board Support Package (SDK) 参照 5. BSP のコンフィギュレーション設定を変更する ( オプション ) Changing Build Configuration 参照 6. カスタム IP ドライバーのサポートを追加する ( オプション ) Using the Board Support Package Drivers Page 参照 7. アプリケーションプロジェクトを作成する Creating an Application Project Using an Application Template 参照 8. アプリケーションプロジェクトをビルドする Building Projects 参照 9. ユーザーアプリケーションをデバッグする Debugging Projects 参照 10. ユーザーアプリケーションを実行する Running Projects 参照 11. ユーザーアプリケーションをプロファイリングする Software Profiling 参照 12. システムパフォーマンスをモデリングする System Performance Modeling 参照 13. ブートイメージを作成する Creating a Boot Image 参照 これらの手順の詳細は MPSoC PetaLinux Software Development [ 参照 31] を参照してください QEMU の詳細は Zynq UltraScale+ MPSoC QEMU ユーザーガイド (UG1169) [ 参照 8] を参照してください 42

43 第 5 章 : ソフトウェア開発フロー PetaLinux を使用したソフトウェア開発 PetaLinux ツール環境でのソフトウェア開発フローには多くの工程があります デザインフローをわかりやすく整理するため 次の図に PetaLinux 環境でのアプリケーション開発のすべての工程をフローチャートで示します X-Ref Target - Figure 5-3 Petalinux Tools Build Tools GNU Petalinux-Build Yocto Make Debug Tools GDB Petalinux-Boot QEMU OProfile 図 5-3: PetaLinux を使用したソフトウェア開発フロー 43

44 第 5 章 : ソフトウェア開発フロー SDK を使用した Linux アプリケーションの開発 ザイリンクスソフトウェア設計ツールは Linux ユーザーアプリケーションの開発をサポートします このセクションでは Linux アプリケーション開発のフローについて簡単に説明します 次の図に SDK を使用した Linux ユーザーアプリケーションの一般的な開発手順を示します X-Ref Target - Figure 5-4 Invoke SDK Open/ Create SDK workspace Create a Linux application project Build the Linux application project Download Hardware Bitstream to FPGA Boot Linux & setup target connection Profiling Software Application Development Debug Performance met? No No Functionality achieved? Yes Adding an Application to Linux file system Yes X 図 5-4: Linux アプリケーションの開発フロー 44

45 第 5 章 : ソフトウェア開発フロー PetaLinux アプリケーションの開発および実行は 次の手順で行います 1. PetaLinux ツールの作業環境をセットアップする PetaLinux 作業環境のセットアップ 参照 2. PetaLinux プロジェクトまたはユーザーアプリケーションを作成する 新規 PetaLinux プロジェクトの作成 参照 3. ユーザープロジェクトに応じて PetaLinux ツールを設定およびカスタマイズする 4. SDK Linux C/C++ アプリケーションプロジェクトを PetaLinux ワークスペースにインポートする インストール手順 参照 5. PetaLinux イメージを構築する システムイメージのビルド 参照 6. プラットフォーム (QEMU またはボード ) で PetaLinux イメージを実行する ユーザーアプリケーションのビルド 参照 7. PetaLinux イメージをデバッグする デバッグにはいくつかのオプションがある PetaLinux ツール資料リファレンスガイド (UG1144) [ 参照 24] 参照 上記手順の詳細は MPSoC PetaLinux Software Development [ 参照 31] を参照してください QEMU の詳細は Zynq UltraScale+ MPSoC QEMU ユーザーガイド (UG1169) [ 参照 8] を参照してください SDK 機能の詳細および Hello World サンプルデザインを使用した SDK デザインフローは SDK のヘルプ [ 参照 21] を参照してください その他 SDK ユーザーガイド : システムパフォーマンス解析 (UG1145) [ 参照 25] も参照してください アプリケーションプロジェクトを作成する SDK では 基本の Hello World や空のアプリケーション FSBL アプリケーションなど キットに含まれるサンプルプログラム用のテンプレートベースのアプリケーションジェネレーターを提供しています アプリケーションジェネレーターは ザイリンクスの C または C++ アプリケーションウィザードで起動します 空のアプリケーションを作成するか あるいは既存アプリケーションをインポートして移植することも可能です コード開発ツールには エディター 検索 リファクタリングなどのツールのほかに ベースの Eclipse プラットフォームや CDT プラグインで利用できる機能があります アプリケーションを構築する SDK アプリケーションプロジェクトは ユーザー管理 ( ユーザーが makefile を作成 ) または自動管理 (SDK が makefile を作成 ) が可能です ユーザー管理のプロジェクトでは ユーザーが makefile を管理してアプリケーションの構築を開始します 自動管理のプロジェクトでは ソースファイルが追加または削除されたときに SDK が必要に応じて makefile を更新し 変更が保存されて ELF が自動生成されると ソースファイルがコンパイルされます Eclipse CDT の用語では アプリケーションプロジェクトは managed makefile プロジェクトと呼ばれています 可能な場合は SDK が使用するハードウェアプラットフォームおよび BSP に基づいてデフォルトの構築オプション ( コンパイラ リンカー ライブラリパスオプションなど ) を推論して設定します アプリケーションを実行する コンパイルされたアプリケーションをファイルシステムへコピーしてアプリケーションを実行するには SDK で実行コンフィギュレーションを作成します Zynq UltraScale+ MPSoC デバイスプラットフォームで Linux を動作させ Linux 環境に SSH が含まれる場合は sftp を使用して実行コンフィギュレーションが実行可能ファイルをファイルシステムへコピーします アプリケーションとの相互通信には STDIN および STDOUT を使用して端末表示が可能です 45

46 第 5 章 : ソフトウェア開発フロー 次のコマンドシェルを使用してアプリケーションを実行することも可能です 必要に応じて次のコマンドを使用します sftp で実行可能ファイルをコピーする Linux で ssh を用いて実行可能ファイルを実行する PL 内のカスタム IP ドライバーのサポートを追加する SDK では PS 内のペリフェラル用の Linux BSP だけでなく PL 内のカスタム IP 用の Linux BSP も生成できます Linux BSP を生成する場合は SDK がデバイスツリーを生成します これは ブート時にカーネルへ渡されるハードウェアシステムに関する情報を含むデータ構造です デバイスドライバーはカーネルの一部として または個別モジュールとして提供され 利用できるハードウェア機能および有効な機能はデバイスツリーで定義されます さらに ユーザーは動的にロード可能なドライバーを追加できます Linux カーネルはこれらのドライバーをサポートします PL 内のカスタム IP は柔軟に設定可能であり デバイスツリーのパラメーターによって システム内で利用できる IP と各 IP で有効なハードウェア機能の両方が定義されます Linux カーネルおよびブートシーケンスの詳細は 第 3 章 開発ツール を参照してください Linux ファイルシステムにアプリケーションを追加する コンパイル済みのユーザーアプリケーション および必要な共有ライブラリを Linux ファイルシステムに追加するには 次の手順を実行します Linux 環境に SSH が含まれている場合は Zynq UltraScale+ MPSoC デバイスプラットフォーム上で Linux が動作している間に sftp を使用してファイルをコピーできます SDK の場合 リモートシステムエクスプローラー (RSE) プラグインを利用し ドラッグアンドドロップ操作でファイルをコピーできます SDK 以外の場合 ファイルシステムイメージを作成してフラッシュへ書き込む前に ファイルシステムフォルダーへアプリケーションとライブラリを追加します Linux アプリケーション開発の詳細は SDK ヘルプの Creating a Linux Application Project [ 参照 21] を参照してください 46

47 第 6 章 ソフトウェアデザインのパラダイム はじめに ザイリンクス Zynq UltraScale+ MPSoC デバイスアーキテクチャは タスクごとに最適なエンジンを使用するヘテロジニアスマルチプロセッサエンジンをサポートしています これらプロセッサをターゲットとしたソフトウェアの主な開発アプローチには 次のものがあります マルチプロセッサ開発用フレームワーク : Zynq UltraScale+ MPSoC デバイスでの開発に利用できるフレームワークについて説明します 対称型マルチプロセッシング (SMP) : PetaLinux で SMP を使用すると Zynq UltraScale+ MPSoC デバイス向け Linux プラットフォームで SMP を最もシンプルに開発できます 非対称型マルチプロセッシング (AMP) : AMP モードでは どのプロセッサで何を実行するかを厳密に制御できるため 複数のプロセッサエンジンをより効果的に活用できます SMP とは異なり AMP にはさまざまな利用方法があります このセクションでは 複雑度の異なる AMP の 2 つの利用法について説明します 以降のセクションでは これらの各開発手法について詳しく説明します マルチプロセッサ開発用フレームワーク ザイリンクスは ヘテロジニアスプロセッサと FPGA を利用したアプリケーション開発を容易にするため Zynq UltraScale+ MPSoC デバイス向けのフレームワークを複数提供しています これらのフレームワークの説明は次のとおりです ハイパーバイザーフレームワーク : ザイリンクスが提供する Xen ハイパーバイザーは Zynq UltraScale+ MPSoC デバイスの APU における仮想化をサポートするために欠かせないアイテムです 詳細は ハイパーバイザーの使用 を参照してください 認証フレームワーク : Zynq UltraScale+ MPSoC デバイスでは 認証フレームワークの一部として 認証機能と暗号化機能をサポートしています 認証フレームワークの詳細は 第 8 章の ブート時のセキュリティ を参照してください TrustZone フレームワーク : TrustZone テクノロジは 1 つのシステム内でセキュアなプロセスと非セキュアなプロセスを分離し 維持します ザイリンクスは ARM トラステッドファームウェア (ATF) を使用して TrustZone に対応し セキュアプロセスと非セキュアプロセスを分離します ATF の詳細は 第 8 章の ARM トラステッドファームウェア を参照してください 47

48 第 6 章 : ソフトウェアデザインのパラダイム マルチプロセッサ通信フレームワーク : ザイリンクスは 異なるプロセッシングユニット間で互いに通信できるように Zynq UltraScale+ MPSoC デバイス用の OpenAMP フレームワークを提供しています 詳細は ザイリンクス Quick Emulator ユーザーガイド (UG1169) [ 参照 13] を参照してください 電力管理フレームワーク : 電力管理フレームワークにより 異なるプロセッシングユニットで駆動されるソフトウェアコンポーネントがプラットフォーム管理ユニットと通信できるようになります 詳細は Zynq 電力管理フレームワークユーザーガイド (UG1199) [ 参照 14] を参照してください 対称型マルチプロセッシング (SMP) SMP を使用することで 比較的少ない開発工数でマルチプロセッサを用いるソフトウェア開発が可能になります 複数のプロセッサ キャッシュ ペリフェラル割り込み および負荷分散などの複雑な管理のほとんどは Linux などの標準 OS によって実行されます Zynq UltraScale+ MPSoC デバイスの APU にはキャッシュコヒーレントな 4 つのヘテロジニアス ARM Cortex -A53 プロセッサがあり これらは OS (Linux または VxWorks) を使用した SMP モードをサポートしています SMP モードの APU を簡単に利用できるように ザイリンクスおよびパートナーはオペレーティングシステムを提供しています 次の図は 1 つの OS 上で複数のアプリケーションを実行した Linux SMP の例を示しています X-Ref Target - Figure 6-1 Thread 1 Thread 2 Thread n Thread 1 Thread 2 Thread n Application 1 Application n Linux Kernel in SMP APU ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 X 図 6-1: Linux を使用した SMP モードの例 この動作モードは 既存のザイリンクスソフトウェアを使用する開発者が利用可能な Linux アプリケーションコアとの親和性を無視してしまうため 厳しいリアルタイム要件が求められる場合は最適ではありません このため リアルタイムプロセッシングユニット (RPU) は 2 つのキャッシュコヒーレントな ARM Cortex-R5 プロセッサで構成されますが SMP モードで使用されることはほとんどありません 48

49 第 6 章 : ソフトウェアデザインのパラダイム 非対称型マルチプロセッシング (AMP) AMP モードでは どのプロセッサで何を実行するかを厳密に制御できるため 複数のプロセッサエンジンを使用できます SMP とは異なり AMP にはさまざまな利用方法があります このセクションでは 複雑度の異なる AMP の 2 つの利用法について説明します このモードでは 各プロセッサでどのコードを実行するかをソフトウェア開発者が決定してから 各 CPU のソフトウェア実行ファイルを含むブートイメージをコンパイルして生成する必要があります RPU の ARM Cortex-R5 プロセッサでこの AMP モードを使用すると (SMP は Cortex-R5 でサポートされていない ) 非常に厳しいリアルタイム要件を満たすことができます 複数のアプリケーションを個別に開発し プロセッサ間通信 (IPC) オプションを使用してアプリケーションどうしが通信できるようにこれらをプログラムできます この機能の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 13 章 割り込み ) を参照してください この AMP モードは PL の MicroBlaze プロセッサで動作するアプリケーションや APU のプロセッサで動作するアプリケーションにも適用できます 次の図に RPU と PL でアプリケーションを実行し アプリケーション間の通信を使用しない AMP の例を示します X-Ref Target - Figure 6-2 図 6-2: RPU と PL でベアメタルアプリケーションを実行した AMP の例 49

50 第 6 章 : ソフトウェアデザインのパラダイム OpenAMP OpenAMP フレームワークには次のようなメカニズムが用意されています ファームウェアのロードとアンロード 標準 API を使用したアプリケーション間通信 次の図は OpenAMP フレームワークを使用した RPU の OpenAMP 機能と厳密なリアルタイム機能の例を示しています この例では APU で動作する Linux アプリケーションが RPU アプリケーションのロードとアンロードを実行します これにより 開発者は必要に応じて異なる処理に特化したアルゴリズムを RPU の各プロセッシングエンジンにロードし 非常に確定的な性能を得ることができます X-Ref Target - Figure 6-3 Open AMP (APIs for loading/ Unloading firmware, Message Passing) Thread 1 Thread 2 Thread n Thread 1 Thread 2 Thread n RPMsg Application 1 Application n Baremetal Application RPMsg Baremetal Application Linux Kernel in SMP mode RTOS Kernel RTOS Kernel Baremetal Application APU ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 RPU ARM Cortex-R5 ARM Cortex-R5 PL MicroBlaze MicroBlaze X 図 6-3: OpenAMP フレームワークを使用した SMP + AMP の例 OpenAMP フレームワークの詳細は Zynq デバイス用 OpenAMP フレームワークスタートアップガイド (UG1186) [ 参照 13] を参照してください 50

51 第 6 章 : ソフトウェアデザインのパラダイム ハイパーバイザーを使用した仮想化 Zynq UltraScale+ MPSoC デバイスは ARM Cortex-A53 プロセッサ 割り込みコントローラー およびシステムメモリ管理ユニット (SMMU) のハードウェア仮想化拡張機能をサポートしており APU 内で SMP と AMP など さまざまなオペレーティングシステムを柔軟に組み合わせることができます 次の図は 1 つのハイパーバイザー上で Linux などの SMP 対応 OS リアルタイム OS (RTOS) およびベアメタルアプリケーションが協調動作する例を示しています これにより 各アプリケーションはそれぞれの動作モードで個別に開発できます X-Ref Target - Figure 6-4 Thread 1 Thread 2 Application 1 Thread n Application n Task 1 Task 2 Task n Linux Kernel in SMP mode RTOS Kernel Baremetal Application Hypervisor APU ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 ARM Cortex-A53 X 図 6-4: ハイパーバイザーを使用した例 Xen ハイパーバイザーなどのハイパーバイザーの使用方法の詳細は MPSoC Xen Hypervisor のウェブサイト [ 参照 37] を参照してください 51

52 第 6 章 : ソフトウェアデザインのパラダイム ハイパーバイザーの使用 Xen は ザイリンクス Zynq UltraScale+ MPSoC デバイスの Xen オープンソースハイパーバイザー用ポートです Xen ハイパーバイザーを使用すると 1 つのコンピューティングプラットフォーム上で複数のオペレーティングシステムを実行できます Xen ハイパーバイザーはハードウェア上で直接動作し CPU メモリ 割り込みを管理します このハイパーバイザー上で複数の OS を実行できます これらの OS をドメインまたは仮想マシン (VM) と呼びます Xen ハイパーバイザーは 1 つのドメイン ( ドメイン 0) と 1 つまたは複数のゲストドメインを制御します 制御ドメインには 次のような特権機能があります ハードウェアへの直接アクセス システムの I/O 機能へのアクセス処理 その他の仮想マシンとの相互作用 また 外部からアクセス可能な制御インターフェイスもあり このインターフェイスを利用してシステムを制御します 各ゲストドメイン上ではそれぞれの OS とアプリケーションを実行します ゲストドメインはハードウェアから完全に隔離されます Xen ハイパーバイザーを使用して複数の OS を実行するには ホスト OS をセットアップして 1 つまたは複数のゲスト OS を追加します 注記 : Xen ハイパーバイザーは PetaLinux ツール内で選択できるコンポーネントですが その他のワークフローを使用する場合はザイリンクス GIT サーバーからもダウンロード可能です ザイリンクスが提供する Linux および Xen ソフトウェアを利用することで 独自の Linux ゲストコンフィギュレーションを構築できます Linux 以外のゲスト OS を構築する場合は サードパーティのソフトウェアと技術が必要です 詳細は PetaLinux の製品ページ [ 参照 2] を参照してください 52

53 第 7 章 システムブートおよびコンフィギュレーション はじめに Zynq UltraScale+ MPSoC デバイスは QSPI フラッシュ SD カード USB デバイスファームウェアアップグレード (DFU) ホスト NAND フラッシュドライブなどからのブートをサポートしています この章では セキュアモードと非セキュアモードの両方において各種デバイスからのブートプロセスについて説明します ブートフロー Zynq UltraScale+ MPSoC アーキテクチャには セキュアブートと非セキュアブートの 2 つのフローがあります 以降のセクションでは 各種プロセッサを立ち上げて必要なブートタスクを実行するシーケンスについて説明します 注記 : 各セクションの図では 必須コンポーネントとオプションコンポーネントをすべて含むブートフロー全体を示しています 非セキュアブートフロー 次の図に Zynq UltraScale+ MPSoC デバイスの非セキュアブートフローの例を示します この図では 各ブートエンティティごとに色分けして表示しています X-Ref Target - Figure 7-1 PMU Release CSU Power Monitoring CSU Load FSBL Tamper Monitoring RPU FSBL APU ATF U-Boot Linux Time 図 7-1: 非セキュアブートフローの例 53

54 第 7 章 : システムブートおよびコンフィギュレーション 図 1 のように 非セキュアブートモードでは PMU はコンフィギュレーションセキュリティユニット (CSU) のリセットを解放後 PMU サーバーモードに移行して電力を監視します PMU によってリセットから解放されると CSU は FSBL を OCM にロードします この例では FSBL は RPU に U-Boot および Linux は APU にロードされます FSBL は RPU または APU のいずれかにロードできます その他のブートコンフィギュレーションでは RPU は APU と完全に独立して起動および動作させることができます ( その逆も同様 ) APU に FSBL がロードされた場合 通常は U-Boot などの SSBL ( 第 2 段階ブートローダー ) が実行され Linux などの OS がロードされます RPU では FSBL の実行はソフトウェアアプリケーションに渡されます その後 Linux が実行可能なソフトウェアをロードします 注記 : 対称型マルチプロセッシング (SMP) モードでは OS が複数の Cortex -A53 プロセッサを管理します セキュアブートフロー 次の図に セキュアブートフローの例を示します この図では 各ブートエンティティごとに色分けして表示しています X-Ref Target - Figure 7-2 PMU Release CSU Power Monitoring CSU Load FSBL Tamper Monitoring RPU FSBL APU ATF U-Boot Linux Time セキュアブートモードでは PMU はコンフィギュレーションセキュリティユニット (CSU) のリセットを解放後 PMU サーバーモードに移行して電力を監視します PMU によってリセットから解放されると CSU は FSBL またはユーザーアプリケーションによって認証が要求されているかを確認します CSU は次を実行します 図 7-2: セキュアブートフローの例 認証チェックを実行し このチェックにパスした場合のみ次へ進みます そして イメージに暗号化されたパーティションがあるかどうかをチェックします 暗号化されたパーティションを検出した場合 CSU は復号化を実行し FSBL を OCM にロードします CSU の詳細は コンフィギュレーションセキュリティユニット を参照してください APU では FSBL は ATF に渡されます ATF はそれを受けて U-Boot を実行し Linux などの OS をロードします その後 Linux が実行可能なソフトウェアをロードします 同様に FSBL はロードする各パーティションの認証および暗号化をチェックします 認証および 暗号化されていた場合は復号化に問題がないことが確認されたパーティションのみが FSBL によってロードされます 54

55 第 7 章 : システムブートおよびコンフィギュレーション ブートイメージの生成 SDK に含まれる Bootgen ユーティリティを使用すると 開発したアプリケーションを Zynq UltraScale+ MPSoC デバイスでブートするのに適した 1 つのブートイメージファイルが生成されます Bootgen は 必要なブートヘッダーを構築して後続パーティションを定義するテーブルを追加し パーティションの入力データファイル (ELF ファイル FPGA ビットストリーム その他のバイナリファイル ) を処理することによってブートイメージを生成します 各パーティションに対して特定のデスティネーションメモリアドレスを割り当てたり アライメント要件を与える機能があります また 各パーティションに対する暗号化 認証およびチェックサムをサポートします このユーティリティは ブートイメージフォーマット (BIF) ファイルというコンフィギュレーションファイル (*.bif) で駆動されます 重要 :.bif ファイルには ATF より上位のビットストリームを含める必要があります 上級認証フローでは Bootgen を使用してオフラインで符号化できる中間のハッシュファイルを出力できます それ以外の場合 Bootgen は提供されたプライベートキーを使用し ブートイメージ内に含まれる認証証明 (Authentication certificates) を符号化します ブートイメージをビルドするには 次の手順を実行します 1. BIF ファイルを作成します 2. Bootgen ユーティリティを実行してバイナリファイルを作成します 3. (QEMU の場合 ): バイナリファイルをブートデバイスの種類に応じたイメージフォーマットに変換します Bootgen の詳細は 第 15 章 Bootgen イメージの生成 を参照してください ブートモード 利用可能なブートモードの概要は 表 7-4 を参照してください 利用可能なブートモードの一覧は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション ) を参照してください 55

56 第 7 章 : システムブートおよびコンフィギュレーション QSPI24 ブートモード QSPI24 ブートモードは次の機能をサポートします シングル QSPI フラッシュメモリ (QSPI24) で x1 x2 および x4 読み出しモード デュアル QSPI で x8 読み出しモード マルチブートのイメージ検索 BSP ドライバー用 I/O モード (FSBL ではサポートされない ) bootrom が x8 モードで最初の 256Mb を検索します QSPI24 ブートモード (QSPI24 デバイスが 128Mb 超 ) でマルチブートを使用する場合は 128Mb 以下のメモリに収まるように複数イメージを配置します 次の図に QSPI24 モードでの Linux のブート例を示します X-Ref Target - Figure 7-3 FSBL R5 Image A53 Image Key SBL Bootgen Tool SDK Boot.mcs Boot Header FSBL SBL R5 Image A53 Image Flash Writer JTAG Key Board Flash efuse QSPI Boot Pins Zynq UltraScale+ MPSoC.bif QSPI24 ブートイメージを作成するには Bootgen に次のファイルを入力します FSBL ELF U-Boot などの SSBL ( 第 2 段階ブートローダー ) または Cortex-R5/Cortex-A53 アプリケーション ELF 認証 / 暗号キー ( オプション ) 図 7-3: QSPI24 モードでのブート 認証 / 暗号化の詳細は 第 8 章 セキュリティ機能 を参照してください Bootgen によって boot.mcs および boot.bin バイナリファイルが生成されたら フラッシュライターを使用してこれらを QSPI24 フラッシュに書き込みます MCS は Intel HEX フォーマットファイルで 信頼性を高めるためにチェックサムを含んでいます 重要 : SD1 からブートする場合はブートピンを 0x5 に設定する必要があります SD0 からブートする場合はブートピンを 0x3 に設定 レベルシフターを用いた SD からブートする場合はブートピンを 0xE に設定します 56

57 第 7 章 : システムブートおよびコンフィギュレーション QSPI32 ブートモード QSPI32 ブートモードは次の機能をサポートします シングル QSPI フラッシュメモリ (QSPI32) で x1 x2 および x4 読み出しモード デュアル QSPI で x8 読み出しモード マルチブートのイメージ検索 BSP ドライバー用 I/O モード (FSBL ではサポートされない ) bootrom が x8 モードで最初の 256Mb を検索します QSPI32 ブートモード (QSPI32 デバイスが 128Mb 超 ) でマルチブートを使用する場合は 128Mb 以下のメモリに収まるように複数イメージを配置します 次の図に QSPI32 モードでの Linux のブート例を示します X-Ref Target - Figure 7-4 FSBL R5 Image A53 Image Key Bootgen Tool SDK Boot.mcs Boot Header FSBL SBL RS Image Flash Writer JTAG Flash Board QSPI 0010 Boot Pins Zynq UltraScale+ MPSoC SBL A53 Image Key efuse.bif QSPI32 ブートイメージを作成するには Bootgen に次のファイルを入力します FSBL ELF U-Boot などの SSBL ( 第 2 段階ブートローダー ) または Cortex-R5/Cortex-A53 アプリケーション ELF 認証 / 暗号キー ( オプション ) 図 7-4: QSPI32 モードでのブート 認証 / 暗号化の詳細は 第 8 章 セキュリティ機能 を参照してください Bootgen によって boot.mcs および boot.bin バイナリファイルが生成されたら フラッシュライターを使用してこれらを QSPI32 フラッシュに書き込みます MCS は Intel HEX フォーマットファイルで 信頼性を高めるためにチェックサムを含んでいます 57

58 第 7 章 : システムブートおよびコンフィギュレーション SD ブートモード SD ブート ( バージョン 3.0) は次の機能をサポートしています FAT 16/32 ファイルシステムによるブートイメージの読み出し マルチブートのイメージ検索 マルチブートの最大ファイル数は 8,192 次の図に SD モードでの Linux のブート例を示します X-Ref Target - Figure 7-5 FSBL SDK Boot.bin SD card Boot Mode pins U-Boot KEY A53 Image KEY Bootgen Tool Kernel Image FAT 32 Zynq UltraScale+ MPSoC Device tree file.bif Root file system EXT 3 File system Petalinux SDK Board SD ブートイメージを作成するには Bootgen に次のファイルを入力します FSBL ELF Cortex-R5/Cortex-A53 アプリケーション ELF 認証 / 暗号キー ( オプション ) Bootgen からは boot.bin バイナリファイルが生成されます この boot.bin ファイルを SD カードリーダーを使用して SD カードに書き込みます PetaLinux で 次を実行します 1. Linux カーネルイメージ デバイスツリーファイル およびルートファイルシステムを構築します 2. これらのファイルを SD カードにコピーします 図 7-5: SD モードでのブート これで フォーマット済み SD カードの FAT32 パーティションに boot.bin カーネルイメージ およびデバイスツリーファイルが格納され EXT 3 パーティションにルートファイルシステムが格納されます 重要 : QEMU の SD からブートするには ブートピンを 0x5 に設定する必要があります 58

59 第 7 章 : システムブートおよびコンフィギュレーション emmc18 ブートモード emmc18 ブート ( バージョン 4.5) は次の機能をサポートしています FAT 16/32 ファイルシステムによるブートイメージの読み出し マルチブートのイメージ検索 マルチブートの最大ファイル数は 8,192 次の図に emmc18 モードでの Linux のブート例を示します X-Ref Target - Figure 7-6 FSBL SDK Boot.bin emmc18 card Boot Mode pins U-Boot KEY A53 Image KEY Bootgen Tool Kernel Image FAT 32 Zynq UltraScale+ MPSoc Device tree file.bif Root file system EXT 3 File system PetaLinux SDK Board emmc18 ブートイメージを作成するには Bootgen に次のファイルを入力します FSBL ELF Cortex-R5/Cortex-A53 アプリケーション ELF 認証 / 暗号キー ( オプション ) Bootgen からは boot.bin バイナリファイルが生成されます この boot.bin ファイルを emmc18 カードリーダーを使用して emmc18 カードに書き込みます PetaLinux で 次を実行します 図 7-6: emmc18 モードでのブート Linux カーネルイメージ デバイスツリーファイル およびルートファイルシステムを構築します これらのファイルを emmc18 カードにコピーします これで フォーマット済み emmc18 カードの FAT32 パーティションに boot.bin カーネルイメージ およびデバイスツリーファイルが格納され EXT3 パーティションにルートファイルシステムが格納されます 59

60 第 7 章 : システムブートおよびコンフィギュレーション NAND ブートモード NAND ブートは 8 ビット幅でのブートイメージ読み出しとマルチブートのイメージ検索をサポートします 次の図に NAND モードでの Linux のブート例を示します X-Ref Target - Figure 7-7 SDK Board Boot.bin Boot Pins FSBL R5 Image A53 Image Bootgen Tool Boot Header FSBL SBL NAND Converter NAND image Flash Writer JTAG Flash NAND Zynq UltraScale+ MPSoC Device Key R5 Image Key efuse SBL A53 Image.bif NAND ブートイメージを作成するには Bootgen に次のファイルを入力します FSBL ELF Cortex-R5 アプリケーション ELF/Cortex-A53 アプリケーション ELF 認証 / 暗号キー ( オプション ) 図 7-7: NAND モードでのブート Bootgen からは boot.bin バイナリファイルが生成されます この NAND ブータブルイメージを フラッシュライターを使用して NAND フラッシュに書き込みます 重要 : NAND からブートするには ブートピンを 0x4 に設定する必要があります JTAG ブートモード PS に必要なソフトウェアイメージと PL に必要なハードウェアイメージは JTAG を使用して個別にダウンロードできます JTAG ブートモードの設定は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション ) を参照してください 重要 : JTAG モードではセキュアブートはサポートされません 60

61 第 7 章 : システムブートおよびコンフィギュレーション USB ブートモード USB ブートモードは USB 2.0 をサポートします マルチブート イメージのフォールバック XIP はサポートされません セキュアモードと非セキュアの両方のブートモードをサポートします USB ブートモードは DDR なしのシステムではサポートされません USB ブートモードはデフォルトで無効となっています d 表 7-1: USB ブートモードの詳細モードピン MIO ピン非セキュアセキュア符号モード 0x7 MIO[63:52] 許可許可許可スレーブ USB ブートモードには dfu-utils がインストールされたホストが必要です このホストとデバイスを USB 3.0 ケーブルで接続します ホストには bootrom コード用の boot.bin (fsbl.elf しか含まれない ) が 1 つ FSBL 用の別の boot_all.bin が含まれている必要があります USB ブートモードでボードの電源を入れたら 次のコマンドを実行します Linux の場合 : dfu-util -D boot.bin ファイルをデバイスにダウンロードし その後 FSBL を実行します dfu-util -D boot_all.bin ファイルをデバイスにダウンロードします FSBL は必要な処理を実行します Windows の場合 : sudo dfu-util.exe -D boot.bin ファイルをデバイスにダウンロードし その後 FSBL を実行します sudo dfu-util.exe -D boot_all.bin ファイルをデバイスにダウンロードします FSBL は必要な処理を実行します boot.bin および boot_all.bin のサイズは それぞれ利用可能な OCM と DDR のサイズに制限されます 61

62 第 7 章 : システムブートおよびコンフィギュレーション ブートフローの詳細 Zynq UltraScale+ MPSoC デバイスのプラットフォーム管理ユニット (PMU) は 主要なブート前タスクを処理します ブート中にデバイスのデフォルト電源ステートの設定 RAM の初期化 そしてメモリとレジスタのテストを実行するために PMU ROM は ROM から実行します PMU は これらのタスクを実行した後にシステムの制御をコンフィギュレーションセキュリティユニット (CSU) に渡して サービスモードへ遷移します このモードの PMU は レジスタインターフェイスを介してシステムからの割り込み要求に対応したり 専用 I/O を介してハードウェアからの割り込み要求に対応してプラットフォーム管理サービスを実行します プリブートシーケンス 次の表に プリブートシーケンスで PMU が実行するタスクを示します 表 7-2: プリブートシーケンス プリブートタスク CSU のリセットが解放されると同時に CSU ブート ROM を実行し 次のシーケンスを実行します 1. ブートモードレジスタを読み出してブートモードを判定します ブートモードレジスタには POR ( パワーオンリセット ) 時のブートモードピンストラッピングが格納されています 2. OCM を初期化します 0 MicroBlaze プロセッサを初期化する 主なステートをキャプチャする 3. ブートヘッダーを読み出します 4. FSBL ブートイメージの認証が必要な場合 CSU ブート ROM が認証プロセスを実行します - FSBL が認証テストに合格すると CSU ブート ROM は FSBL が暗号化されているかどうかをチェックします - FSBL が暗号化されている場合 CSU ブート ROM は FSBL を復号化してから OCM にロードします 図 7-8 に 詳細なブートフローを示します 説明 1 LPD および FPD をスキャンおよびクリアする 2 システムモニターを初期化する 3 MBIST クロックに使用される PLL を初期化する 4 PMU-RAM をすべて 0 に設定する 5 PLL を検証する MBIST クロックを設定する 6 電源を検証する 7 FPD メモリを修復する ( 必要な場合 ) 8 LPD と FPD をすべて 0 に設定し メモリセルフテストを初期化する 9 無効化されたすべての IP をパワーダウンする 10 CSU を解放 またはエラーステートに遷移する 11 サービスモードに遷移する 62

63 第 7 章 : システムブートおよびコンフィギュレーション X-Ref Target - Figure 7-8 \ Power ON PMU PMU releases CSU Reset Read Boot Mode Pins CSU Read Boot Header from the Boot image Is FSBL Authenticated? YES Check for Authentication NO Decrypt FSBL YES Is FSBL Encrypted? YES Authentication Test passed? NO Fallback boot Decryption Fails? NO Load FSBL to OCM YES Fallback boot FSBL configures the PS FSBL configures PL with the bitstream APU/RPU FSBL loads the RPU software FSBL loads the APU software FSBL Handoff to APU software X 図 7-8: 詳細なブートフローの例 63

64 第 7 章 : システムブートおよびコンフィギュレーション FSBL コンパイルフラグの設定 コンパイルフラグは 次の図のように SDK FSBL プロジェクトで [C/C++ Build] の [Settings] を使用して設定できます 注記 : これらのフラグを含めるために FSBL ソースファイルやヘッダーファイルを変更する必要はありません X-Ref Target - Figure 7-9 次の表に FSBL コンパイルフラグを示します 表 7-3: FSBL コンパイルフラグ 図 7-9: FSBL デバッグフラグ フラグ FSBL_DEBUG FSBL_DEBUG_INFO FSBL_DEBUG_DETAILED FSBL_NAND_EXCLUDE NAND FSBL_QSPI_EXCLUDE QSPI FSBL_SD_EXCLUDE SD FSBL_RSA_EXCLUDE RSA FSBL_AES_EXCLUDE AES FSBL_BS_EXCLUDE PL FSBL_SHA2_EXCLUDE SHA2 説明基本情報およびエラーがあればエラーステータスを出力する 基本情報のほかに フォーマット指定子付きの出力を有効化する 転送されたすべてのデータを含む情報を出力する NAND サポートコードを除外する QSPI サポートコードを除外する SD サポートコードを除外する 認証コードを除外する 復号化コードを除外する ビットストリームコードを除外する SHA2 コードを除外する 64

65 第 7 章 : システムブートおよびコンフィギュレーション 表 7-3: FSBL コンパイルフラグ ( 続き ) フラグ FSBL_WDT_EXCLUDE WDT FSBL_USB_EXCLUDE 説明 WDT サポートコードを除外する USB コードを除外する これは デフォルトで 1 に設定されている 0 にセットすると USB ブートモードが有効になる フォールバックおよびマルチブートフロー Zynq UltraScale+ MPSoC デバイスでは CSU ブート ROM がマルチブートおよびフォールバックブートイメージ検索をサポートしています これは コンフィギュレーションセキュリティユニット (CSU) のブート ROM がブートデバイス内を検索してロードすべき有効なイメージを検出するものです このシーケンスは次のとおりです bootrom はフラッシュの 32KB オフセットで有効なイメージ ID 文字列 ( イメージ ID XLNX) を検索します 有効な ID を検出すると bootrom はヘッダーのチェックサムを検証します チェックサムが有効なら bootrom はそのイメージをロードします これは フラッシュ内に複数のイメージが含まれることを見込んでいます マルチブートの場合 : FSBL またはユーザーアプリケーションがブートイメージ検索を開始して別のブートイメージを選択する必要があります このイメージ検索を開始するには FSBL またはユーザーアプリケーションでマルチブートオフセットを更新して目的のブートイメージを指し示すようにし CRL_APB レジスタに書き込んでソフトリセットを生成します 図 7-10 に フォールバックの例およびマルチブートフローを示します X-Ref Target - Figure 7-10 MultiBoot Offset=1 MultiBoot Offset=2 MultiBoot Offset=3 MultiBoot Offset=4 図 7-10: マルチブートフロー ( 左側 ) フォールバックの例 ( 右側 ) 65

66 第 7 章 : システムブートおよびコンフィギュレーション 注記 : セキュアブートと非セキュアブートの両方に同じフローを適用できます フォールバックブートフローの例では 次のシーケンスが実行されます CSU ブート ROM は最初に 0x000_0000 にあるブートイメージをロードします このイメージが破損しているか復号化 / 認証に失敗した場合 CSU ブート ROM はマルチブートオフセットを 1 つインクリメントして 0x000_8000 (32KB オフセット ) で有効なブートイメージを検索します このオフセットで有効な ID 値を検出できない場合 CSU ブート ROM はマルチブートオフセットをさらに 1 つインクリメントして次の 32KB 境界アドレスで有効なブートイメージを検索します CSU ブート ROM は 検索可能な範囲内で有効なブートイメージが検出されるまでこの動作を繰り返します この例では 次のイメージは 0x002_0000 にあり マルチブートオフセットは 4 です このマルチブートフローの例でアドレス 0x002_0000 にある 2 番目のイメージをロードするには FSBL またはユーザーアプリケーションでマルチブートオフセットを 4 に設定します マルチブートオフセットを更新したら システムのソフトリセットを生成します 次の表に 各ブートデバイスのイメージ検索範囲を示します 表 7-4: 各ブートデバイスのイメージ検索範囲 ブートデバイス QSPI シングル (24 ビット ) QSPI デュアル (24 ビット ) QSPI シングル (32 ビット ) QSPI デュアル (32 ビット ) NAND SD/eMMC USB イメージ検索範囲 16MB 32MB 256MB 512MB 128MB 8,191 のブートファイル N/A 66

67 第 8 章 セキュリティ機能 はじめに この章では アプリケーションのブート時および実行時のセキュリティを確保するために利用できる Zynq UltraScale+ MPSoC デバイスの機能について説明します セキュアブートメカニズムの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション ) を参照してください システム保護ユニット (SPU) は Zynq UltraScale+ MPSoC デバイス上で実行するアプリケーションの実行時のセキュリティを確保するために次のハードウェア機能を提供します ザイリンクスメモリ保護ユニット (XMPU) ザイリンクスペリフェラル保護ユニット (XPPU) システムメモリ管理ユニット (SMMU) A53 メモリ管理ユニット R5 メモリ保護ユニット ブート時のセキュリティ このセクションでは 認証および暗号化用のさまざまなブートイメージフォーマットについて詳しく説明します 暗号化 Zynq UltraScale+ MPSoC デバイスにはユーザーブートイメージの機密性をサポートする AES-GCM ハードウェアエンジンがあり これを使用してブート後にユーザーデータを暗号化 / 復号化することも可能です AES 暗号エンジンは さまざまなキーソースへアクセスできます 表 8-1 に これらのキーソースについて説明します 表 8-1: キーの種類キー名説明バッテリバックアップ式 RAM (BBRAM) キーは 256 ビットの SRAM アレイにテキスト形式で格納されます バッテリ寿命を延長させるために SRAM アレイは VCCAUX BBRAM に電源が供給されるとこの電源から電力が供給されます それ以外の場合 SRAM アレイは VCCBAT から電力が供給されます ブートキー使用中は ブートキーレジスタに復号化されたキーが保持されます 67

68 第 8 章 : セキュリティ機能 表 8-1: キーの種類 (Cont d) キー名 efuse ファミリ 操作 PUF KEK キーアップデートレジスタ 説明 efuse キーは efuse に格納され テキスト形式 難読化 ( 例 : ファミリキーで暗号化 ) または PUF KEK を使用して暗号化できます ファミリキーは デバイスにハードコーディングされた固定の AES キー値です Zynq UltraScale+ MPSoC ファミリのすべてのデバイスで同じキーが使用されます このキーは 難読化キーを復号化するために CSU ROM によってのみ使用されます 復号化された難読化キーを使用して ブートイメージを復号化します 難読化キーは efuse または認証されたブートヘッダーに格納されます ファミリキーは すべてのデバイスで同じであるため セキュリティメカニズムの相対的な強さを反映させるために暗号化ではなく難読化された文字列が使用されています 操作キーを取得するには ほかのデバイスのキーソースから得られるプレーンテキストキーを使用してセキュアヘッダーを復号化します セキュアブートの場合 このキーはオプションです 操作キーは ブートヘッダーに指定され デバイスキーの使用を最小限に抑えて攻撃への露出を制限します PUF KEK は PUF で生成されるキー暗号化用のキーです ユーザーが提供するキーソース ブート後 ハードマクロとして提供されている AES アクセラレータでユーザーが選択したキーを使用できます イメージを暗号化するにはレッドキーを使用します ブートファイル (BOOT.bin) の生成時に レッドキーと初期化ベクター (IV) を.nky ファイル形式で Bootgen に提供する必要があります BBRAM レッドキーを使用する BIF ファイル 次の BIF ファイルの例は BBRAM に格納されたレッドキーを示しています the_rom_image: { [aeskeyfile] bbram.nky [fsbl_config] a5x_x64 [keysrc_encryption] bbram_red_key [bootloader, encryption=aes] ZynqMP_Fsbl.elf [destination_cpu = a53-0, encryption=aes] App_A53_0.elf } efuse レッドキーを使用する BIF ファイル 次の BIF ファイルの例は efuse に格納されたレッドキーを示しています the_rom_image: { [aeskeyfile] efuse.nky [fsbl_config] a5x_x64 [keysrc_encryption] efuse_red_key [bootloader, encryption=aes] fsbl.elf [destination_cpu = a53-0, encryption=aes] App_A53_0.elf } 68

69 第 8 章 : セキュリティ機能 操作キーを使用する BIF ファイル 操作キーを使用して Bootgen でブートイメージを生成する場合 ユーザーは操作キーのほかにレッドキーと IV (.nky ファイル ) をツールに提供する必要があります Bootgen は 操作キーをヘッダーに配置し デバイスのレッドキーを使用してこれを暗号化します その結果 暗号化された安全なヘッダー が構築されます この方法の主なメリットは デバイスキーの使用を最小限に抑えて攻撃への露出を制限できることです 詳細は Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル [ 参照 10] の Minimizing Use of the AES Boot Key (OP Key Option) ( 英語版のみ ) を参照してください the_rom_image: { [aeskeyfile] bbram.nky [fsbl_config] a5x_x64, opt_key [keysrc_encryption] bbram_red_key [bootloader, encryption=aes] ZynqMP_Fsbl.elf [destination_cpu = a53-0, encryption=aes] App_A53_0.elf } efuse に格納されたブラックキーを使用する BIF ファイル 使用しないデバイスキーを暗号化して格納しておく場合には PUF (Physical Unclonable Function) を利用できます つまり PUF で生成された暗号キー PUF KEK ( キー暗号化のキー ) を使用して 実際のレッドキーを暗号化します デバイスは実際のレッドキーを得るためにブラックキーを復号化する必要があるため ユーザーは Bootgen に適切な入力を与える必要があります ブラックキーは efuse またはブートヘッダーのいずれかに格納できます 次に示す例では efuse に格納されたブラックキーを示しています the_rom_image: { [pskfile]psk.pem [sskfile]ssk.pem [aeskeyfile]red.nky [keysrc_encryption] efuse_blk_key [fsbl_config]a53_x64, shutter=0x e [auth_params] ppk_select=0 [bootloader, encryption = aes, authentication = rsa]fsbl.elf [bh_key_iv] black_key_iv.txt } ブートヘッダーに格納されたブラックキーを使用する BIF ファイル 次の BIF ファイルの例では ブートヘッダーに格納されたブラックキーの暗号化を示しています the_rom_image: { [aeskeyfile] redkey.nky [keysrc_encryption] bh_blk_key [bh_keyfile] blackkey.txt [bh_key_iv] black_key_iv.txt [fsbl_config] a5x_x64, pufhd_bh, puf4kmode, shutter=0x e, bh_auth_enable [pskfile] PSK.pem [sskfile] SSK.pem [bootloader,authentication=rsa, encryption=aes ]fsbl.elf [puf_file]hlprdata4k.txt } 注記 : ブラックキーの暗号化を使用する場合は ブートイメージの認証が必須です 69

70 第 8 章 : セキュリティ機能 認証 Zynq UltraScale+ MPSoC が備える SHA ハードウェアアクセラレータは SHA-3 アルゴリズムを実装しており 384 ビットのダイジェストを生成します これを RSA アクセラレータと共に使用することでイメージの認証が可能になり イメージの復号化には AES-GCM を使用します これらのブロック (SHA-3/384 RSA および AES-GCM) は ハードマクロとして提供されており 暗号インターフェイスブロック (CIB) の一部となっています 認証フローでは FSBL を生データとして扱います イメージが暗号化されているかどうかは無視されます キーにはプライマリキー (PK) とセカンダリキー (SK) の 2 つのレベルがあります 各キーには 秘密キーと公開キーの 2 つの補足要素があります PK にはプライマリ公開キー (PPK) とプライマリ秘密キー (PSK) があります SK にはセカンダリ公開キー (SPK) とセカンダリ秘密キー (SSK) があります CIB 内のハード RSA ブロックは RSA で求められる大規模な計算を高速化するためのモンゴメリ乗算器です ハードウェアアクセラレータはシグネチャ生成や検証に使用できます ROM コードは シグネチャ生成のみをサポートします 秘密キーは 証明を生成する場合のシグネチャ生成ステージでのみ使用されます 重要 : シグネチャ生成はデバイスで実行されるのではなく ブートイメージの準備中にソフトウェアで実行されます 認証証明のフォーマットは 第 15 章の 認証証明 を参照してください PPK と SPK の 2 つのキーでパーティションを認証します PSK と SSK を使用してパーティションを符号化します 各シグネチャ (SPK ブートヘッダー ブートイメージ ) の式を次に示します SPK シグネチャ 次の計算によって 512 バイトの SPK シグネチャが生成されます SPK シグネチャ = RSA (PSK パディング SHA(SPK+ auth_header)) ブートヘッダーシグネチャ 次の計算によって 512 バイトのブートヘッダーシグネチャが生成されます ブートヘッダーシグネチャ = RSA (SSK パディング SHA( ブートヘッダー )) ブートイメージシグネチャ 次の計算によって 512 バイトのブートイメージシグネチャが生成されます BI シグネチャ = RSA(SSK パディング SHA(PFW + FSBL + 認証証明 )) Bootgen は RSA シグネチャの生成のみをサポートします 係数 累乗 および事前計算された R^2 Mod N が必要になります ソフトウェアは RSA 暗号の復号化でのみサポートされています シグネチャ RSA エンジンの復号化では 係数 累乗 および事前計算された R^2 Mod N が必要です これらはすべてキーから抽出されます 70

71 第 8 章 : セキュリティ機能 SHA3 ブートヘッダー認証と PPK0 を使用する BIF ファイル 次の BIF ファイルの例は BH RSA オプションをサポートしています このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 12 章 セキュリティ ) で説明するこのオプションは システムがフィールド展開される前の統合およびテストをサポートします BIF ファイルは SHA3 ブートヘッダー認証用であり 実際の PPK ハッシュ値は efuse に格納された値と比較されません the_rom_image: { [fsbl_config] a5x_x64, bh_auth_enable [auth_params] ppk_select=0; spk_id=0x [pskfile] primary_4096.pem [sskfile] secondary_4096.pem [bootloader, authentication=rsa] fsbl.elf [pmufw_image, authentication=rsa] xpfw.elf } SHA3 efuse RSA 認証と PPK0 を使用する BIF ファイル 次の BIF ファイルの例は PPK0 と SHA3 を使用する efuse RSA 認証を示しています the_rom_image: { [fsbl_config]a53_x64 [auth_params]ppk_select=0;spk_id=0x584c4e58 [pskfile]psk.pem [sskfile]ssk.pem [bootloader, authentication = rsa]zynqmp_fsbl.elf [destination_cpu = a53-0, authentication = rsa]application.elf } 外部メモリを使用するビットストリーム認証 ビットストリームの認証は その他のパーティションとは異なります FSBL は OCM 内にすべて含めることが可能であるため デバイス内部で認証 / して復号化できます ビットストリームの場合は ファイルサイズが非常に大きいためデバイス内にすべてを含めることができず 外部メモリを使用する必要があります 外部メモリを使用すると 攻撃者がこの外部メモリに侵入する可能性が高くなるため セキュリティ管理という課題が生じます 次のセクションでは 外部メモリを使用する場合にビットストリームを安全に認証する方法について説明します Bootgen ビットストリームの認証が要求されると Bootgen はビットストリーム全体を 8MB ブロックに分割し 各ブロックに認証証明書が与えられます ビットストリームが 8MB の倍数でない場合は 最後のブロックに残りのビットストリームデータが含まれます 71

72 第 8 章 : セキュリティ機能 X-Ref Target - Figure 8-1 Boot Header FSBL FSBL AC 8MB block 1 8MB block 2. PL Bitstream Data.. Whole Bitstream LastBlock(remaining) Block1 AC Block2 AC... Authentication certificates of bitstream Last Block AC 図 8-1: ビットストリームブロック X 認証と暗号化の両方が有効の場合は 最初にビットストリームの暗号化が実行されます その後 Bootgen は暗号化されたデータをブロックに分割して 各ブロックに認証証明書を提供します ソフトウェア ビットストリームパーティションを安全に認証するために FSBL は ATF セクションの OCM メモリを使用して フラッシュまたは DDR からビットストリームをチャンクとしてコピーします したがって ブートイメージの作成中 ビットストリームパーティションは ATF パーティションより前に配置される必要があります ATF パーティションより後に配置されると ビットストリームパーティションが処理されるときに ATF メモリが上書きされてしまいます ソフトウェアは 次の手順に従ってビットストリームを認証します 1. FSBL は OCM 内に 2 つのバッファーを持ちます 1 つはバッファーサイズ 56KB の ReadBuffer もう 1 つは 8MB ブロックの各 56 KB 用に計算された中間ハッシュを格納する HashsOfChunks[] です 2. システムで DDR が有効の場合は DDR の方が高速アクセスが可能なため すべてのビットストリームパーティション ( ビットストリームと認証証明 ) をフラッシュデバイスから DDR にコピーします 3. 最初の 8MB ブロックから 56KB チャンクデータを ReadBuffer へコピーします 4. 56KB のハッシュ値を計算して HashsOfChunks に格納します 72

73 第 8 章 : セキュリティ機能 5. 8MB ブロックすべてが完了するまで前の手順を繰り返します 注記 : 性能を考慮して 56KB を使用しますが 実際は任意のサイズを選択可能です 6. ビットストリームを認証します 7. 認証に成功すると DDR/ フラッシュにある最初のブロックの始めから ReadBuffer へ 56KB データをコピーし ハッシュ値を計算して HashsOfChunks に格納されているハッシュ値と比較します 8. ハッシュ値の比較に問題がない場合は DMA または AES ( 暗号化が有効の場合 ) を使用してデータを PCAP へ送信します 9. 8MB ブロックすべてが完了するまで前の 2 つの手順を繰り返します 10. ビットストリームのすべてのブロックに対して一連のプロセスを繰り返します 注記 : いかなる段階でもエラーが生じた場合には PL がリセットされて FSBL は終了します セキュアストリームスイッチを設定することで ビットストリームは CSU DMA 経由で PCAP へ直接転送されます DDR システムの場合 暗号化されたすべてのビットストリームは DDR へコピーされます DDR をサポートしていないシステムの場合 復号化されたビットストリームは OCM (ATF セクション ) にチャンクとしてコピーされます 注記 : ザイリンクスでは ブートイメージ内でビットストリームパーティションを FSBL パーティションの直後に配置することを推奨しています 実行時セキュリティ 実行時セキュリティとは 正しくプログラムされていないデバイス または悪意のあるデバイスによるシステムメモリの破損やシステム障害からシステムを保護することをいいます システムを保護するには ソフトウェア実行中にメモリとペリフェラルを保護することが重要です Zynq UltraScale+ MPSoC デバイスには メモリとペリフェラルを保護する目的で次のブロックが用意されています ARM トラステッドファームウェア ザイリンクスメモリ保護ユニット ザイリンクスペリフェラル保護ユニット システムメモリ管理ユニット A53 メモリ管理ユニット R5 メモリ保護ユニット ARM トラステッドファームウェア Zynq UltraScale+ MPSoC デバイスには ARMv8 コア用の標準実行モデルが組み込まれています このモデルは 低いレベルの権限で通常のオペレーティングシステムを実行するため セキュリティを重視するハードウェアまたはレジスタへのアクセスを要求する場合は セキュアモニターコール (SMC) と呼ばれるプロキシソフトウェアを使用する必要があります セキュアワールドと非セキュアワールドの両方を統合した Linaro ARM トラステッドファームウェア (ATF) には ザイリンクスの Zynq UltraScale+ MPSoC デバイス用 SMC が含まれています セキュアアプリ 73

74 第 8 章 : セキュリティ機能 ケーションは トラステッド OS 上で動作します ATF には セキュアワールドと非セキュアワールドを切り替えるためのセキュアモニターがあります システムモジュール ( ドライバー アプリケーション ) は 絶対に必要な場合以外は リソースへアクセスすべきではありません たとえば Linux で SoC 内の公開キーが格納されている領域へのアクセスを禁止する必要があります さらに 暗号ブロックのドライバーは使用中のセッションキーを識別しません つまり セッションキーは キーネゴシエーションアルゴリズムでプログラム可能であり 暗号ブロック内の安全な場所に格納できます PSCI は 非セキュアソフトウェアから電力管理ユースケース ( セカンダリ CPU ブート ホットプラグ アイドルなど ) を実装したファームウェアへのインターフェイスです 例外レベルで動作する監視システムでは コンテキストの復元やコアの電源ステート切り替えといったアクションが必要になる場合があります 非セキュアソフトウェアは ARM セキュアモニターコール (SMC) 命令を使用して ATF のランタイムサービスにアクセスできます ARM アーキテクチャでは SMC 命令によって生成される SMC 例外を利用した非セキュアステートからセキュアステートへの同期制御転送は セキュアモニターで処理されます セキュアモニターの動作は レジスタで渡されるパラメーターで決定します 次の 2 種類の呼び出しが定義されています 不可分なセキュア動作を実行する高速呼び出し プリエンプティブなセキュア動作を開始する標準呼び出し SMC 命令の 2 つの呼び出し規約によって SMC 命令の 2 つの関数識別子を定義します SMC32: 32 ビットおよび 64 ビットクライアントコードのどちらも使用できる 32 ビットインターフェイス 最大 6 つの 32 ビット引数を渡します SMC64: 64 ビットクライアントコードのみが使用する 64 ビットインターフェイス 最大 6 つの 64 ビット引数を渡します SMC 関数識別子は ユーザーが呼び出し規約に基づいて定義します SMC 関数識別子を定義して それをすべての SMC 呼び出しのレジスタ R0 または W0 に渡すと 次のものが決まります 呼び出しタイプ 呼び出し規約 呼び出すセキュア関数 ATF は いずれかのセキュリティステートで生成された割り込みを設定および管理するためのフレームワークを実装しています 実装されているのは ARM リファレンスプラットフォームの TBBR (Trusted Board Boot Requirements) および PDD (Platform Design Document) の一部です コールドブートパスはプラットフォームをパワーアップして TBBR シーケンスが開始する場所で このシーケンスは DRAM 内の非セキュアワールドで動作するファームウェアに制御を渡すまで動作を継続します コールドブートパスは プラットフォームに物理的に電源が供給された時点から開始します リセットから解放された CPU のうち 1 つがプライマリ CPU として選択され その他の CPU はセカンダリ CPU と見なされます プライマリ CPU の選択方法はプラットフォームにより異なります コールドブートパスは主にプライマリ CPU によって実行されますが 必須の CPU 初期化はすべての CPU によって実行されます 74

75 第 8 章 : セキュリティ機能 プライマリ CPU がセカンダリ CPU のブートに必要な初期化を十分に実行するまで セカンダリ CPU はプラットフォーム固有の安全なステートに保持されます ウォームブートの場合 CPU はリセットから解放されたときと同じプロセッサモードでプラットフォーム固有のアドレスへジャンプします 次の表に ATF の API を示します 表 8-2: ATF の API ATF の API bl31_arch_setup(); bl31_platform_setup(); bl31_lib_init(); cm_init(); dcsw_op_all(dccsw); (*bl32_init)(); runtime_svc_init(); validate_rt_svc_desc(); get_unique_oen(); bl31_prepare_next_image_entry (); bl31_get_next_image_type(); bl31_plat_get_next_image_ep_i nfo (image_type); get_security_state () cm_init_context() cm_get_context_by_mpidr() get_scr_el3_from_routing_mode l() 説明 EL3 からの全般的なアーキテクチャセットアップ BL1 でのプラットフォームセットアップ すべての BL31 ヘルパーライブラリを初期化するシンプルな関数 コンテキスト管理ライブラリ初期化ルーチン 再び非セキュアソフトウェアワールドへ入る前にキャッシュをクリーニングします BL32 イメージの初期化に使用する関数ポインター ランタイムサービスによってエクスポートされるディスクリプター内の初期化ルーチンを呼び出します ディスクリプターの検査が完了したら ディスクリプターの開始および終了所有エンティティ番号と呼び出しタイプを結合して一意の oen を生成します この一意の oen を rt_svc_descs_indices 配列へのインデックスとして使用します ランタイムサービスディスクリプターのインデックスは このインデックスに格納されます ランタイムサービスディスクリプターを使用する前にサニティチェックするシンプルなルーチンです 一意の oen を取得します EL3 レジスタをプログラムし 次の ERET で BL31 の次のイメージに入るために必要なセットアップを実行します next_image_type を返します 指定したセキュリティステートで動作しているイメージに対応する entry_point_info 構造体への参照を返します セキュリティステートを取得します 現在の CPU によって最初に使用される cpu_context を初期化し entry_point_info 構造体で指定された初期エントリポイントステートを設定します 指定したセキュリティステートのコンテキストとして設定した MPIDR で特定される CPU の最新の cpu_context 構造体へのポインターを返します そのような構造体が指定されていない場合は NULL が返されます 前回の set_routing_model() の呼び出しで保存されたセキュリティステートのルーティングモデル (IRQ および FIQ ビットで表現 ) を含む SCR_EL3 のキャッシュコピーを返します 75

76 第 8 章 : セキュリティ機能 表 8-2: ATF の API (Cont d) ATF の API get_el3state_ctx() get_gpregs_ctx() cm_prepare_el3_exit() cm_get_context(security_state ); el1_sysregs_context_restore cm_set_next_context bl31_late_platform_setup(); bl31_register_bl32_init bl31_set_next_image_type 説明 ERET が正しいエントリにジャンプするように EL3 ステートに値を入力します コンテキストへのエントリポイントから X0-X7 の値を保存します セキュアまたは非セキュアソフトウェアワールドへの最初のエントリに対する CPU システムレジスタを準備します EL2 または hyp モードに対して実行が要求される場合 SCTLR_EL2 が初期化されます 非セキュア EL1 または svc モードに対して実行が要求される場合 CPU は EL2 をサポートします 次に 必要なすべての EL2 レジスタを設定して EL2 を無効にします すべてのエントリに関して EL1 レジスタは cpu_context から初期化されます セキュリティステートのコンテキストを取得します システムレジスタのコンテキストを復元します 例外リターンに使用するコンテキストをプログラムします これにより SP_EL3 は必要なセキュリティステートに設定された cpu_context へのポインターに初期化されます プラットフォームをセットアップします BL32 init 関数へのポインターを初期化します ランタイムサービスが BL31 の後に実行するイメージを決定するのに使用するアクセサ関数 ATF に関する詳細は ARM ATF のリンク [ 参照 37] を参照してください ザイリンクスメモリ保護ユニット ザイリンクスメモリ保護ユニット (XMPU) は領域ベースのメモリ保護ユニットです 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 16 章 システム保護ユニット ) を参照してください XMPU によるメモリ保護 XMPU 機能の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 16 章 システム保護ユニット ) を参照してください 76

77 第 8 章 : セキュリティ機能 XMPU レジスタの設定 XMPU は ワンタイム設定 またはセキュアマスター (PMU APU TrustZone セキュアマスター またはセキュアマスターとして指定されている場合の RPU) から trust-zone アクセスを介して設定可能です ブート時に XMPU を設定して その設定をロックすると 次のパワーオンリセットまで設定を変更できません 設定をロックしない場合 XMPU はセキュアマスターアクセスによって何回でも設定可能です ザイリンクスペリフェラル保護ユニット ザイリンクスペリフェラル保護ユニット (XPPU) の機能および動作の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の ザイリンクスペリフェラル保護ユニット ) を参照してください システムメモリ管理ユニット システムメモリ管理ユニット (SMMU): 分離サービスを提供します SMMU は I/O デバイスが実際に可能な範囲を超えてアドレス指定できるようにします メモリを分離しないと I/O デバイスによってシステムメモリが破壊される可能性があります SMMU はデバイスを分離して DMA 攻撃を防ぎます 分離とメモリ保護のために SMMU は DMA 対応 I/O に対するデバイスアクセスを事前に割り当てた物理空間のみに制限します SMMU の機能と動作の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の システムメモリ管理ユニット ) を参照してください A53 メモリ管理ユニット メモリ管理ユニット (MMU) はメインメモリ内の変換テーブルにアクセスするテーブルウォークハードウェアを制御します また 仮想アドレスを物理アドレスに変換します MMU は ページテーブルに格納された仮想アドレスから物理アドレスへのマップおよびメモリ属性を組み合わせて細精度のメモリシステム制御を可能にします これらは メモリアドレスにアクセスする際に変換ルックアサイドバッファー (TLB) に読み込まれます MMU の機能と動作の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の メモリ管理ユニット ) を参照してください R5 メモリ保護ユニット メモリ保護ユニット (MPU) を有効にすると メモリを複数の領域に分割して各領域に対して個別に保護属性を設定できます MPU を無効にするとアクセス許可のチェックは実行されず メモリ属性はデフォルトのメモリマップに従って割り当てられます MPU には最大 16 の領域があります MPU の機能と動作の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の メモリ保護ユニット ) を参照してください 77

78 第 9 章 電力管理フレームワークの概要 はじめに Zynq UltraScale+ MPSoC は 複数のユーザープログラマブルプロセッサ FPGA 最先端の電力管理機能を統合した業界初のヘテロジニアスマルチプロセッサ SoC (MPSoC) です 電力効率に優れた最新デザインでは 消費電力を削減するハードウェアオプションを複数備えた複雑なシステムアーキテクチャを使用し 複数のマスターデバイスからのすべての電力管理要求に対応できる特別な CPU を使用して 各リソースへのパワーアップやパワーダウンおよび電源ステートの遷移を管理する必要があります この場合の課題は 業界規格 (IEEEP2415) に準拠し 異なる動作システムを実行する複数 CPU からの要求にすべて応えることができるインテリジェントなソフトウェアフレームワークを提供することです ザイリンクスは PMF ( 電力管理フレームワーク ) を作成し プラットフォーム管理ユニット (PMU) を使用する柔軟な電力管理制御を可能にしました この電力管理フレームワークは さまざまな使用状況に対応します たとえば Linux は アイドル ホットプラグ サスペンド ( 一時停止 ) レジューム ( 復帰 ) ウェークアップなどの基本的な電力管理機能を提供します カーネルは API を使用して電力管理制御を実行しますが ほとんどの RTOS にはこの機能がありません したがって ユーザーインプリメンテーションが必要になり この電力管理フレームワークを使用することで簡単に実装できます エンベデッドビジョンシステム 先進運転支援システム 監視システム 医療用ポータブル測定機器 IoT (Internet of Things) などの産業向けアプリケーションでは 高性能なヘテロジニアス SoC へのニーズが高まっている一方で 厳しい電力バジェットが要求されます これらのアプリケーションの中にはバッテリで駆動されるものがあり バッテリ寿命が重視されています その他 クラウドやデータセンターでは 環境コストの削減はもちろんのこと 冷却コストやエネルギーコストの削減が非常に重視されています これらすべてのアプリケーションは 柔軟な電力管理ソリューションによって大きなメリットを享受できます 78

79 第 9 章 : 電力管理フレームワークの概要 主な機能 電力管理フレームワークの主な機能は次のとおりです プラットフォーム管理ユニット (PMU) の使用によって 集中管理された電源ステート情報を提供 EEMI (Embedded Energy Management Interface) API (IEEE P2415) をサポート すべてのデバイスの電源ステートを監視 Linux の電力管理機能をサポート Linu デバイスツリー電力管理 ATF/PSCI 電力管理サポート アイドル ホットプラグ サスペンド ( 一時停止 ) レジューム ( 復帰 ) ウェークアッププロセス管理 24 以上の API を使用して次の電力管理機能を直接制御 プロセッシングユニットのサスペンドとウェークアップの管理 管理用メモリとペリフェラル 電力管理ソフトウェアのアーキテクチャ Zynq UltraScale+ MPSoC アーキテクチャには すべてのシステムリソースのパワーアップ パワーダウン 監視 およびウェークアップ機能を制御する専用のプログラマブルユニット PMU を備えています ユーザーは 複数プロセッサを統合したヘテロジニアスシステムの電力管理に最適な機能を備えたシステムを利用することで 大きなメリットを享受できます その一方で デザインは複雑になります 電力管理フレームワークの目的は この複雑なデザインを抽象化し ユーザーが電力バジェットの目標を満たすために必要な API のみを提供することです 79

80 第 9 章 : 電力管理フレームワークの概要 X-Ref Target - Figure 9-1 図 9-1: 電力管理フレームワーク EEMI の目的は すべてのソフトウェアコンポーネントがコアやペリフェラルの電力を管理できるように共通の API を提供することです EEMI によって 複雑プロセッサや単一コアをサスペンドするなどの高度な電力管理が可能になります この基本アーキテクチャでは 最適な省電力アプローチをユーザーが簡単に実装できるようになります Linux デバイスツリーは 各デバイスに共通する記述フォーマットと電力特性を提供します また Linux は基本的な電力管理機能として アイドル ホットプラグ サスペンド レジューム ウェークアップなども提供します カーネルは 実装された API を利用して電力管理を実行します ユーザーは XilPM ライブラリを使用して 24 以上の API を利用する独自の電力管理アプリケーションを作成することも可能です Zynq UltraScale+ MPSoC の電力管理の概要 Zynq UltraScale+ MPSoC の電力管理フレームワークは EEMI (Extensible Energy Management Interface) の実装をベースとする電力管理のオプションです これによって チップやデバイス上のさまざまなプロセッシングユニット (PU) を駆動するソフトウェアコンポーネントが電力管理のための要求を発行したり 要求に応えることが可能になります Zynq UltraScale+ MPSoC の電力管理ハードウェアアーキテクチャ Zynq UltraScale+ MPSoC デバイスは 主に 4 つの電源ドメインに分割されています フル電力ドメイン (FPD): ARM Cortex -A53 アプリケーションプロセッシングユニット (APU) が含まれるほか APU が使用する多数のペリフェラルが含まれます 低電力ドメイン (LPD): ARM Cortex-R5 リアルタイムプロセッシングユニット (RPU) プラットフォーム管理ユニット (PMU) コンフィギュレーションセキュリティユニット (CSU) その他残りのオンチップペリフェラルが含まれます プログラマブルロジック (PL) 電源ドメイン : PL が含まれます 80

81 第 9 章 : 電力管理フレームワークの概要 バッテリ電源ドメイン : リアルタイムクロック (RTC) およびバッテリバックアップ式 RAM (BBRAM) が含まれます 次の図にあるその他の電力ドメインは 電力フレームワークによって積極的に管理されません 次の図は Zynq UltraScale+ MPSoC デバイスの電源ドメインと電源アイランドを示しています X-Ref Target - Figure 9-2 Battery Power Supplies VCC_PSBATT BPU BBRAM RTC Osc PS Battery-Power Domain Low-Power Domain Full-Power Domain 0.85V VCC_PSINTLP USB SERDES Power Domain 1.8V 3.3V VCCO_PSIO0 1.8V 3.3V VCCO_PSIO1 1.8V 3.3V VCCO_PSIO2 1.8V 3.3V VCCO_PSIO3 1.8V VCC_PSAUX GPIO efuse AMS IOU CSU PMU Interconnect IPI SLCR DMA ETM GIC Dual Cortex-R5 RPU TCM TCM TCM TCM PS-TAP USB RAM RAM RAM RAM O C M GPIO Power Domain DDRIO Power Domain PL Power Domain LP PLLs Power Domains FP PLLs Power Domains 1.2V VCC_PSPLL_0 VCC_PSPLL_1 VCC_PSPLL_2 IOPLL RPUPLL APUPLL PTM SOC Debug DAP, RPU Debug PTM PTM PTM VCC_PSPLL_3 VCC_PSPLL_4 DDRPLL VideoPLL PCIe CPU CPU CPU CPU APU RA RAM M L2 1.2V 1.8V VCCO_PSDDR DDR IOB DDR Interconnect and SLCR GPU DMA AXI SATA DP VCC_PSINTFP_DDR 0.85V VCC_PSINTFP GPU-PP0 GPU-PP1 0.85V 1.8V PS_MGTRAVCC PS_MGTRAVTT PS-GTR FP Gasket LP Gasket 0.85V 0.85V VCCINT VCCBRAM PL Video Codec 1.8V VCCAUX X 図 9-2: Zynq UltraScale+ MPSoC の電力ドメインと電源アイランド Zynq UltraScale+ MPSoC デバイスはヘテロジニアスなマルチコアアーキテクチャであるため 単一プロセッサが個々のコンポーネントやサブシステムの電源ステートを独自に判断することは不可能です その代わり 電力管理 API がすべての電力管理制御をプラットフォーム管理ユニット (PMU) に委託する協調アプローチが採用されています これは APU または RPU などのその他のプロセッシングユニット (PU) から受信した電力管理要求に対応したり 電力管理 API を介してほかのプロセッシングユニットからの要求や実行に対応する重要なコンポーネントです 81

82 第 9 章 : 電力管理フレームワークの概要 重要 : Zynq UltraScale+ MPSoC の EEMI 実装の場合 プラットフォーム管理ユニット (PMU) は APU や RPU などのプロセッシングユニット (PU) の電力管理コントローラーとして機能します これらの APU/RPU は 電力管理 (PM) マスターノードとして機能し 電力管理要求を発行します これらの要求に基づいて PMU はすべての PM スレーブノードおよび PM マスターノードの電源ステートを制御します Zynq UltraScale+ MPSoC デバイスは 異なるプロセッサ間での電力管理関連の通信手段として使用されるプロセッサ間割り込み (IPI) もサポートしています このフローの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 13 章 割り込み ) を参照してください Zynq UltraScale+ MPSoC の電力管理ソフトウェアアーキテクチャ 電力管理において複数のプロセッシングユニットが協調できるようにするため Zynq UltraScale+ MPSoC デバイスのソフトウェアフレームワークはヘテロジニアスマルチプロセッシングシステムを管理するための電力管理 API の実装を提供します 次の図は API ベースの電力管理ソフトウェアアーキテクチャを示しています X-Ref Target - Figure 9-3 PM Masters APU OS/Application(s) RPU RTOS/Application(s) Microblaze Application(s) PM-API PM-API PM-API PM Controller IPI - communication Power state control PM-API PMU IPI - communication Power state control PMM Power state control PM Slaves Memory_A Memory_B Peripheral_A Peripheral_B 図 9-3: API ベースの電力管理ソフトウェアアーキテクチャ 82

83 第 9 章 : 電力管理フレームワークの概要 電力管理フレームワークの概要 Zynq UltraScale+ MPSoC デバイスの電力管理フレームワーク (PMF) は EEMI の実装をベースとしています ( Embedded Energy Management API Specification (UG1200) [ 参照 15] を参照 ) この実装には プロセッシングユニット (PU) が電力管理コントローラーにメッセージを送信するための機能や 電力管理コントローラーがメッセージを PU に送信するためのコールバック機能を持つ API が含まれます API は 次のような機能に分類されます PU のサスペンドとウェークアップ メモリやペリフェラルなどのスレーブデバイスの電力管理 直接アクセス その他 API の呼び出しと応答 IPI を使用する電力管理の通信 Zynq UltraScale+ MPSoC デバイスの場合 電力管理通信層は IPI ブロックで提供されるプロセッサ間割り込み (IPI) を使用して実装されます IPI の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 13 章 割り込み ) を参照してください 各 PU には 割り込みとペイロードバッファーを含む電力管理コントローラーと接続する専用の IPI チャネルが 1 本あります バッファーは API ID ( 最大 5 つの引数 ) を渡します ターゲットへの IPI 割り込みによって 次のような API の処理がトリガーされます API 関数を呼び出すと PU が PMU に IPI を生成して必要な電力管理動作の実行を促します PMU は 各 PM 動作を分割できないものとして実行します つまり この動作は割り込みで中断できません PMU から PU への通知に使用される PM のコールバック機能をサポートするために 各 PU にはこれらのコールバック IPI の処理機能が実装されています 肯定応答メカニズム Zynq UltraScale+ MPSoC の電力管理フレームワーク (PMF) は ブロッキング / ノンブロッキングの肯定応答をサポートしています 肯定応答の引数を提供するほとんどの API 呼び出しでは 呼び出し元で次に示す肯定応答オプションのいずれかを選択できます REQUEST_ACK_NO: 肯定応答なしの要求 REQUEST_ACK_BLOCKING: ブロッキング肯定応答の要求 REQUEST_ACK_NON_BLOCKING: コールバック機能を使用する非ブロッキング肯定応答の要求 各プロセッシングユニット (PU) は API 呼び出し用に 1 本の IPI チャネルを使用するため 電力管理 API 呼び出しが複数ある場合はシリアル化されます 1 つの要求が電力管理コントローラーに送信された後 電力管理コントローラーが 1 つ目の要求の処理を完了した場合のみ次の要求を発行できます したがって いずれの肯定応答メカニズムを使用した場合でも 後続要求を発行しているときには 呼び出し元がブロックされます 83

84 第 9 章 : 電力管理フレームワークの概要 肯定応答なし 肯定応答なし (REQUEST_ACK_NO) が要求された場合 電力管理コントローラーは呼び出し元へ肯定応答を返さずに要求を処理します それ以外は 通常は肯定応答が送信されます ブロッキング肯定応答 ブロッキング肯定応答 (REQUEST_ACK_BLOCKING) を指定した PM 要求が開始されると 電力管理コントローラーが肯定応答を提供しない限り 呼び出し元はブロックされたままとなります プラットフォーム管理ユニット (PMU) は IPI 割り込みをクリアする前に IPI バッファーの応答部分に肯定応答値を書き込みます IPI 観察レジスタが割り込みのクリアを示した後 ( つまり PMU が発行された IPI の処理を完了した後 ) に 呼び出し元は IPI バッファーから肯定応答値を読み出します PMU が次の要求に対応する準備ができるようになるまで PU の IPI は無効になります 非ブロッキング肯定応答 非ブロッキング肯定応答 (REQUEST_ACK_NON_BLOCKING) を指定した PM 要求が発行されると 呼び出し元はプラットフォーム管理ユニット (PMU) が要求を処理するまで待機する必要はありません つまり 呼び出し元は PMU からの肯定応答を待つ間 別の動作を実行できます PMU は 要求の処理を完了すると IPI バッファーに肯定応答値を書き込みます その後 PMU は呼び出し元 PU に対して IPI をトリガーして その動作を割り込み 送信された肯定応答に関する情報を通知します 非ブロッキング肯定応答は 呼び出し元 PU で実行されるコールバック関数を使用して実装されます (XPm_NotifyCb Callback 参照 ) XPm_NotifyCb の詳細は 付録 I XilPM Library v2.1 を参照してください 電力管理フレームワークの層 Zynq UltraScale+ MPSoC デバイスの電力管理フレームワーク (PMF) インプリメンテーションには 次に示す API 層があります Xilpm: このライブラリ層は APU や RPU などの異なるプロセッシングユニットのスタンドアロンアプリケーションに使用されます ATF: ARM Trusted Firmware (ATF) には クライアント側の PM フレームワークの独自インプリメンテーションが含まれます 現在 Linux オペレーティングシステムで使用されています PMUFW: プラットフォーム管理ユニットファームウェア (PMUFW) は プラットフォーム管理ユニット (PMU) 上で動作し 電力管理 API を実装しています 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の PMU のプログラミングモデル ) を参照してください 84

85 第 9 章 : 電力管理フレームワークの概要 次の図に APU RPU PMF 間における API の相互作用を示しています X-Ref Target - Figure 9-4 APU Bare metal application RPU Bare metal application xilpm PM-API xilpm PM-API IPI PM-API PMU 図 9-4: ベアメタルアプリケーションのみで使用される API 層 APU がオペレーティングシステムを使用してフルソフトウェアスタックを実行する場合 Xilpm ライブラリは使用されません その代わり EL3 上で動作する ATF がクライアント側の電力管理 API を実装し 上位層に対して SMC ( セキュアモニターコール ) ベースのインターフェイスを提供します 次の図に このビヘイビアーを示しています ARMv8 アーキテクチャおよびその異なる実装モードの詳細は ARMv8 マニュアル [ 参照 42] を参照してください 85

86 第 9 章 : 電力管理フレームワークの概要 次の図は APU 上でフルソフトウェアスタックが実行される場合の PMF 層を示しています X-Ref Target - Figure 9-5 APU EL0/1 EL3 OS SMC ATF PM-API RPU Bare metal application xilpm PM-API IPI PM-API PMU X 図 9-5: APU 上でフルソフトウェアスタックが実行される場合の PM フレームワーク層 一般的な電力管理 API 呼び出しフロー 電力管理に関わるすべてのエンティティを ノード と呼んでいます この後のセクションでは 電力管理フレームワーク (PMF) が APU や RPU に割り当てられたスレーブノードを使用してどのように機能するのかを説明します スレーブノードへの要求とリリース PU がペリフェラルまたはメモリいずれかのスレーブノードを必要とする場合は 電力管理 API を使用するスレーブノードを要求する必要があります スレーブノードが特定機能を果たし 必要なくなった場合には リリースして電源をオフにする必要があります 86

87 第 9 章 : 電力管理フレームワークの概要 次の図は APU と RPU が 1 つの OCM メモリバンク (ocm0) を共有している場合の呼び出しフローを示しています X-Ref Target - Figure 9-6 図 9-6: APU と RPU が 1 つの OCM メモリバンクを共有している場合の PM フレームワーク呼び出しシーケンス 注記 : APU が XStatus XPm_ReleaseNode を呼び出した後 RPU も同じスレーブノードを要求しているため ocm0 メモリの電源はオンのままとなります PMU が ocm0 ノードもリリースした後に PMU は ocm0 メモリの電源をオフします 87

88 第 9 章 : 電力管理フレームワークの概要 プロセッシングユニットのサスペンドとレジューム プロセッシングユニット (PU) の電源をオフにすることは アイドル状態に遷移するのとは異なり 外部エンティティを使用してパワーダウンおよびパワーアップ遷移を処理する必要があります Zynq UltraScale+ MPSoC デバイスの場合 プラットフォーム管理ユニット (PMU) がすべての電源ステートの遷移を管理します PU が PMU に電源ステートの遷移が要求されていることを通知します 次の図に このプロセスを示しています X-Ref Target - Figure 9-7 図 9-7: APU のサスペンドおよびレジュームプロセス CPU/PU のセルフサスペンド セクションで サスペンドプロセスまたはレジュームプロセスの詳細を説明しています 各 PU は 動作可能なスレーブノードに依存します アクセス権利 プロセッシングユニット (PU) がアクセスすべきではないペリフェラルに要求を発行することを回避するために PMF には 次のセクションで説明するように 各 PU に対するペリフェラル ( スレーブノード ) のデフォルト割り当てが含まれています ノードの基本的な説明は Node IDs: XPmNodeId を参照してください 88

89 第 9 章 : 電力管理フレームワークの概要 デフォルトリソース 各 PU は PU 動作を可能にするためのスレーブノードセットに依存します 各 PU には 動作の復帰に必要なスレーブノードが多数含まれています PU 動作を復帰させる前に PMU で これらのリソースを各 PU にあらかじめ割り当てます たとえば リセット後に CPU が命令のフェッチを開始するメモリノードは CPU が実行を開始する前にアクセス可能な状態になる必要があります デフォルト要件は次のとおりです APU のデフォルト要件 : L2 キャッシュ DDR RPU のデフォルト要件 : すべての TCM メモリバンク 電力管理に API を使用 概要 この章では ザイリンクスの電力管理フレームワーク (PMF) API を使用して 一般的な電力管理タスクを実行する手順について詳しく説明します プロセッシングユニットに電力管理機能を実装 Xilpm ライブラリは PU 上で実行されているソフトウェアが電力管理 API 呼び出しを開始する際に必要なインターフェイスを提供します API 呼び出しを実行するには プロセッシングユニット (PU) で実行されているソフトウェアが Xilpm ライブラリを使用する必要があります プロジェクトに Xilpm ライブラリを含める方法は ザイリンクスソフトウェア開発キットのヘルプ (UG782) [ 参照 21] を参照してください Xilpm ライブラリの初期化 すべての電力管理 API 呼び出しを開始する前には XPm_InitXilpm を呼び出し 適切に初期化されたプロセッサ間割り込み (IPI) ドライバーインスタンスにポインターを移動させて Xilpm ライブラリを初期化する必要があります IPI の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 13 章 割り込み ) を参照してください XPm_InitXilpm の詳細は 付録 I XilPM Library v2.1 を参照してください スレーブデバイスの使用 Zynq UltraScale+ MPSoC デバイスの電力管理フレームワーク (PMF) には メモリやペリフェラルなどのスレーブデバイス (PM スレーブとも呼ばれている ) を管理するための専用機能が含まれています プロセッシングユニット (PU) がこれらの機能を使用して 電力管理コントローラーにこれらのデバイスの要件 ( 機能やウェークアップレイテンシなど ) を伝えます 電力管理コントローラーは 各デバイスが該当するすべての PU 要件を満たしながら最小限の消費電力ステートを常に維持できるように制御します 89

90 第 9 章 : 電力管理フレームワークの概要 ノードの要求とリリース PU は XPm_RequestNode API を使用して スレーブデバイスへのアクセスを要求し そのデバイスの要件を提示します PU がそのスレーブ ( アクセス権利 参照 ) へのアクセスを許可されている場合は 電力管理コントローラーによって 要求されたデバイスの電源がオンになり アクティブステートに遷移した状態が確保されます 単一 PU にしか対応できないデバイスの場合 その他の PU はこのデバイスにアクセスできません 電力管理コントローラーは 各 PM スレーブに対して 1 つまたは複数の PU へのアクセス許可を与えます 1 つの PU が PM スレーブへアクセスを要求した場合 電力管理コントローラーは その権限の構成を確認して PU が要求した PM スレーブを使用可能であるかを判断します ユーザーは ソースコードで電力管理コントローラーの権限の割り当てを再構成する必要があります デバイスが使用されなくなると 通常 PU は XPm_RequestNode 関数を呼び出して PM コントローラーがそのデバイスの電力ステートを再評価して 潜在的に低電力状態にすることが可能です また 別の PU がこのデバイスへのアクセスを要求することも可能です XPm_RequestNode の詳細は 付録 I XilPM Library v2.1 を参照してください 要件の変更 ノードの使用中 PU は XPM_SetRequirement API を使用して PM スレーブの機能に関する要件を変更できます 通常 ノードを使用する要求は デバイスがあまり使用されなくなると生じます ただし 適切なウェークアップ割り込み生成やノード内容の保持は指定する必要があります 次の呼び出しの例では ウェークアップ割り込みのみを必要とするように node 引数の要件を変更しています XPm_SetRequirement(node, PM_CAP_WAKEUP, 0, REQUEST_ACK_NO); PU には要件がないことがあります その場合は PM スレーブをリリースするオプションや要件を 0 に設定するオプションを使用します 重要 : ノード要件を 0 に設定することは PM スレーブをリリースすることではありません PM スレーブをリリースすると PU がそのアクセス権をリリースすることであり ほかの PU が潜在的にこのデバイスを使用できる状態になります 要件 0 に設定すると PU のアクセス権利を保持したまま電力管理コントローラーがデバイスを低電力ステートへ遷移させることが可能になります 複数の PU が 1 つの PM スレーブ ( 通常はメモリ ) を共有する場合 電力管理コントローラーは呼び出し元の PU の要件をすべて満たすように PM スレーブの電力ステートを構成します XPM_SetRequirement の詳細は 付録 I XilPM Library v2.1 を参照してください CPU/PU のセルフサスペンド PU は複数の CPU の集合体として構成できます APU は 4 つの CPU を持つ PU です RPU には 2 つの CPU があります セルフサスペンドを実行するには CPU が XPM_SelfSuspend 関数を呼び出して 電力管理コントローラーへセルフサスペンドの開始を伝えます その後 次の動作が実行されます XPm_SelfSuspend() 呼び出しが処理された後 その後いかなる割り込みが発生しても CPU は必ずスリープ状態になります APU および RPU では このようなビヘイビアーを確実にするために 90

91 第 9 章 : 電力管理フレームワークの概要 XPm_SelfSuspend() 呼び出しが完了した後に CPU へのすべての割り込みを GIC ウェークアップ割り込みとして電力管理コントローラーへリダイレクトします その後 電力管理コントローラーは CPU がサスペンドプロセスを完了するまで待機します PU は XPm_SuspendFinalize を呼び出して スリープステートへ遷移する準備が整ったことを電力管理コントローラーへ通知します XPm_SuspendFinalize()school 関数はアーキテクチャに依存します これにより 未処理の電力管理 API 呼び出しが処理され アーキテクチャ固有のサスペンドシーケンスが実行されます また サスペンドの完了が電力管理コントローラーへ通知されます APU や RPU などの ARM プロセッサの場合 XPm_SuspendFinalize() 関数は WFI (Wait for interrupt) 命令を使用します この命令は CPU をサスペンドし 電力管理コントローラーへの割り込みをトリガーします サスペンド完了が電力管理コントローラーに通知されると 電力管理コントローラーは CPU をリセット状態にし アイランド内のその他のコンポーネントが現在アクティブでなければ CPU の電源アイランドの電源を切断できます CPU の GIC インターフェイスを介して有効になった割り込みは その特定の CPU に割り当てられた GIC ウェークアップ割り込みとして電力管理コントローラー (PMC) にリダイレクトされます 割り込みはリダイレクトされるため CPU は電力管理コントローラーを使用してのみ復帰できます PU をサスペンドするには すべての CPU を個別にサスペンドする必要があります XPM_SelfSuspend および XPm_SuspendFinalize の詳細は 付録 I XilPM Library v2.1 を参照してください レジューム ( 復帰 ) の実行 CPU は ハードウェアリソースでトリガーされるウェークアップ割り込み または XPM_RequestWakeup API を使用する明示的なウェークアップ要求で復帰可能です CPU は XPm_RequestSuspend 呼び出しで提供されるレジュームアドレスから実行を開始します XPM_RequestWakeup および XPm_RequestSuspend の詳細は 付録 I XilPM Library v2.1 を参照してください ウェークアップソースのセットアップ いずれの FPD デバイスも使用されておらず 既存のレイテンシ要件がパワーダウンを許可する場合は PM コントローラーが FPD 全体の電源をオフにできます FPD の電源がオフ状態で LPD のデバイスによってトリガーされる割り込みで APU を起動する場合は FPD ウェークアップイベントの伝搬を許可するように GIC プロキシを設定しておく必要があります ウェークアップ割り込みを発行する必要のあるすべてのデバイスに対して XPM_SetWakeUpSource を呼び出すことによって APU は確実に起動できます したがって サスペンドする前に APU は XPm_SetWakeupSource(NODE_APU, node, 1) を呼び出して 必要なスレーブをウェークアップソースとして追加する必要があります この場合 APU は使用しているすべてのスレーブに対して要件 0 を設定できます APU がサスペンド処理を終了し ほかの PU が FPD 内のリソースを使用していない場合 PM コントローラーは FPD 全体の電源をオフにし IC プロキシを設定して LPD スレーブのウィークイベントの伝搬を有効にします XPM_SetWakeUpSource の詳細は 付録 I XilPM Library v2.1 を参照してください 91

92 第 9 章 : 電力管理フレームワークの概要 サスペンド処理の中断 XPM_SetSelfSuspend 関数を呼び出した後に PU がサスペンド処理の中断を決定した場合 PU は XPm_AbortSuspend 関数を呼び出すことによって 電力管理コントローラーに中断したサスペンドについて通知する必要があります XPM_SetSelfSuspend および XPm_AbortSuspend の詳細は 付録 I XilPM Library v2.1 を参照してください サスペンド処理中の PM スレーブへの対応 セルフサスペンドする PU は 使用中のペリフェラルとメモリに関して変更した要件を 電力管理コントローラーに通知する必要があります PU が電力管理コントローラーに通知しないと 使用されているすべてのデバイスの電源はオンのままとなります スレーブデバイスがメモリの場合 通常 次の関数を使用してコンテキストが保持されるようにする必要があります XPm_SetRequirement(node, PM_CAP_CONTEXT, 0, REQUEST_ACK_NO); XPM_SelfSuspend の呼び出し後などのサスペンド中に PM スレーブの要件を設定した場合 CPU がサスペンドを終了するまで設定は延期されます これにより サスペンド処理の完了に必要なデバイスは 呼び出し元の CPU がサスペンド処理を完了した後 確実に低電力ステートへ遷移します 一般的な例には命令メモリがあります サスペンド処理が完了するまで CPU はメモリへアクセスできます CPU がメモリをサスペンドした後 そのメモリのコンテンツは保持されます 各 CPU が復帰する前に 延期されたすべての要件は自動的に置き換えられます PU 全体がサスペンドする場合 PU 内の最後に起動した CPU がデバイスの変更を管理する必要があります XPM_SelfSuspend の詳細は 付録 I XilPM Library v2.1 を参照してください APU/RPU をサスペンドするためのコード例 APU または RPU をサスペンドするためのソースコードの例を次に示します /* Base address of vector table (reset-vector) */ extern void *_vector_table; /* Inform PM controller that APU_0 intends to suspend */ XPm_SelfSuspend(NODE_APU_0, MAX_LATENCY, 0, (u64)&_vector_table); /** * Set requirements for OCM banks to preserve their context. * The PM controller will defer putting OCMs into retention until the suspend is finalized */ XPm_SetRequirement(NODE_OCM_BANK_0, PM_CAP_CONTEXT, 0, REQUEST_ACK_NO); XPm_SetRequirement(NODE_OCM_BANK_1, PM_CAP_CONTEXT, 0, REQUEST_ACK_NO); XPm_SetRequirement(NODE_OCM_BANK_2, PM_CAP_CONTEXT, 0, REQUEST_ACK_NO); XPm_SetRequirement(NODE_OCM_BANK_3, PM_CAP_CONTEXT, 0, REQUEST_ACK_NO); /* Flush data cache */ Xil_DCacheFlush(); /* Inform PM controller that suspend procedure is completed */ 92

93 第 9 章 : 電力管理フレームワークの概要 XPm_SuspendFinalize(); FPD ドメイン全体をサスペンド フル電力ドメイン全体の電源をオフにするためには FPD デバイスが使用されていないときに電力管理コントローラーが APU をサスペンドする必要があります この条件が満たされると 電力管理コントローラーは FPD の電源を自動的にオフにできます レイテンシ要件によってこの動作が制限されない限り 電力管理コントローラーは FPD の電源をオフにします 要件によって制限された場合 FPD の電源はオンのままになります FPD の強制的パワーダウン XPM_ForcePowerdown 関数を呼び出すことによって FPD を強制的にパワーダウンさせるオプションがあります この場合 呼び出し元の PU が電力管理コントローラーで設定された適切な権限を持っている必要があります 電力管理コントローラーは APU で使用されているすべての PM スレーブを自動的にリリースします 注記 : 特に APU 上で複雑なオペレーティングシステムを実行している場合 OS が適切にサスペンドされなかったことによってデータやシステムの破損が発生する可能性があるため この強制的パワーダウンは推奨していません 重要 : XPm_RequestSuspend API を使用する必要があります XPM_ForcePowerdown の詳細は 付録 I XilPM Library v2.1 を参照してください その他のプロセッシングユニットとの相互作用 PU をサスペンドする PU は XPm_RequestSuspend を呼び出して 引数でターゲットノード名を渡すことで 別の PU のサスペンドを要求できます これ受けて 電力管理コントローラーは XPm_InitSuspendCb() を呼び出します これは ターゲット PU に実装されたコールバック関数です その後 ターゲット PU はサスペンド処理を開始するか または XPm_AbortSuspend を呼び出してサスペンドの中断理由を指定します たとえば 次のコマンドを使用して APU にサスペンドを要求できます XPm_RequestSuspend(NODE_APU, REQUEST_ACK_CB_STANDARD, MAX_LATENCY, 0); 次の図は XPM_RequestSuspend の呼び出しによってトリガーされる一般的なシーケンスを示しています XPm_RequestSuspend XPm_InitSuspendCb および XPm_AbortSuspend の詳細は 付録 I XilPM Library v2.1 を参照してください 93

94 第 9 章 : 電力管理フレームワークの概要 X-Ref Target - Figure 9-8 図 9-8: XPm_RequestSuspend の呼び出しで RPU に対して APU がサスペンドを開始 PU をウェークアップさせる さらに PU は XPm_RequestWakeup を呼び出すことによって その CPU の 1 つまたは別の PU のウェークアップを要求できます 呼び出しを処理するとき 電力管理コントローラーはターゲット CPU または PU を起動します PU がターゲットである場合 この要求によっていずれか 1 つの CPU が起動します 電力管理コントローラーで選択された CPU は PU 内のプライマリ CPU として見なされます 次に ウェークアップ要求の例を示します XPm_RequestWakeup(NODE_APU_1, REQUEST_ACK_NO); XPm_RequestWakeup の詳細は 付録 I XilPM Library v2.1 を参照してください XilPM の実装の詳細 PM フレームワークのシステム層は プロセッサ間割り込み (IPI) を使用して Zynq UltraScale+ MPSoC に実装されています EEMI API 呼び出しを開始する場合 PU は API データ (API ID と引数 ) を IPI 要求バッファーに書き込み その後 PMU に対して IPI をトリガーします 94

95 第 9 章 : 電力管理フレームワークの概要 PM コントローラーが要求を処理した後 特定の EEMI API および提供された引数に応じて 肯定応答を送信します 肯定応答の詳細は セクション を参照してください PMU への API 呼び出しのペイロードマッピング 各 EEMI API 呼び出しは 次のデータで識別されます EEMI API 識別子 (ID) EEMI API の引数 API 識別子と API 引数の一覧表は 付録 A を参照してください PMU への IPI を実行する前に PU は呼び出しの情報を IPI 要求バッファーへ書き込む必要があります IPI バッファーへ書き込まれる各データは 32 ビットワードです 合計ペイロードサイズは 6 つの 32 ビットワードで構成されます EEMI API 識別子用に 1 ワードが予約されており 残りのワードは引数に使用されます IPI バッファーへの書き込みはオフセット 0 から開始します 情報データは 次のようにマッピングされます Word [0]EEMI API ID Word [1:5]EEMI API の引数 IPI 応答バッファーを使用して 動作ステータスと最大 3 つの値を返します Word [0] サクセス / エラーコード Word [1:3] 値 1..3 PMU からの API コールバックのペイロードマッピング EEMI API には PM コントローラーによって呼び出され PU に送信されるコールバック関数が含まれています Word [0]EEMI API Callback ID Word [1:5]EEMI API の引数 API 識別子および API の引数の一覧表は 付録 I XilPM Library v2.1 を参照してください PMU への EEMI API 呼び出しを実行 PMU への API 呼び出しを実行する前に PU は前の API 呼び出しが PMU で完了されるまで待機する必要があります 対応する IPI 観察レジスタを読み出すことで PMU 動作の完了を確認できます IPI ペイロードバッファーに API データを書き込み PMU への IPI 割り込みをトリガーすると API 呼び出しが実行されます ブロッキング API 呼び出しの場合は PMU が応答バッファーに動作ステータスと最大 3 つの値を書き込んで応答します PM 動作にエラーが生じた場合に PMU から送信されるすべてのエラーの一覧表は 付録 B を参照してください 応答バッファーのデータが有効であることを確証するために PU は PMU が API 呼び出し処理を完了するまで待機してから 応答バッファーを読み出す必要があります 95

96 第 9 章 : 電力管理フレームワークの概要 X-Ref Target - Figure 9-9 図 9-9: PMU への API 呼び出し実行フローの例 PMU からの API コールバックを処理 PMU は IPI バッファーに API コールバックデータを書き込み PU への IPI 割り込みをトリガーすることによって PU へコールバック関数を呼び出します このような割り込み信号を受信するために PU は IPI ブロックと割り込みコントローラーを適切に初期化する必要があります すべてのコールバックには 1 つの割り込みがあります このため ペイロードバッファーの要素 0 には PU が API コールバックを識別するための API ID が含まれています したがって PU はそれぞれの API コールバック関数を呼び出す際には IPI 要求バッファーのロケーション 1 ~ 4 から取得した引数でその関数を渡す必要があります このビヘイビアーの実装は XilPM ライブラリにあります 96

97 第 9 章 : 電力管理フレームワークの概要 Linux Linux は EL1 レベルで実行され Linux と ATF ソフトウェア層の間の通信は SMC 呼び出しを使用して実行されます EEMI API ベースの電力管理機能が Linux カーネルに移植され Linux で実行される電力管理機能は PMU で提供される EEMI サービスを利用できるようになります さらに デバッグの場合 EEMI API へは debugfs を使用して直接アクセス可能です debugfs を使用して EEMI API に直接アクセスすると カーネルの電力管理操作が妨げられ 予期しない問題が発生する可能性があることに注意してください この章で紹介するすべての Linux 電力管理機能は PetaLinux のデフォルト設定で利用できます ユーザー空間の PM インターフェイス システムの電源ステート ユーザーは システムまたはシステム全体の電源ステートを変更できます PMU によって システムやサブシステムの新しい電源ステートへの切り替えが容易になります シャットダウン ユーザーは 標準の shutdown コマンドで APU サブシステムをシャットダウンできます システム全体をシャットダウンするには APU サブシステムをシャットダウンする前に その他すべてのサブシステムをシャットダウンする必要があります echo release_node 69 > /sys/kernel/debug/zynqmp_pm/power 97

98 第 9 章 : 電力管理フレームワークの概要 このコマンドを使用して PL を再びパワーアップします echo request_node 69 > /sys/kernel/debug/zynqmp_pm/power PL サブシステムをシャットダウンする方法は Zynq UltraScale+ MPSoC OpenAMP: スタートアップガイド (UG1186) [ 参照 13] を参照してください リブート ( 再起動 ) ユーザーは reboot コマンドを使用して APU PS またはシステムをリセットできます reboot コマンドはデフォルトでシステムをリセットします 必要に応じて reboot コマンドの範囲を APU または PS に変更できます リブート範囲を APU に変更する場合 : echo system_shutdown 2 0 > /sys/kernel/debug/zynqmp_pm/power リブート範囲を PS に変更する場合 : echo system_shutdown 2 1 > /sys/kernel/debug/zynqmp_pm/power リブート範囲をシステムに変更する場合 : echo system_shutdown 2 2 > /sys/kernel/debug/zynqmp_pm/power リセットが完了するとリブート範囲は再びシステムに設定されます サスペンド ( 一時停止 ) CPU および大半のペリフェラルがパワーダウンすると カーネルはサスペンドされます サスペンド状態から復帰するのに必要なシステムランステートが DRAM に格納されており セルフリフレッシュモードに設定されています カーネルコンフィギュレーションの要件 : 電力管理オプション [*] Suspend to RAM and standby [*] User space wakeup sources interface [*] Device power management core functionality デバイスドライバー SOC (System On Chip) 固有のドライバー - [*] Xilinx Zynq MPSoC driver support どのデバイスでも カーネルのサスペンドを防ぐことができます も参照してください カーネルをサスペンドする場合 : $ echo mem > /sys/power/state 98

99 第 9 章 : 電力管理フレームワークの概要 ウェークアップソース ウェークアップイベントが生じると カーネルはサスペンドモードから復帰します 使用可能なウェークアップソースを次に示します UART UART がウェークアップソースとして有効になっている場合 UART 入力によってカーネルはサスペンドモードから復帰します RTC カーネルコンフィギュレーションの要件 : サスペンド ( 一時停止 ) と同じ たとえば UART 入力で APU を起動する場合 : $ echo enabled > /sys/devices/platform/amba/ff serial/tty/ttyps0/power/wakeup RTC がウェークアップソースとして有効になっている場合 RTC タイマーが切れたときにカーネルはサスペンドモードから復帰します カーネルコンフィギュレーションの要件 : サスペンド ( 一時停止 ) と同じ たとえば RTC を開始して 10 秒後に APU を復帰させるには 次のようにします $ echo +10 > /sys/class/rtc/rtc0/wakealarm GPIO GPIO がウェークアップソースとして有効になっている場合 GPIO イベントによってカーネルはサスペンドモードから復帰します カーネルコンフィギュレーションの要件 : デバイスドライバー - 入力デバイスサポート [*] 一般的な入力層 ( キーボード マウスなどに必要 )(INPUT [=y]) [*] Keyboards (INPUT_KEYBOARD [=y]) [*] GPIO Buttons (CONFIG_KEYBOARD_GPIO=y) [*] Polled GPIO buttons たとえば GPIO ピンで APU を起動する場合 : $ echo enabled > /sys/devices/platform/gpio-keys/power/wakeup 99

100 第 9 章 : 電力管理フレームワークの概要 CPU の電力管理 CPU ホットプラグ ユーザーは CPU ホットプラグ制御インターフェイスを介して 必要に応じて 1 つまたは複数の APU コアをオンラインおよびオフラインで使用できます カーネルコンフィギュレーションの要件 : カーネルの機能 [*] Support for hot-pluggable CPUs 関連資料 たとえば CPU3 をオフラインで使用する場合 : $ echo 0 > /sys/devices/system/cpu/cpu3/online CPU アイドル 有効にすると APU コアがアイドル状態の時にカーネルは個々の APU コアの電力を削減できます カーネルコンフィギュレーションの要件 : CPU 電力管理 CPU アイドル - [*] CPU idle PM support 関連資料 - ARM CPU アイドルドライバー [*] Generic ARM/ARM64 CPU idle Driver

101 第 9 章 : 電力管理フレームワークの概要 cpuidle の sysfs インターフェイスは次のとおりです $ ls -lr /sys/devices/system/cpu/cpu0/cpuidle/ /sys/devices/system/cpu/cpu0/cpuidle/: drwxr-xr-x 2 root root 0 Jun 10 21:55 state0 drwxr-xr-x 2 root root 0 Jun 10 21:55 state1 /sys/devices/system/cpu/cpu0/cpuidle/state0: -r--r--r-- 1 root root 4096 Jun 10 21:55 desc -rw-r--r-- 1 root root 4096 Jun 10 21:55 disable -r--r--r-- 1 root root 4096 Jun 10 21:55 latency -r--r--r-- 1 root root 4096 Jun 10 21:55 name -r--r--r-- 1 root root 4096 Jun 10 21:55 power -r--r--r-- 1 root root 4096 Jun 10 21:55 residency -r--r--r-- 1 root root 4096 Jun 10 21:55 time -r--r--r-- 1 root root 4096 Jun 10 21:55 usage /sys/devices/system/cpu/cpu0/cpuidle/state1: -r--r--r-- 1 root root 4096 Jun 10 21:55 desc -rw-r--r-- 1 root root 4096 Jun 10 21:55 disable -r--r--r-- 1 root root 4096 Jun 10 21:55 latency -r--r--r-- 1 root root 4096 Jun 10 21:55 name -r--r--r-- 1 root root 4096 Jun 10 21:55 power -r--r--r-- 1 root root 4096 Jun 10 21:55 residency -r--r--r-- 1 root root 4096 Jun 10 21:55 time -r--r--r-- 1 root root 4096 Jun 10 21:55 usage 説明 : desc: アイドルステートに関する簡単な説明 ( 文字列 ) disable: このアイドルステートを無効にするためのオプション ( ブール型 ) 下記の注記参照 latency: このアイドルステートを終了するためのレイテンシ ( マイクロ秒 ) name: アイドルステートの名称 ( 文字列 ) power: このアイドルステート中の消費電力 ( ミリワット ) time: このアイドルステートの合計時間 ( マイクロ秒 ) usage: このステートに遷移した回数 ( カウント ) cpuidle ガバナーの sysfs インターフェイスは次のとおりです $ ls -lr /sys/devices/system/cpu/cpuidle/ /sys/devices/system/cpu/cpuidle/: -r--r--r-- 1 root root 4096 Jun 10 21:55 current_driver -r--r--r-- 1 root root 4096 Jun 10 21:55 current_governor_ro 101

102 第 9 章 : 電力管理フレームワークの概要 CPU 周波数 有効の場合 CPU コアは異なる動作クロック周波数間で切り替えることができます カーネルコンフィギュレーションの要件 : CPU 周波数スケーリング [*] CPU Frequency scaling デフォルト CPUFreq ガバナー - Userspace CPU 電力管理 [*] CPU 周波数スケーリング デフォルト CPUFreq ガバナー - Userspace - <*> Generic DT based cpufreq driver 利用可能な CPU スピードを確認 : $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cpu_freq CPU 周波数制御に userspace ガバナーを選択 : $ echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 現在の CPU スピードを確認 ( すべてのコアで同じ ): $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cpu_freq CPU スピードを変更 ( すべてのコアで同じ ): $ echo <freq> > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed デバイスの電力管理 クロックゲーティング 使用していないときにデバイスのクロックを停止する (Common Clock Framework とも呼ばれている ) カーネルコンフィギュレーションの要件 : 共通クロックフレームワーク [*] Support for Xilinx ZynqMP Ultrascale+ clock controllers ランタイム PM 使用していないときにデバイスの電源をオフにする個々のドライバーは ランタイム電力管理 (PM) をサポートしていない場合があることに注意してください カーネルコンフィギュレーションの要件 : 電力管理オプション [*] Suspend to RAM and standby 102

103 第 9 章 : 電力管理フレームワークの概要 デバイスドライバー SOC ( システムオンチップ ) 固有のドライバー - [*] Xilinx Zynq MPSoC driver support デバッグインターフェイス PM プラットフォームドライバーは すべての EEMI サービスへアクセスできるように標準の debugfs インターフェイスをエクスポートします このインターフェイスはテスト専用であり 不適切な使用や 引数の数 タイプ 有効範囲などをチェックする機能はありません このインターフェイスを使用して EEMI サービスを直接呼び出すと カーネルの電力管理動作を妨害してしまい 結果として予期しない動作やシステムクラッシュを招く可能性があることに注意してください カーネルコンフィギュレーションの要件 ( この順番 ): カーネルハッキング コンパイル時間チェックとコンパイラオプション - [*] Debug Filesystem デバイスドライバー SOC ( システムオンチップ ) 固有のドライバー - [*] Enable Xilinx Zynq MPSoC Power Management API debugfs functionality - [*] Xilinx Zynq MPSoC driver support ユーザーは任意の EEMI API を呼び出し可能 : [TODO: Need to confirm] を除く セルフサスペンド (Self Suspend) システムシャットダウン (System Shutdown) APU のパワーダウン強制 (Force Power Down the APU) APU のウェークアップ要求 (Request Wake-up the APU) コマンドライン入力 ユーザーは debugfs インターフェイスノードに EEMI API ID と最大 4 つの引数を書き込むことで EEMI サービスを呼び出すことができます API ID 関数 ID は EEMI API 関数の名称または ID 番号であり それぞれに文字列または整数を入力します 引数 引数の数や型は 選択した API 関数に依存します すべての引数は整数型で指定し EEMI 引数リストにあるその特定引数の型の序数になる必要があります 関数の説明 引数の型 および引数の数の詳細は EEMI API の仕様を参照してください 例 NODE_USB_0 の request_node API 呼び出しを実行する方法を示しています 103

104 第 9 章 : 電力管理フレームワークの概要 $ echo "REQUEST_NODE " > /sys/kernel/debug/zynqmp_pm/power コマンドリスト Get API Version API バージョンを取得します $ echo get_api_version > /sys/kernel/debug/zynqmp_pm/power Request Suspend 別の PU にセルフサスペンドするように要求します $ echo request_suspend <node> > /sys/kernel/debug/zynqmp_pm/power Self Suspend この PU がセルフサスペンドすることを PMU に通知します $ echo self_suspend <node> > /sys/kernel/debug/zynqmp_pm/power Force Power Down 別の PU の電源を強制的にオフにします $ echo force_powerdown <node> > /sys/kernel/debug/zynqmp_pm/power Abort Suspend サスペンド処理が中断されたことを PMU に通知します $ echo abort_suspend > /sys/kernel/debug/zynqmp_pm/power Request Wake-up 別の PU に対して サスペンド状態から復帰することを要求します $ echo request_wakeup <node> <set_address> <address> > /sys/kernel/debug/zynqmp_pm/power Set Wake-up Source ノードをウェークアップソースとして設定します $ echo set_wakeup_source <target> <wkup_node> <enable> > /sys/kernel/debug/zynqmp_pm/power Request Node ノードの使用を要求します $ echo request_node <node> > /sys/kernel/debug/zynqmp_pm/power Release Node 使用しないノードをリリースします 104

105 第 9 章 : 電力管理フレームワークの概要 $ echo release_node <node> > /sys/kernel/debug/zynqmp_pm/power Set Requirement ノード上の電源要件を設定します $ echo set_requirement <node> <capabilities> > /sys/kernel/debug/zynqmp_pm/power Set Max Latency ノードの最大ウェークアップレイテンシ要件を設定します $ echo set_max_latency <node> <latency> > /sys/kernel/debug/zynqmp_pm/power Get Node Status ノードのステータス情報を取得します ( ノードの割り当てにかかわらず すべての PU が任意のノードのステータスを確認できます ) $ echo get_node_status <node> > /sys/kernel/debug/zynqmp_pm/power Get Operating Characteristic ノードの動作特性を取得します $ echo get_operating_characteristic <node> > /sys/kernel/debug/zynqmp_pm/power Reset Assert 特定のリセットラインでアサート / ディアサートします $ echo reset_assert <reset> <action> > /sys/kernel/debug/zynqmp_pm/power Reset Get Status リセットラインのステータスを取得します $ echo reset_get_status <reset> > /sys/kernel/debug/zynqmp_pm/power MMIO Read メモリマップされた I/O アドレスからの読み出しを実行します $ echo mmio_read <address> > /sys/kernel/debug/zynqmp_pm/power 注記 : アドレスは 16 進数形式です ( 例 : 0xFFFF0000) MMIO Write メモリマップされた I/O アドレスへの書き込みを実行します $ echo mmio_write <mask> <address> <value> > /sys/kernel/debug/zynqmp_pm/power マスク アドレス 値は 16 進数形式です ( 例 : 0xFFFF0000) 105

106 第 9 章 : 電力管理フレームワークの概要 PM プラットフォームドライバー Linux 用 Zynq UltraScale+ MPSoC 電力管理機能は PM プラットフォームドライバーにカプセル化されています システムレベルの API 関数 (UG1200 の EEMI API 仕様の SPI 層を参照 ) はエクスポートされるため GPL 互換のライセンスを使用して別の Linux モジュールで呼び出すことが可能です 関数の宣言は include/linux/soc/xilinx/zynqmp/pm.h にあります 関数のインプリメンテーションは drivers/soc/xilinx/zynqmp/pm.c にあります ドライバーを適切に初期化するには Linux デバイスツリーに正しいノードが指定されている必要があります PM API ドライバーは ファームウェアノードを頼りにして PMU ファームウェアの存在を検出し PM フレームワークファームウェア層への呼び出しメソッド ( smc または hvc ) を決定し コールバック割り込み番号をレジスタに格納します ファームウェアノードには 次のプロパティが含まれています 1. compatible: xlnx,zynqmp-pm を必ず含む 2. method: PM フレームワークファームウェアを呼び出すメソッド smc にする必要がある 注記 : その他の情報は Linux の資料を参照してください Documentation/devicetree/bindings/soc/xilinx/zynq_mpsoc.txt 例 : zynqmp-firmware { compatible = "xlnx,zynqmp-pm"; method = "smc"; interrupt-parent = <&gic>; interrupts = <0 35 4>; }; ARM トラステッドファームウェア (ATF) ARM Trusted Firmware (ATF) は EL3 で実行されます EEMI API をサポートし IPI ベースの通信手段を介して PMU へ PM 要求を送信することによってスレーブノードの電源ステートを管理します ATF アプリケーションバイナリインターフェイス APU で実行可能な EL3 以下のすべての層は ATF を介して PMU と間接的に通信可能です ATF は 下位層 EL からのすべての呼び出しを受信し すべての要求を統合して PMU にそれらを送信します ARM の SMC 呼び出し規約に従うため 非セキュアワールドから ATF への PM 通信は 呼び出し規約で指定されているように事前定義された SMC 関数識別子と SMC サブレンジ所有権を使用して SiP のサービスコールとして実行されます APU 用 EEMI API の実装は SMC64 呼び出し規約にのみ準拠していることに注意してください OS またはハイパーバイザーソフトウェアレベルで作成された EEMI API 呼び出しは 32 ビットの API ID を SMC 関数識別子として渡し 最大 4 つの 32 ビット引数も渡します PM の引数はすべて 32 ビット値であるため 2 つのペアが結合されて 1 つの 64 ビット値を構成します ATF は最大 5 つの 32 ビット戻り値を返します 106

107 第 9 章 : 電力管理フレームワークの概要 処理完了またはエラーとその理由のいずれかを示すステータスを返す PM コントローラーからのその他の情報 API バージョンの確認 EEMI API を使用してスレーブノードを管理する前に ATF に実装されている EEMI API バージョンが PMU ファームウェアに実装されているバージョンと一致していることを確認する必要があります EEMI API バージョンは メジャーバージョンを示す上位 16 ビットとマイナーバージョンを示す下位 16 ビットに分離された 32 ビット値です これら両方のフィールドが ATF と PMU ファームウェアで同じになる必要があります EEMI API バージョンの確認方法 ATF に実装されている EEMI バージョンは ローカルの EEMI_API_VERSON フラグに定義されています ATF と PMU ファームウェアの EEMI API バージョンを確認するには ローカル関数 XPm_GetApiVersion() を使用できます これらのバージョンが異なる場合 この呼び出しでエラーがレポートされます 注記 : この EEMI API 呼び出しはバージョンに依存しません つまり すべての EEMI バージョンにこの呼び出しが実装されています PSCI PSCI (Power State Coordination Interface) は サスペンド シャットダウン リブートなど ARM プロセッサのシステム電源ステータスを制御するための標準インターフェイスです PSCI 仕様の詳細は を参照してください ATF が Linux からの PSCI 要求を処理します ATF は PSCI v0.2 のみをサポートしています (v0.1 の下位互換性サポートなし ) Linux カーネルには PSCI の標準サポートが付随します カーネルと ATF/PSCI のバインドに関する情報は を参照してください 表 9-1: ATF でサポートされる PSCI v0.2 の関数 関数説明サポート PSCI Version 実装された PSCI のバージョンを返す あり CPU Suspend CPU On CPU Off コアまたは上位レベルトポロジのノードで実行をサスペンド この呼び出しは コアがウェークアップイベントによって復帰することになっているアイドル状態のサブシステムで使用することを目的とする コアをパワーアップする 次のいずれかのコアをパワーアップするために使用 呼び出し元の監視ソフトウェアをまだ起動していない CPU_OFF 呼び出しで 前もって電源オフにされている 呼び出し元のコアの電源をオフにする この呼び出しは ホットプラグ状態で使用することを目的とする CPU_OFF によって電源をオフにするコアは CPU_ON のみに応答して再びパワーアップできる Affinity Info 呼び出し元がアフィニティインスタンスのステータスを要求できる あり あり あり あり Migrate ( オプション ) ユニプロセッサのトラステッド OS に コンテキストを特定コアに移行するように要求する あり 107

108 第 9 章 : 電力管理フレームワークの概要 表 9-1: ATF でサポートされる PSCI v0.2 の関数 ( 続き ) 関数説明サポート Migrate Info Type 呼び出し元がトラステッド OS に存在するマルチコアサポートのレベルを識別 あり ( オプション ) 可能になる Migrate Info Up CPU ユニプロセッサのトラステッド OS の場合 この関数は現在の常駐コアを返す あり ( オプション ) System Off システムをシャットダウンする あり System Reset システムをリセットする あり PSCI Features CPU Freeze ( オプション ) CPU Default Suspend ( オプション ) Node HW State ( オプション ) System Suspend ( オプション ) PSCI Set Suspend Mode ( オプション ) PSCI Stat Residency ( オプション ) PSCI Stat Count ( オプション ) PSCI v1.0 で導入 クエリ API を使用して 特定の PSCI 関数が実装されているかどうか またその機能情報について API に問い合わせる PSCI v1.0 で導入 コアを IMPLEMENTATION DEFINED 低電力ステートにする CPU_OFF とは異なり コアに割り込みをターゲットするには有効 ただし CPU_ON コマンドが発行されるまで コアは低電力状態を維持する必要がある PSCI v1.0 で導入 コアを IMPLEMENTATION DEFINED 低電力ステートにする CPU_SUSPEND とは異なり 呼び出し元が電力ステートパラメーターを指定するは必要ない PSCI v1.0 で導入 この API は システムの電力ドメイントポロジ内のノードの真の HW ステートを返すことを目的とする PSCI v1.0 で導入 RAM にサスペンドを実装する 最も低い電力ステートにする CPU_SUSPEND と同等 PSCI v1.0 で導入 この API を使用して CPU_SUSPEND で使用されるモードを設定して電源ステートを調整できる PSCI v1.0 で導入 コールドブート後にプラットフォームが指定された電源ステートで費やした時間を返す PSCI v1.0 で導入 コールドブート後にプラットフォームが指定された電源ステートを使用した回数を返す ありなしなしありありなしありあり PMU ファームウェア PMU ファームウェアには PM コントローラーと呼ばれるモジュールの 1 つとして EEMI サービスハンドラーが実装されています ( 別のタイプのサービスを処理するために PMU ファームウェアで実行されるモジュールがほかにもある ) 108

109 第 9 章 : 電力管理フレームワークの概要 電力管理イベント PM コントローラーはイベント駆動型であるため すべての操作は次のいずれかのイベントによってトリガーされます IPI0 割り込みでトリガーされる EEMI API イベント GPI1 割り込みでトリガーされるウェークアップイベント GPI2 割り込みでトリガーされるスリープイベント PIT2 割り込みでトリガーされるタイマーイベント EEMI API イベント EEMI API イベントは ソフトウェアで生成されるイベントです PM マスターが PMU への EEMI API 呼び出しを開始すると IPI 割り込みによってイベントがトリガーされます PM コントローラーは EEMI 要求を処理し 肯定応答を返すことができます ( 要求されている場合 ) 通常 ( 一部の例外を除く ) EEMI 要求はノードまたはマスターの電源ステートの変更をトリガーします ウェークアップイベント ウェークアップイベントは ハードウェアで生成されるイベントです これらはペリフェラル信号でトリガーされ PM マスターを復帰させる必要があることを示します すべてのウェークアップイベントは GPI1 割り込みでトリガーされます PM コントローラーでサポートされるウェークアップイベントを次に示します 関連する GIC インターフェイスのハードウェアリソースによってトリガーされる割り込みが発生し CPU を復帰させる必要があることを通知する GIC ウェークアップイベント サポートされる GIC ウェークアップイベントを次に示します APU[3:0] 各 APU プロセッサに 1 つのイベント RPU[1:0] 各 RPU プロセッサに 1 つのイベント GIC プロキシで指示される FPD ウェークアップイベント このウェークアップイベントは ウェークアップソースがサスペンドされる前に有効になったときにトリガーされます このイベントの目的は FPD の電源がオフになっているときに APU マスターのウェークアップをトリガーすることです FPD の電源がオフになっていない場合は いずれのウェークアップ信号も FPD ウェークアップを使用して伝搬されません 代わりに GIC での関連する割り込みが適切に有効になっている場合には GIC ウェークアップを使用してウェークアップ信号を伝搬できます RPU をターゲットとするすべてのウェークアップ信号は 関連する GIC ウェークアップを使用して伝搬されます スリープイベント スリープイベントは ソフトウェアで生成されるイベントです サスペンド処理を完了した後に CPU によってトリガーされるイベントであり 低電力ステートに遷移する準備が整ったことを PMU に通知する目的があります すべてのスリープイベントは GPI2 割り込みによってトリガーされます サポートされるスリープイベントを次に示します APU[3:0] 各 APU プロセッサに 1 つのイベント RPU[1:0] 各 RPU プロセッサに 1 つのイベント 109

110 第 9 章 : 電力管理フレームワークの概要 PM コントローラーが特定の CPU のスリープイベントを受信すると その CPU は低電力ステートになります タイマーイベント タイマーイベントは ハードウェアで生成されるイベントです 一定の時間が経過すると ハードウェアタイマーによってトリガーされます このイベントは電力管理タイムアウトアカウンティングに使用され PIT2 割り込みでトリガーされます EEMI API 呼び出しの一般的フロー 次の図は PM マスター ( 別の PU など ) で開始される呼び出しから始まる 標準的な API 呼び出しのシーケンスを示しています X-Ref Target - Figure 9-10 図 9-10: EEMI API 呼び出しシーケンス 上記の図には 4 つのアクターがあり 1 番目は PM マスター (RPU APU MicroBlaze プロセッサコアなど ) です 残りの 3 つのアクターは PMU の異なるソフトウェア層となります まず最初に PMU ファームウェアが IPI 割り込みを受信します この割り込みが電力管理関連の割り込みとして認識されると 電力管理モジュールに IPI 引数が渡されます その後 PM コントローラーが API 呼び出しを処理します 必要に応じて PMU ROM を呼び出して 電源アイランドや電力ドメインのパワーオン / パワーオフなどの電力管理動作を実行します 110

111 第 10 章 プラットフォーム管理 はじめに Zynq UltraScale+ MPSoC デバイスは 高性能と低消費電力の両立が要求される幅広い市場のアプリケーション向けに設計されています システムの消費電力は 各種サブシステムをソフトウェアでどれだけ高度に管理できるかによって決まります つまり 必要なときだけサブシステムの電源をオンにしたり より細かなレベルでパフォーマンスと消費電力のトレードオフを最適化することが求められます この章では 消費電力の管理に関する機能 およびソフトウェアを使用して各種パワーモードを制御する方法について説明します PS のプラットフォーム管理 スケーラブルなプラットフォーム管理ユニット (PMU) を実現するため Zynq UltraScale+ MPSoC デバイスは次に示す複数の電源ドメインをサポートしています フル電力ドメイン (FPD) 低電力ドメイン (LPD) バッテリ電源ドメイン PL パワードメイン PMU およびオプションのプラットフォーム管理ユニットファームウェア (PMUFW) 機能の詳細は Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] および Zynq UltraScale+ MPSoC 電力管理フレームワークユーザーガイド (UG1199) [ 参照 14] を参照してください PS のクロックを動的に変更する方法の詳細は 第 13 章 クロックおよび周波数管理 を参照してください PS ブロックは高度な機能と性能を備えています しかし同時に 動作の各段階で必要な機能とパフォーマンスに応じて PS ブロックの消費電力を最適化したいという強い要求も存在します Zynq UltraScale+ MPSoC デバイスには複数の電源レールがあります 各レールは個別にオフにすることも 異なる電圧を使用することもできます また 各電源レールに属するブロックの多くは電力ゲーティングを実装しており 個別にゲートオフが可能です これらの電力ゲーティングに対応したドメインの例としては ARM Cortex -A53/Cortex-R5 プロセッサ GPU ピクセルプロセッサ (PP) 大容量 RAM 個々の USB などがあります 111

112 第 10 章 : プラットフォーム管理 次に PS レベルでのプラットフォーム管理のブロック図を示します X-Ref Target - Figure 10-1 BPU OSC PS BBRAM RTC USB efuse AMS IOU CSU PMU Interconnect IPI PLLs SLCR ADMA GIC Dual R5 RPU TCM O C M Low power domain Battery power domain Full power domain SoC Debug DAP, RPU Debug Quadcore APU L2 RAM GPU PL 図 10-1: PS レベルのプラットフォーム管理消費電力に関して Zynq UltraScale+ MPSoC デバイスは PS レベルで次の動作モードをサポートしています フル電力動作モード 低電力動作モード ディープスリープモード シャットダウンモード バッテリ電源モード以降のセクションでは これらのモードについて説明します 112

113 第 10 章 : プラットフォーム管理 フル電力動作モード フル電力動作モード ( 図 10-1 に示したフル電力ドメイン ) では システム全体が動作します 全体の消費電力は 動作しているコンポーネントの数 ( それらのステートと動作周波数 ) によって決まります このモードでは 消費電力全体のほとんどをダイナミック消費電力が占めます フル電力動作モードでスタティック消費電力とダイナミック消費電力を最適化するため 大規模なモジュールはすべて専用の電源アイランドを持っており 使用しない間はシャットダウンできます フル電力動作モードの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 6 章 プラットフォーム管理ユニット ) を参照してください 低電力動作モード 低電力動作モードでは PMU RPU CSU IOU など PS の一部のブロック ( 図 10-1 で低電力ドメインとして表示したブロック ) への電源が供給されます このモードでは システム周波数の変更によって消費電力を調整できます CSU は SEU および改ざんからシステムを保護するために動作を継続する必要があります このモードでは システム周波数の変更によって消費電力を調整できます 低電力動作モードでは 低電力ドメインに属するすべてのペリフェラルが動作します 低電力動作モードに属するブロックの中で PLL デュアル Cortex-R5 USB および TCM/OCM ブロック RAM が電力ゲーティングに対応しています 各ブロックに対する電力ゲーティングは ソフトウェアで LPD_SLCR レジスタを設定して制御できます LPD_SLCR レジスタの詳細は SLCR レジスタのページ [ 参照 11] を参照してください * SATA PCIe および DisplayPort ブロックはフル電力ドメイン (FPD) に属します ディープスリープ動作モード ディープスリープモードは PS がサスペンド状態に移行して復帰信号を待つ特別なモードです 復帰は MIO USB または RTC でトリガーできます 復帰後 PS はブートプロセスを実行する必要がなく システムのセキュリティステートは維持されます ディープスリープモードでは ブートおよびセキュリティステートを維持したままデバイスの消費電力を最小限に抑えることができます このモードでは システムモニターや PLL など低電力ドメインに属するブロックを除き すべてのブロックがパワーダウンされます LPD では Cortex-R5 がパワーダウンします このモードではコンテキストを維持する必要があるため TCM と OCM はリテンションステートとなります 113

114 第 10 章 : プラットフォーム管理 シャットダウンモード シャットダウンモードでは APU コア全体がパワーダウンします このモードは APU にのみ適用可能です シャットダウン中 キャッシュを含むすべてのプロセッサステートが完全に失われます したがって PMU に対して APU コアのパワーダウンを要求する前に ソフトウェアですべてのステートを保存しておく必要があります CPU がシャットダウンした後 いずれかのペリフェラルからその CPU に関係する割り込みが発生すると CPU はパワーアップを開始する必要があります このため APU コアへの割り込みラインは PMU の割り込みコントローラーにも接続されており APU コアがパワーダウンするとこの割り込みラインが有効になります API のシャットダウン呼び出しについては Zynq UltraScale+ MPSoC 電力管理フレームワークユーザーガイド (UG1199) [ 参照 14] および Embedded Energy Management Interface Specification (UG1200) [ 参照 15] を参照してください 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 6 章 プラットフォーム管理ユニット の PMU のプログラミングモデル ) を参照してください バッテリ電源モード システムがオフの間も PS の一部の機能はバッテリで動作を継続する必要があります 次の機能は バッテリ電源ドメインの PS ( 図 10-1 参照 ) で動作します バッテリバックアップ RAM (BBRAM): セキュアコンフィギュレーション用のキーを格納 リアルタイムクロック (RTC): クリスタル I/O を含む Zynq UltraScale+ MPSoC デバイスにはバッテリ電源ドメインが 1 つしかありません したがって PS に実装された機能のみバッテリバックアップ可能です バッテリ電源ドメインに必要な I/O としては バッテリ電源パッドおよび RTC クリスタル用 I/O パッドがあります 復帰メカニズム 復帰メカニズムの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 6 章 プラットフォーム管理ユニット の PMU の動作 ) を参照してください メモリのプラットフォーム管理 Zynq UltraScale+ MPSoC デバイスは L2 キャッシュ OCM TCM などの大容量 RAM を備えています これらの RAM は クロックゲーティング 電力ゲーティング メモリリテンションモードなどの電力管理機能をサポートしています TCM と OCM は個別に電力ゲーティングとリテンションモードをサポートしています L2 キャッシュコントローラーはダイナミッククロックゲーティング リテンション およびシャットダウンモードをサポートしており 細かな消費電力の削減が可能です 114

115 第 10 章 : プラットフォーム管理 DDR コントローラー DDR コントローラーには 消費電力を削減する目的で次のメカニズムが実装されています クロック停止 : この機能を有効にすると DDR PHY は DRAM へのクロックを停止できます DDR2 と DDR3 では この機能はセルフリフレッシュモードの場合のみ有効です LPDDR2 では この機能はアイドル期間 パワーダウンモード セルフリフレッシュモード およびディープパワーダウンモードでも有効です プリチャージパワーダウン : この機能を有効にすると DDRC は動的にプリチャージパワーダウンモードを使用してアイドル期間の消費電力を削減します コントローラーが新規要求を受信すると 通常動作が再開します セルフリフレッシュ : アイドル期間中 DDR コントローラーは DRAM を動的にセルフリフレッシュモードに移行できます コントローラーが新規要求を受信すると 通常動作が再開します このモードでは DDRC コアロジックの電源を完全にオフにしても DRAM の内容が維持されます このため DDR 終端を制御する DDR3X クロックおよび DCI クロックを停止できます インターコネクトのプラットフォーム管理 インターコネクトは 複数の電源レールおよび電源アイランドにまたがっています これらの電源レールや電源アイランドは 別々にオン / オフが可能です インプリメンテーションを容易にするため 互いに通信を行う 2 つの電源ドメインに対するクロックは ほとんどの場合非同期とする必要があります したがって これらドメインの相互接続にはシンクロナイザーが必要です タイミング要件を緩和するため 電源ドメインはちょうどクロックが交差する場所に配置されます シンクロナイザーは 接続する 2 つのドメインのそれぞれに実装し ブリッジを形成する必要があります このブリッジはスレーブインターフェイスとマスターインターフェイスがそれぞれ 1 つずつで構成され 各インターフェイスは 1 つの電源およびクロックドメイン内に完全に包含されます このインターフェイスのクロック周波数は互いに独立して変更でき リセットもそれぞれ独立して実行できます 多電圧実装またはパワーダウンのためには ブリッジの両端の間にレベルシフターまたはクランプのいずれか または両方を実装する必要があります また このブリッジは次の方法でオープンなトランザクションを追跡します PMU からパワーダウン要求を受信すると ブリッジはその要求をログに記録します 過去の未処理のトランザクションが通常どおり処理されている間 トランザクションカウンターが 0 になるまで新規トランザクションはすべてエラーを返します カウンターが 0 になるとブリッジは PMU に肯定応答 (ACK) を返し ブリッジに接続されたマスターまたはスレーブをシャットダウンしても安全であることを通知します インターコネクト内のすべてのブリッジがアイドルになった場合のみ インターコネクト全体がシャットダウンします 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 6 章 プラットフォーム管理ユニット の PMU インターコネクト ) を参照してください 115

116 第 10 章 : プラットフォーム管理 カスタム PMU ファームウェアの使用 パワーアップおよびスリープ管理以外に PMU は高度なシステム監視および電力管理アルゴリズムを実装したユーザープログラムを実行できます このモードでは APU または RPU は電力管理プログラムをインバウンド LPD スイッチ経由で PMU 内部の RAM にコピーします PMU は カスタムプラットフォーム管理ユニットファームウェア (PMUFW) と呼ばれている 高度なシステム監視および電力管理アルゴリズムを実装したカスタムプログラムを実行できます 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 6 章 プラットフォーム管理ユニット の PMU のプログラミングモデル ) を参照してください カスタム PMU ファームウェアの作成には ザイリンクス SDK を使用できます SDK には PMUFW テンプレートのソースコードと必要なライブラリサポートが含まれています SDK プロジェクトの作成方法は 第 5 章 ソフトウェア開発フロー を参照してください 電力管理フレームワーク API の電力管理については Zynq UltraScale+ MPSoC 電力管理フレームワークユーザーガイド (UG1199) [ 参照 14] および Embedded Energy Management Interface Specification (UG1200) [ 参照 15] を参照してください 注記 : ザイリンクス API に関する ベアメタル FreeRTOS Linux の電力管理方法に違いはありません 116

117 第 11 章 リセット はじめに Zynq UltraScale+ MPSoC デバイスのリセットブロックはシステムに対する外部および内部リセット入力を処理し すべてのペリフェラル APU および RPU に対するリセット要件を確実に満たします リセットブロックはデバイスのプログラマブルロジックに対してリセットを生成し PS ブロックと PL ブロックに対して個別にリセットのアサートが可能です この章では システムレベルリセットおよびモジュール単位のリセットの仕組みについて説明します システムレベルリセット Zynq UltraScale+ MPSoC デバイスは APU や RPU などのブロック単位 または FPD や LPD といった電源ドメイン単位での個別リセットが可能です システムレベルリセットには 次に示す複数の方法があります パワーオンリセット (POR) システムリセット (SRST_B) デバッグシステムリセット システムレベルリセットフローの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 38 章 リセットシステム ) を参照してください 117

118 第 11 章 : リセット ブロックレベルリセット PS のみのリセットはシステムリセットのサブセットとして実装できますが PS のみのリセットが開始される前に PS-PS 間の AXI トランザクションを正しい手順で終了させるためのソフトウェアをユーザーが提供する必要があります PS 専用のリセット PS 専用のリセットは PL を動作させたまま PL を再起動します このリセットは ハードウェアのエラー信号やソフトウェアによるレジスタ書き込みによってトリガーできます エラー信号によって PS 専用のリセットが発生した場合 PL にもそのエラーを通知できます これにより PL は PR の開始準備ができます PS 専用のリセットシーケンスは 次の方法で実装できます [ErrorLogic] PS のみのリセットが必要となるようなエラー割り込みをアサートします この要求は PMU に割り込みとして送信されます [PMU-FW] PMU エラー (=>PS のみのリセット ) をセットして PL に通知します PS 専用のリセットシーケンスの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 38 章 リセットシステム の PS のみのリセット ) を参照してください APU リセット APU の各 CPU コアは ソフトウェアで個別にリセットできます APU MPCore リセットは FPD WDT またはソフトウェアによるレジスタ書き込みでトリガーできます ただし APU MPCore は APU への要求および APU からの要求を正しい手順で終了せずにリセットされます これは 重大な障害が発生した場合は FPD リセットを使用するためです APU のリセットは 主にソフトウェアデバッグに使用します APU リセットシーケンスの詳細は Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] を参照してください RPU リセット Cortex -R5 の各コアは 個別にリセットできます ロックステップモードでは Cortex-R5_0 のみをリセットすると両方の Cortex-R5 コアがリセットされます このリセットは エラーまたはソフトウェアによるレジスタ書き込みでトリガーできます ロックステップエラーで Cortex-R5 リセットをトリガーして RPU をリセットおよび再起動できます Cortex-R5 のリセットを開始する前に その Cortex-R5 のイングレス ( 入力 ) およびイーグレス ( 出力 ) トランザクションを正しい手順で終了する必要があります RPU リセットシーケンスは 次の方法で実装できます 118

119 第 11 章 : リセット FPD リセット FPD リセットは フル電力ドメイン (FPD) すべてをリセットし エラーまたはソフトウェアによるレジスタ書き込みでトリガーできます エラー信号によって FPD リセットが発生した場合 LPD と PL の両方にエラーを通知する必要があります FPD リセットは FPD パワーアップシーケンスを利用して実装できます ただし FPD のリセットを開始する前に FPD のイングレス ( 入力 ) およびイグレス ( 出力 ) AXI トランザクションを正しい手順で終了する必要があります FPD リセットシーケンスは PL リセットになります Zynq UltraScale+ MPSoC デバイスには PMU ブロックからの汎用出力ピンがあり これを使用して PL 内のブロックをリセットできます また EMIO インターフェイスを使用した GPIO でも PL 内のブロックをリセットできます リセットフローの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 38 章 リセットシステム ) を参照してください リセット用ソフトウェア API の詳細は 第 10 章 プラットフォーム管理 の カスタム PMU ファームウェアの使用 を参照してください 119

120 第 12 章 高速バスインターフェイス はじめに Zynq UltraScale+ MPSoC デバイスには 高速シリアルインターフェイス用のシリアル入出力ユニット (SIOU) が 1 つあります このユニットは PCIe USB 3.0 DisplayPort SATA およびイーサネットなどのプロトコルをサポートします SIOU ブロックは PS のフル電力ドメイン (FPD) に属します Zynq UltraScale+ MPSoC デバイスの低電力ドメイン (LPD) に属する USB およびイーサネットコントローラーブロックも PS-GTR トランシーバーを共有します 4 つの PS-GTR トランシーバーは インターコネクトマトリックスによって複数のコントローラーブロック間でさまざまな組み合わせの多重化が可能です SIOU 内の信号は レジスタブロックを使用して制御および監視します この章では 高速インターフェイスプロトコルのコンフィギュレーションフローについて説明します 詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 29 章 高速 PS-GTR トランシーバーインターフェイス ) を参照してください USB 3.0 Zynq UltraScale+ MPSoC の USB 3.0 コントローラーは 2 つの独立したデュアルロールデバイス (DRD) コントローラーで構成されます これらのコントローラーは いつでもホストモードまたはデバイスモードに個別に設定できます USB 3.0 DRD コントローラーからシステムソフトウェアへは AXI (Advanced extensible Interface (AXI) スレーブインターフェイスを介して xhci (extensible Host Controller Interface) が提供されます このコントローラーには内部 DMA エンジンがあり AXI マスターインターフェイスを使用してデータを転送します 3 つのデュアルポート RAM コンフィギュレーションは RX データ FIFO TX データ FIFO およびディスクリプター / レジスタキャッシュを実装します 120

121 第 12 章 : 高速バスインターフェイス 次に USB をマスストレージデバイスとして設定する方法をフローチャートで示します X-Ref Target - Figure 12-1 Start USB config initialize Call a function to hookup the handler for control packets Is Req type== Std dev req? No Is Req type== class req? Yes Yes Handle standard device request Handle the class request No Is Req type== vendor req? No Stall on endpoint 0 Yes Do nothing Call a function to hookup the handler for mass storage No Is Req == Mass storage reset? Yes Do nothing (Status phase is handled by driver) No Is Req == Get_Maz_LUN No Stall the endpoint 0 Yes Prepare a URB with number of LUNs A X 図 12-1: USB フローの例 (USB 初期化 ) 121

122 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-2 A Prepare device descriptors Prepare configuration descriptors Call a function to hookup the bulkout handler Is phase == Command? No Yes Parse CBW Is phase == Data? Yes Send reduced block command (RBC) Write operation No Send command status wrapper (CSW) Call a function to hookup the bulk In handler Is phase == Status? Yes Read the packet data into Receive Buffer No Is phase == Data? Yes Is RBC Mode sense == 1? No Yes Send CSW with mode No Send CSW with mode Initialize the driver interrupt controller Config initialize for GIC Connect the interrupt controller B X 図 12-2: USB フローの例 ( バルク IN およびバルク OUT ハンドラーの接続および割り込みコントローラーの初期化 ) 122

123 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-3 B Enable all the required interrupts Connect the interrupt controller to the interrupt handling logic in ARM Enable interrupts in the ARM Start USB Controller Wait for interrupts X 図 12-3: 割り込みの有効化および USB コントローラーの起動 USB コントローラーの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 31 章 USB 2.0/3.0 ホスト / デバイス /OTG コントローラー ) を参照してください ギガビットイーサネットコントローラー ギガビットイーサネットコントローラー (GEM) は IEEE イーサネット規格 (IEEE Std ) に準拠した 10/100/1000Mb/s イーサネット MAC を実装しており 半二重または全二重 10/100 モード および全二重 1000 モードでの動作が可能です プロセッシングシステム (PS) には 4 つのギガビットイーサネットコントローラーがあります MAC の機能および動作モードはレジスタで設定します DMA コントローラーは AXI (Advanced extensible Interface) 経由でメモリに接続します このコントローラーは MAC コントローラーの FIFO インターフェイスに接続されており パケットデータをスキャッターギャザー方式でプロセッシングシステムに格納できます 123

124 第 12 章 : 高速バスインターフェイス 次に 1 パケットのデータを送信するようにイーサネットコントローラーを設定する場合の例をフローチャートで示します X-Ref Target - Figure 12-4 Start Set the Baudrate Set the Line Control register Invalidate the Data Cable if Data Cache is emabled Get the Configuration of Axi Ethernet Hardware Is AXI FIFO present? No Return error and exit Yes Initialize the AXI FIFO instance Initialize AXI Ethernet hardware Error initializing? No Return error and exit Yes Set the MAC address Yes Is Phy-type==MII? Set the loopback speed to 100 No Set the loopback speed to 1G Get the PHY interface Detect the PHY address Read the PHY Model A 図 12-4: イーサネットフローの例 ( イーサネットコントローラーの初期化 ) 124

125 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-5 図 12-5: イーサネットフローの例 ( イーサネットパラメーターの設定および送信の開始 ) 125

126 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-6 B Wait for status of the transmitted packet Receive the packet Error Yes Return error and exit No Get the length of the arrived data Read the packet data received Verify the received frame length Validate the frame data Stop Ethernet Hardware Stop X 図 12-6: イーサネットフローの例 ( データの受信および検証 ) イーサネットコントローラーの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 34 章 ギガビットイーサネットコントローラー ) を参照してください 126

127 第 12 章 : 高速バスインターフェイス PCI Express Zynq UltraScale+ MPSoC デバイスには PCI Express v2.1 準拠の統合ブロック AXI-PCIe ブリッジ および DMA モジュールで構成される PCIe コントローラーがあります AXI-PCIe ブリッジは PCIe と AXI を高速にブリッジ接続します 次に データ転送用に PCIe ルートコンプレックスを設定する場合の例をフローチャートで示します X-Ref Target - Figure 12-7 Yes No 図 12-7: PCIe フローの例 ( レガシ割り込みの有効化および PCIe ルートバスの作成 ) 127

128 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-8 A Clear the PHY of any existing bits RGMII mode PHY specific register initialization Configure the Interface modes Set the speed & put the PHY in reset Put the PHY in loopback Error Setting the PHY loopback? Yes Return Error and Exit No Set PHY<->MAC Data clock Delay Start the AXI Ethernet Device Setup the packet to be transmitted Clear out the receive packet memory area Calculate the frame length (not including FCS) Wait for FIFO to become available Write the frame data to FIFO Initiate the transit Wait for status of the transmitted packet B X 図 12-8: PCIe フローの例 (PCIe パラメーターの設定および送信の初期化 ) 128

129 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 12-9 B Get the legacy interrupt number Invalid interrupt number Yes Return error and exit No Register the legacy interrupt handler Failed to register handle? Yes Return error and exit No Enable all legacy interrupts Get the bridge resources Error getting resources? No Create PCIe root bus Yes Return error and exit Error creating root bus? No Yes Return error and exit C X 図 12-9: PCIe フローの例 ( レガシ割り込みの有効化および PCIe ルートバスの作成 ) 129

130 第 12 章 : 高速バスインターフェイス X-Ref Target - Figure 図 12-10: PCIe フローの例 (MSI 割り込みの有効化および割り込みの待機 ) 注記 : エンドポイントの操作については このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 30 章 PCI Express コントローラー ) を参照してください 130

131 第 12 章 : 高速バスインターフェイス PCIe ブリッジと ECAM のメモリ空間をマップ後 ECAM 変換を実行できるよう ECAM を有効にします 次に バス範囲を取得してバス番号を設定し primary secondary および subordinate バス番号を書き込みます 割り込みシステムをセットアップする際は レガシ割り込みを含むすべての種類の割り込みを有効にする必要があります PCI ホストブリッジデバイスノードの ranges プロパティを解析し その内容に基づいてリソースマップをセットアップできます ルートバスを作成するには PCIe ルートバスを割り当て そのバスに初期リソースを追加します MSI ビットがセットされている場合 MSI (Message Signalling Interrupt) を有効にする必要があります MSI 割り込みを設定したら PCIe スロットをスキャンして PCIe バス全体をエニュメレートし スキャンしたバスに対してバスリソースを割り当てます これで PCIe デバイスをシステムに追加できます PCI Express の詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 19 章 DMA コントローラー ) およびこのセクション ( 同マニュアルの第 30 章 PCI Express コントローラー ) を参照してください 131

132 第 13 章 クロックおよび周波数管理 はじめに Zynq UltraScale+ MPSoC デバイスアーキテクチャには PS の位相ロックループ (PLL) ブロックを使用して ある一定の入力クロック周波数から複数のクロックを生成するプログラマブルなクロックジェネレーターがあります 各 PLL からの出力クロックを PS の各種ペリフェラルの基準クロックとして使用します USB およびイーサネットペリフェラルを除き UART や SD などのペリフェラルではデバイスの周波数設定を動的に変更できます この章では これらペリフェラルの動作周波数を動的に変更する方法について説明します ペリフェラルの周波数変更 ペリフェラルの動作周波数は 各ペリフェラルのクロックコンフィギュレーションレジスタで周波数を直接設定して変更できます Zynq UltraScale+ MPSoC の BSP には ユーザー要件に合わせてペリフェラルのクロック周波数を動的に変更するための API が用意されています 次の表に ペリフェラルの周波数を変更するために使用するスタンドアロン API を示します 表 13-1: スタンドアロン API XSDPS_change_clkfreq API XSPIPS_setclkprescaler XSPIPS_getclkprescaler XRtcPSu_calculatecalibration XQSPIPSU_setclkprescaler 説明 SD のクロック周波数を変更します SPI 周波数のプリスケーラです オシレーターの周波数を変更します QSPI のクロック周波数を変更します 132

133 第 13 章 : クロックおよび周波数管理 Linux アプリケーションの場合 すべてのペリフェラルの周波数をデバイスツリーファイルで設定します 次のコードの一部は ペリフェラルのクロック設定方法を示しています ps7_qspi_0: ps7-qspi@0xff0f0000 { #address-cells = <0x1>; #size-cells = <0x0>; #bus-cells = <0x1>; clock-names = ref_clk, pclk ; compatible = xlnx,usmp-gqspi, cdns,spi-r1p6 ; stream-connected-dma = <0x26>; clocks = <0x1e 0x1e>; dma = <0xb>; interrupts = <0xf>; num-chip-select = <0x2>; reg = <0x0 0xff0f0000 0x1000 0x0 0xc x >; speed-hz = <0xbebc200>; xlnx,fb-clk = <0x1>; xlnx,qspi-clk-freq-hz = <0xbebc200>; xlnx,qspi-mode = <0x2>; エラー条件の発生を防ぐため ペリフェラルのクロック周波数を変更する前にそのペリフェラルを停止しておく必要があります ペリフェラルのクロック周波数を変更するには 次の手順を実行します 1. クロック周波数を変更するペリフェラル (IP) に関する遷移を停止します 2. レジスタの設定を変更して IP を停止します 3. ペリフェラルのクロック周波数を変更します 4. IP に対してソフトリセットを発行します 5. IP を再起動します Zynq UltraScale+ MPSoC のクロックジェネレーターの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の クロッキング ) を参照してください 133

134 第 14 章 ターゲット開発プラットフォーム はじめに この章では Quick Emulator (QEMU) および Zynq UltraScale+ MPSoC ボード / キットなどの Zynq UltraScale+ MPSoC デバイス向けに提供される各種開発プラットフォームについて説明します QEMU QEMU は Intel 互換の Linux ホストシステム上で動作するシステムエミュレーションモデルです ザイリンクス QEMU は コマンドラインから渡されたデバイスツリーに基づいてカスタムマシンモデルを生成するフレームワークを実装しています QEMU の詳細は Zynq UltraScale+ MPSoC クイックエミュレーターユーザーガイド (UG1169) [ 参照 8] を参照してください ボード / キット ザイリンクスは 開発者向けに Zynq UltraScale+ MPSoC ZCU102 評価キットを提供しています ZCU102 評価キットの詳細は ザイリンクスアンサー : Zynq UltraScale+ MPSoC ZCU102 評価キット - ZCU102 入門ガイド [ 参照 33] を参照してください 各種 Zynq UltraScale+ MPSoC デバイスについては Zynq UltraScale+ MPSoC の製品ページ [ 参照 7] を参照してください 134

135 第 15 章 Bootgen イメージの生成 はじめに Bootgen は Zynq UltraScale+ MPSoC デバイスに適したブータブルイメージを作成するスタンドアロンツールです このプログラムがパーティションリストの先頭にヘッダーブロックを付けてブートイメージを構築します オプションとして ビットストリームおよびパーティションを暗号化して Bootgen を使用して認証できます システムのブートフラッシュメモリへ直接プログラムできるファイルが 1 つ出力されます 認証および暗号化をサポートする周辺ファイルも生成されます Bootgen は ザイリンクスソフトウェア開発キット (SDK) に統合されており 自動的にイメージを生成します また Bootgen はコマンドラインで実行することも コマンドラインで開始するスクリプトで実行することもできます BIF ファイルのパラメーター 表 15-1: BIF ファイルのパラメーター パラメーター [aeskeyfile] [init] [udf_bh] [headersignature] [ppkfile] [pskfile] [spkfile] [sskfile] [spksignature] 暗号化に使用する AES キーファイル <.nky key file> レジスタ初期化ファイル 説明とオプション 最大 256 の初期化ペアをサポートします ブートヘッダーの User Defined Field ( ユーザー定義フィールド ) へコピーされる最大 40 バイトのデータを含むファイルをインポートします ヘッダーシグネチャを認証ヘッダーにインポートします パーティションの認証に使用するプライマリ公開キー (PPK) ファイル <.pub.pem key files> パーティションの認証に使用するプライマリ非公開キー (PSK) ファイル <.pub.pem key files> パーティションの認証に使用するセカンダリ公開キー (SPK) ファイル <.pub.pem key files> パーティションの認証に使用するセカンダリ非公開キー (SSK) ファイル <.pub.pem key files> SPK シグネチャを認証証明にインポートします 135

136 第 15 章 : Bootgen イメージの生成 表 15-1: BIF ファイルのパラメーター ( 続き ) パラメーター [fsbl_config] [auth_params] [keysrc_encryption] [pmufw_image] これらのパラメーターで FSBL イメージを設定します r5_single a53_x32 a53_x64 r5_dual bh_auth_enable auth_sha2_enable bi_integrity_sha3 auth_only opt_key shutter pufhd_bh puf4kmode 例 : [fsbl_config] a53_x64 opt_key, 認証パラメーター ppk_select = <0/1>, spk_id = <4-byte value> FSBL を実行するコアを指定します ブートヘッダー認証イネーブル - ブートイメージの RSA 認証を実行します (PK ハッシュおよび SPK ID の検証を除く ) 統合およびテスト専用です RSA 認証中に SHA2 を使用します ( デフォルトは SHA3) SHA3 でブートイメージのインテグリティをチェックします 注記 : bi_integrity_sha3 は 今後のリリースで廃止されるため checksum=sha3 オプションを使用してください ブートイメージは RSA 署名のみ FSBL の復号化は実行しません Block-0 の復号化にオプションキーを使用します オプションキーはセキュアヘッダーにあります シャッターオープン時間 (SOPEN * 16) - 16 は PUF 生成の APB_CLK クロックサイクル数です PUF ヘルパーデータが実際に efuse 上でプログラムされ ブートヘッダー内に配置されている場合 PUF ブートヘッダーの暗号化用に提供されるヘルパーデータが 4K であることを Bootgen に指示します 例 : [auth_params] ppk_select=0; spk_id=0x 暗号のキーソース efuse_red_key bbram_red_key bh_blk_key efuse_blk_key 説明とオプション PMU ファームウェアイメージ <PMU ELF file> この PMU パーティションは BootROM によって FSBL と一緒にロードされます 136

137 第 15 章 : Bootgen イメージの生成 表 15-1: BIF ファイルのパラメーター ( 続き ) パラメーター [bootloader] FSBL を含むパーティション authentication = <value> checksum = <value> encryption = <value> load = <value> offset = <value> reserve = <value> startup = <value> udf_data = <filename> presign =<filename> blocks = <block sizes> パーティションの認証を有効にするかどうかを設定します none rsa 説明とオプション パーティションのチェックサムを有効にするかどうかを設定します none sha3 パーティションの暗号化を有効にするかどうかを設定します none aes パーティションのロードアドレスを設定します イメージ内の絶対オフセットを設定します パーティションのメモリサイズを維持します このサイズになるまでパーティションにパディングが追加されます ロード後のパーティションのエントリアドレスを設定します この識別子は 実行しないパーティションでは無視されます パーティション認証証明の User Defined Field ( ユーザー定義フィールド ) へコピーされる最大 56 バイトのデータを含むファイルをインポートします パーティションシグネチャをパーティション認証証明にインポートします 暗号キーローリングのブロックサイズを指定します blocksize(# blocks);blocksize(# blocks);blocksize(#blocks) 例 : blocks=4096(2);1024;2048;1024(2) このパーティションは次の 6 つのブロックで構成されます : 4096 バイト 2 つめは 4096 バイト 3 つめは 1024 バイト 4 つめは 2048 バイト 5 つめは 1024 バイト 6 つめは 1024 バイト 7 つめはパーティションの残りバイト 137

138 第 15 章 : Bootgen イメージの生成 表 15-1: BIF ファイルのパラメーター ( 続き ) destination_cpu = <value> destination_device = <value> exception_level = <value> TrustZone partition_owner = <value> bh_key_iv bh_keyfile puf_file パラメーター 説明とオプション パーティションをどのコアで実行するかを指定します a5x-0 a5x-1 a5x-2 a5x-3 r5-0 r5-1 r5-lockstep pmu 注記 : デスティネーション CPU として PMU が選択されている場合は FSBL でパーティションがロードされて PMU に渡されます パーティションのデスティネーションを指定します ps pl pmufw xip 注記 : このオプションは 今後のリリースで廃止される予定です destination_device=pmufw を使用している場合は destination_cpu=pmu で対応します destination_device=xip を使用している場合は xip_mode 属性で対応します コアに設定する例外レベルを指定します el-0 el-1 el-2 el-3 コアに TrustZone セキュリティを設定します パーティションをロードするパーティションオーナーを設定します fsbl uboot 難読化キーを復号化する際に使用する初期化ベクター レッドキーおよび PUF キーから生成されるブラックキーは.txt フォーマットで取り込まれ PUF ブートヘッダー暗号化用の入力として提供されます 同じシリコン上で生成されるヘルパーデータは.txt フォーマットで取り込まれ PUF ブートヘッダー暗号化用の入力として Bootgen に提供されます 138

139 第 15 章 : Bootgen イメージの生成 Bootgen コマンドラインのオプション 表 15-2: Bootgen コマンドラインのオプション 引数 -arch <type> -bif_help -efuseppkbits <filename> -fill <hex_byte> -generate_hashes -generate_keys auth <option> アーキテクチャを選択します zynq zynqmp fpga オプション BIF ヘルプサマリをプリントアウトします PK ハッシュを書き込む efuse ファイルの名前を指定します このオプションにより 32 バイト (SHA2 認証を選択した場合 ) または 48 バイト (SHA3 認証を選択した場合 ) の直接ハッシュがパディングなしで生成されます フィル用に使用するバイトを指定します PKCS#1v1.5 フォーマットのパディング付き SHA2/SHA3 ハッシュファイルを出力するよう指定します PEM または RSA 形式で認証キーを生成します pem rsa 例 : bootgen arch zynqmp image test.bif generate_keys auth pem 注記 : test.bif には生成するキーのパスが含まれている必要があります image: { [ppkfile] C:\path\to\ppk.txt [pskfile] C:\path\to\psk.txt [spkfile] C:\path\to\spk.txt [sskfile] C:\path\to\ssk.txt } -h -help ヘルプサマリをプリントアウトします -image <filename.bif> ブートイメージフォーマット (BIF) ファイル名 -log <option> 現在の作業ディレクトリに次のメッセージタイプのログファイルを生成します error warning info debug trace 139

140 第 15 章 : Bootgen イメージの生成 表 15-2: Bootgen コマンドラインのオプション ( 続き ) -o <filename> 出力ファイルを指定します.bin.mcs -p <partname> 暗号キー (.nky) を生成する際にザイリンクスのデバイス名を指定します このデバイス名はそのままキーファイルの Device 行にコピーされます -process_bitstream -split <option> 引数 ビットストリームを.bin ファイルと.mcs ファイルのどちらで処理および出力するかを指定します たとえば BIF ファイルのビットストリームに暗号化を選択した場合 出力は暗号化されたビットストリームです ブートイメージを指定したファイル形式でパーティションごとに出力します bin mcs -w <option> 出力ファイルを上書きするかどうかを指定します on off オプション 注記 : オプションのない -w は w on として解釈されます Bootgen コマンドの例 次に BootGen のコマンド例を示します bootgen arch zynqmp -image bootimage.bif w -o BOOT.bin 140

141 第 15 章 : Bootgen イメージの生成 ブートイメージのフォーマット ブートイメージは ブートヘッダー 異なるイメージのパーティションとパーティションヘッダーで構成されます 次の表にブートイメージを示します 表 15-3: ブートイメージ ブートヘッダー (BH) イメージタイプオフセットバイト 0x0 0xB8 レジスタの初期化 0xB8 0x800 イメージヘッダーテーブル (IHT) イメージヘッダー (IH1-IHn) パーティションヘッダーテーブル (BPHT1-PHTm) ワードオフセットは BH の 0x98 第一ヘッダーワードオフセットは IHT の 0xC 第一ヘッダーワードオフセットは BH の 0x9C 0x40 n*(0x40) m*(0x40) ヘッダー認証 ( オプション ) ワードオフセットは IHT の 0x10 0xEC0 パーティション 1 (FSBL) ( 暗号化 - オプション ) パーティション -1 RSA 認証証明 ( オプション ) パーティション 2 ( ビットストリーム ) ( 暗号化 - オプション ) パーティション -2 RSAS 認証証明 ( オプション ) パーティション 3 (U-boot) ( 暗号化 - オプション ) パーティション -3 RSA 認証証明 ( オプション ) パーティション 4 (Linux イメージ ) ( 暗号化 - オプション ) パーティション -4 RSA 認証証明 ( オプション ) ワードオフセットは PHT1 の 0x20 ワードオフセットは PHT1 の 0x34 ワードオフセットは PHT2 の 0x20 ワードオフセットは PHT2 の 0x34 ワードオフセットは PHT3 の 0x20 ワードオフセットは PHT3 の 0x34 ワードオフセットは PHT4 の 0x20 ワードオフセットは PHT4 の 0x34 ワード長は PHT1 の 0x08 0xEC0 ワード長は PHT2 の 0x08 0xEC0 ワード長は PHT3 の 0x08 0xEC0 ワード長は PHT4 の 0x08 0xEC0 ブートヘッダーテーブル ブートヘッダーの詳細は 前のセクションの ブートイメージのフォーマット を参照してください 141

142 第 15 章 : Bootgen イメージの生成 レジスタ初期化テーブル 表 15-4: レジスタ初期化 ( オフセット パラメーター および説明 ) アドレスオフセットパラメーター説明 0xB8 ~ 0x8B4 レジスタ初期化ペア <address> <value> このワード領域には MIO マルチプレクサーおよびフラッシュクロックの PS レジスタを初期化するシンプルなシステムが含まれます これにより FSBL イメージを OCM にコピーする前 または XIP でフラッシュから実行する前に MIO マルチプレクサーを完全にコンフィギュレーションでき フラッシュデバイスのクロックを帯域幅が最大となるように設定できます 合計 256 ペアです address = 0xFFFFFFFF は そのレジスタをスキップして値を無視することを意味します 未使用のレジスタフィールドはすべて address=0xffffffff および value = 0x0 に設定する必要があります イメージヘッダーテーブル 次の表に 生成された BOOT.BIN イメージのさまざまなフィールドについて説明します BOOT.BIN ファイルの詳細は このセクション ( Zynq UltraScale+ MPSoC テクニカルリファレンスマニュアル (UG1085) [ 参照 10] の第 11 章 ブートおよびコンフィギュレーション の ブートイメージのフォーマット ) を参照してください 表 15-5: イメージヘッダーテーブル アドレスオフセットパラメーター説明 0x00 バージョン 0x x04 イメージヘッダー数 イメージ内のパーティション数 0x08 第一パーティションヘッダーワード 第一パーティションヘッダーを指すポインター オフセット 0x0C 第一イメージヘッダーワードオフ 第一イメージヘッダーを指すポインター セット 0x10 ヘッダー認証証明ワードオフセット ヘッダー認証照明を指すポインター 0x14 ブートデバイス 0 - 同じブートデバイス 1 - QSPI 2 - NAND 3 - SD 4 - MMC 5 - USB 6 - ETHERNET 7 - PCIE 8 - SATA 142

143 第 15 章 : Bootgen イメージの生成 表 15-5: イメージヘッダーテーブル ( 続き ) アドレスオフセット パラメーター 説明 0x18 0x38 予約 予約 (0x0) 0x3C チェックサム イメージヘッダーの以前のワードの合計値 パーティションヘッダーテーブル 表 15-6: パーティションヘッダー ( オフセット パラメーター および説明 ) アドレスオフセット パラメーター 説明 0x00 パーティションデータワード長 (x4) 暗号化されたパーティションの長さ 0x04 抽出されたデータワード長 (x4) 暗号化されていないパーティションデータの長さ 0x08 合計パーティションワード長 ( 認証証明を含む ) (x4) 暗号化 パディング 拡張 認証をすべて合計した長さ 0x0C 次のパーティションヘッダーオフセット 次のパーティションヘッダーの位置 0x10 デスティネーション実行アドレス LO ロード後のこのパーティションの実行可能アドレス 0x14 デスティネーション実行アドレス HI ロード後のこのパーティションの実行可能アドレス 0x18 デスティネーションロードアドレス LO このパーティションがロードされる RAM アドレス 0x1C デスティネーションロードアドレス HI このパーティションがロードされる RAM アドレス 0x20 実パーティションワードオフセット ブートイメージの開始に対するパーティションデータの位置 0x24 属性 表 15-7 参照 0x28 予約 内部で使用 0x2C チェックサムワードオフセット (x4) ブートイメージ内のチェックサムワードの位置 0x30 予約 内部で使用 0x34 認証証明ワードオフセット (x4) ブートイメージ内の認証証明の位置 0x38 未使用 0x x3C ヘッダーチェックサム パーティションヘッダーの以前のワードの合計値 表 15-7: パーティションヘッダーの属性 ビット フィールド名 説明 31:24 予約 23 ベクターの位置 1 - HIVEC 0 - LOVEC 22:20 ビットストリームブロックサイズ 非認証ビットストリームおよびその他のすべてのパーティション 010-8MB ブロック ( 認証が有効にされている場合 ) 19 早期ハンドオフ 143

144 第 15 章 : Bootgen イメージの生成 表 15-7: パーティションヘッダーの属性 ( 続き ) ビット フィールド名 説明 18 エンディアン 0 - リトルエンディアン 1 - ビッグエンディアン 17:16 パーティションオーナー 0 - FSBL 1 - UBOOT 予約 15 RSA シグネチャの有無 0 - RSA 認証証明なし 1 - RSA 認証証明あり 14:12 チェックサムタイプ 0 - なし 1 - MD5 2 ~ 7 - 予約 11:8 デスティネーション CPU 0 - なし 1 - A A A A R R R5-ロックステップ 8 ~ 15 - 予約 7 暗号化の有無 0 - 暗号化なし 1 - 暗号化あり 6:4 デスティネーションデバイス 0 - なし 1 - PS 2 - PL 3 - PMU FW 4 - XIP 5 ~ 15 - 予約 3 A5X 実行ステート 0 - AARCH64 ( デフォルト ) 1 - AARCH32 2:1 例外レベル 0 - EL0 1 - EL1 2 - EL2 3 - EL3 0 TrustZone 0 - 非セキュア 1 - セキュア 144

145 第 15 章 : Bootgen イメージの生成 認証証明 表 15-8: 認証証明アドレスオフセット パラメーター 説明 0x00 認証証明のヘッダー 表 15-9 を参照してください 0x04 SPK ID 32 ビット SPK ID 0x08 ユーザー定義フィールド (UDF) 56 バイト 0x40 プライマリモジュラス 512 バイト 0x240 P プライマリモジュラス拡張 512 バイト 0x440 P プライマリ公開指数 4 バイト - 推奨 0x x444 K プライマリゼロパディング 60 バイト - 0x x480 セカンダリモジュラス 512 バイト 0x680 S セカンダリモジュラス拡張 512 バイト 0x880 P セカンダリ公開指数 4 バイト - 推奨 0x x884 K セカンダリゼロパディング 60 バイト - 0x x8c0 SPK シグネチャ 512 バイト 0xAC0 ブートヘッダーシグネチャ 512 バイト 0xCC0 パーティションシグネチャ 512 バイト 認証証明のヘッダー 表 15-9: ビット フィールド名 および説明 ビット フィールド名 説明 31:18 予約 0 17:16 PPK キー選択 0: PPK0 1: PPK1 15:14 認証証明フォーマット 00: PKCS #1 v1.5 13:12 認証証明バージョン 00: 現在の認証証明 11 PPK キータイプ 0: ハッシュキー 10:9 PPK キーソース 0: efuse 8 SPK イネーブル 1: SPK イネーブル 7:4 公開キー強度 0: 予約 1: :3: 予約 145

146 第 15 章 : Bootgen イメージの生成 表 15-9: ビット フィールド名 および説明 ( 続き ) ビット フィールド名 説明 3:2 ハッシュアルゴリズム 1:0 公開キーアルゴリズム 0: 予約 1: RSA 2: 予約 注記 : キーおよび認証証明の生成は オープン Linux ツールで実行されます パッケージには付属しません 146

147 付録 A Power Management Framework Appendix XilPM Argument Value Definitions Introduction The following are value definitions for the various arguments used in the power management APIs, as defined in the file pm_defs.h. Node IDs: XPmNodeId The following table lists the defined Node IDs in the Zynq UltraScale + MPSoC device. enum XPmNodeId { 表 A-1: XPmNodeIds NODE_UNKNOWN Node IDs for Zynq UltraScale+ MPSoC Devices NODE_APU APU Controller 1U NODE_APU_0 APU Controller 0 2U NODE_APU_1 APU Controller 1 3U NODE_APU_2 APU Controller 2 4U NODE_APU_3 APU Controller 3 5U NODE_RPU RPU Controller 6U NODE_RPU_0 RPU Controller 0 7U NODE_RPU_1 RPU Controller 1 8U NODE_PL PL Controller 9U NODE_FPD FPD Controller 10U NODE_OCM_BANK_0 OCM Memory Tile 0 11U NODE_OCM_BANK_1 OCM Memory Tile 1 12U NODE_OCM_BANK_2 OCM Memory Tile 2 13U NODE_OCM_BANK_3 OCM Memory Tile 3 14U NODE_TCM_0_A Tightly coupled memory (0A) 15U NODE_TCM_0_B Tightly coupled memory (0B) 16U NODE_TCM_1_A Tightly coupled memory (1A) 17U 0U 147

148 付録 A: Power Management Framework Appendix 表 A-1: XPmNodeIds (Cont d) Node IDs for Zynq UltraScale+ MPSoC Devices NODE_TCM_1_B Tightly coupled memory (1B) 18U NODE_L2 L2 Cache system 19U NODE_GPU_PP_0 Graphics Processing Unit 0 20U NODE_GPU_PP_1 Graphics Processing Unit 1 21U NODE_USB_0 USB Controller 0 22U NODE_USB_1 USB Controller 1 23U NODE_TTC_0 Triple-timer Counter 0 24U NODE_TTC_1 Triple-timer Counter 1 25U NODE_TTC_2 Triple-timer Counter 2 26U NODE_TTC_3 Triple-timer Counter 3 27U NODE_SATA SATA Controller 28U NODE_ETH_0 Gigabit Ethernet Controller 0 29U NODE_ETH_1 Gigabit Ethernet Controller 1 30U NODE_ETH_2 Gigabit Ethernet Controller 2 31U NODE_ETH_3 Gigabit Ethernet Controller 3 32U NODE_UART_0 UART Controller 0 33U NODE_UART_1 UART Controller 1 34U NODE_SPI_0 SPI Controller 0 35U NODE_SPI_1 SPI Controller 1 36U NODE_I2C_0 SPI Controller 2 37U NODE_I2C_1 SPI Controller 3 38U NODE_SD_0 SD/SDIO Controller 0 39U NODE_SD_1 SD/SDIO Controller 1 40U NODE_DP DisplayPort Controller 41U NODE_GDMA FPD DMA Controller 42U NODE_ADMA APU DMA 43U NODE_NAND NAND Controller 44U NODE_QSPI QSPI Controller 45U NODE_GPIO GPIO Controller 46U NODE_CAN_0 CAN Controller 0 47U NODE_CAN_1 CAN Controller 1 48U NODE_AFI AFI Block 49U NODE_APLL APU PLL 50U NODE_VPLL Video PLL 51U NODE_DPLL DDR Controller PLL 52U NODE_RPLL RPU PLL 53U 148

149 付録 A: Power Management Framework Appendix 表 A-1: XPmNodeIds (Cont d) Node IDs for Zynq UltraScale+ MPSoC Devices NODE_IOPLL Peripheral I/O PLL 54U NODE_DDR DDR Controller 55U NODE_IPI_APU IPI APU Controller 56U NODE_IPI_RPU_0 IPI APU Controller 0 57U NODE_GPU Graphics Processing Unit Controller 58U NODE_PCIE PCIE Controller 59U Acknowledge Request Types: XPmRequestAck enum XPmRequestAck { REQUEST_ACK_NO = 1, REQUEST_ACK_BLOCKING, REQUEST_ACK_NON_BLOCKING, }; Abort Reasons: XPmAbortReason enum XPmAbortReason { ABORT_REASON_WKUP_EVENT = 100, ABORT_REASON_PU_BUSY, ABORT_REASON_NO_PWRDN, ABORT_REASON_UNKNOWN, }; Suspend Reasons enum XPmSuspendReason { SUSPEND_REASON_PU_REQ = 201, SUSPEND_REASON_ALERT, SUSPEND_REASON_SYS_SHUTDOWN, }; Operating Characteristic Types: XPmOpCharType enum XPmOpCharType { PM_OPCHAR_TYPE_POWER = 1, PM_OPCHAR_TYPE_ENERGY, PM_OPCHAR_TYPE_TEMP, }; Notify Event Types: XPmNotifyEvent enum XPmNotifyEvent { EVENT_STATE_CHANGE = 1, EVENT_ZERO_USERS = 2, EVENT_ERROR_CONDITION = 4, }; 149

150 付録 A: Power Management Framework Appendix Reset Line IDs enum XPmReset { XILPM_RESET_PCIE_CFG = 1000, XILPM_RESET_PCIE_BRIDGE, XILPM_RESET_PCIE_CTRL, XILPM_RESET_DP, XILPM_RESET_SWDT_CRF, XILPM_RESET_AFI_FM5, XILPM_RESET_AFI_FM4, XILPM_RESET_AFI_FM3, XILPM_RESET_AFI_FM2, XILPM_RESET_AFI_FM1, XILPM_RESET_AFI_FM0, XILPM_RESET_GDMA, XILPM_RESET_GPU_PP1, XILPM_RESET_GPU_PP0, XILPM_RESET_GPU, XILPM_RESET_GT, XILPM_RESET_SATA, XILPM_RESET_ACPU3_PWRON, XILPM_RESET_ACPU2_PWRON, XILPM_RESET_ACPU1_PWRON, XILPM_RESET_ACPU0_PWRON, XILPM_RESET_APU_L2, XILPM_RESET_ACPU3, XILPM_RESET_ACPU2, XILPM_RESET_ACPU1, XILPM_RESET_ACPU0, XILPM_RESET_DDR, XILPM_RESET_APM_FPD, XILPM_RESET_SOFT, XILPM_RESET_GEM0, XILPM_RESET_GEM1, XILPM_RESET_GEM2, XILPM_RESET_GEM3, XILPM_RESET_QSPI, XILPM_RESET_UART0, XILPM_RESET_UART1, XILPM_RESET_SPI0, XILPM_RESET_SPI1, XILPM_RESET_SDIO0, 150

151 付録 A: Power Management Framework Appendix XILPM_RESET_SDIO1, XILPM_RESET_CAN0, XILPM_RESET_CAN1, XILPM_RESET_I2C0, XILPM_RESET_I2C1, XILPM_RESET_TTC0 XILPM_RESET_TTC1, XILPM_RESET_TTC2, XILPM_RESET_TTC3, XILPM_RESET_SWDT_CRL, XILPM_RESET_NAND, XILPM_RESET_ADMA, XILPM_RESET_GPIO, XILPM_RESET_IOU_CC, XILPM_RESET_TIMESTAMP, XILPM_RESET_RPU_R50, XILPM_RESET_RPU_R51, XILPM_RESET_RPU_AMBA, XILPM_RESET_OCM, XILPM_RESET_RPU_PGE, XILPM_RESET_USB0_CORERESET, XILPM_RESET_USB1_CORERESET, XILPM_RESET_USB0_HIBERRESET, XILPM_RESET_USB1_HIBERRESET, XILPM_RESET_USB0_APB, XILPM_RESET_USB1_APB, XILPM_RESET_IPI, XILPM_RESET_APM_LPD, XILPM_RESET_RTC, XILPM_RESET_SYSMON, XILPM_RESET_AFI_FM6, XILPM_RESET_LPD_SWDT, XILPM_RESET_FPD, XILPM_RESET_RPU_DBG1, XILPM_RESET_RPU_DBG0, XILPM_RESET_DBG_LPD, XILPM_RESET_DBG_FPD, XILPM_RESET_APLL, XILPM_RESET_DPLL, XILPM_RESET_VPLL, XILPM_RESET_IOPLL, XILPM_RESET_RPLL, 151

152 付録 A: Power Management Framework Appendix XILPM_RESET_GPO3_PL_0, XILPM_RESET_GPO3_PL_1, XILPM_RESET_GPO3_PL_2, XILPM_RESET_GPO3_PL_3, XILPM_RESET_GPO3_PL_4, XILPM_RESET_GPO3_PL_5, XILPM_RESET_GPO3_PL_6, XILPM_RESET_GPO3_PL_7, XILPM_RESET_GPO3_PL_8, XILPM_RESET_GPO3_PL_9, XILPM_RESET_GPO3_PL_10, XILPM_RESET_GPO3_PL_11, XILPM_RESET_GPO3_PL_12, XILPM_RESET_GPO3_PL_13, XILPM_RESET_GPO3_PL_14, XILPM_RESET_GPO3_PL_15, XILPM_RESET_GPO3_PL_16, XILPM_RESET_GPO3_PL_17, XILPM_RESET_GPO3_PL_18, XILPM_RESET_GPO3_PL_19, XILPM_RESET_GPO3_PL_20, XILPM_RESET_GPO3_PL_21, XILPM_RESET_GPO3_PL_22, XILPM_RESET_GPO3_PL_23, XILPM_RESET_GPO3_PL_24, XILPM_RESET_GPO3_PL_25, XILPM_RESET_GPO3_PL_26, XILPM_RESET_GPO3_PL_27, XILPM_RESET_GPO3_PL_28, XILPM_RESET_GPO3_PL_29, XILPM_RESET_GPO3_PL_30, XILPM_RESET_GPO3_PL_31, }; XPm_Notifier struct The XPm_Notifier struct is the structure to be passed in XPm_RegisterNotifier. typedef struct XPm_Notifier { void (*const callback)(xpm_notifier* const notifier); enum XPmNodeId node; enum XPmNotifyEvent event; u32 flags; volatile u32 oppoint; volatile u32 received; 152

153 付録 A: Power Management Framework Appendix XPm_Notifier* next; } XPm_Notifier; Struct Members 表 A-2: Struct Members Name callback node event flags oppoint received next Description Custom callback handler to be called when the notification is received. The custom handler executes from the interrupt context; hence, it shall return quickly and must not block! (enables event-driven notifications), Node argument (the node to receive notifications about). Event argument (the event type to receive notifications about). Flags: Currently the flags only contain the wake option in bit0. flags = 1: wake up on event flags = 0: do not wake up (only notify if awake), no buffering or queueing will take place Operating point of node in question. Contains the value updated when the last event notification is received. User shall not modify this value while the notifier is registered. How many times the notification has been received - to be used by application (enables polling). User shall not modify this value while the notifier is registered. Pointer to next notifier in linked list. Must not be modified while the notifier is registered. User shall not ever modify this value. XPm_NodeStatus struct The XPm_NodeStatus struct is used to pass node status information. typedef struct XPm_NodeStatus { u32 status; u32 requirements; u32 usage; } XPm_NodeStatus; Struct Members 表 A-3: Struct Members Name status requirements usage Description Node power state. Current requirements asserted on the node (slaves only). Usage information (which master is currently using the slave). This information is used for slave nodes only. It is encoded based on the IPI bits for the masters. If the respective bit is set, the corresponding master is currently using the node. 153

154 付録 A: Power Management Framework Appendix XilPM Error Codes Introduction The following is a list of possible error codes returned by the PM API. 表 A-4: Error Codes and Explanations Error Code XST_FAILURE XST_INVALID_PARAM XST_NO_FEATURE XST_PM_CONFLICT XST_PM_DOUBLE_REQ XST_PM_INTERNAL XST_PM_INVALID_NODE XST_PM_NO_ACCESS XST_PM_ABORT_SUSPEND Explanation Power management controller has failed to comply with the request, because of a hardware/pmu-rom failure or because the API cannot be processed in the given circumstances. An argument is either out-of-range or its value is not admissible in the respective API call. The requested feature is not available for the selected PM slave. Conflicting requirements have been asserted when more than one PU is using the same PM slave. XPm_RequestNode: A PU has already been assigned access to a PM slave and has issued a duplicate request for that PM slave. Unexpected error in the PMU state machine. Should be reported as a bug. The API function does not apply to the node passed as argument. The PU does not have access to the requested node or operation. The target PU has aborted suspend. 154

155 Appendix B: Xilinx Standard C Libraries 155

156 Xilinx Standard C Libraries Overview The Xilinx Software Development Kit (SDK) libraries and device drivers provide standard C library functions, as well as functions to access peripherals. The SDK libraries are automatically configured based on the Microprocessor Software Specification (MSS) file. These libraries and include files are saved in the current project lib and include directories, respectively. The -I and -L options of mb-gcc are used to add these directories to its library search paths. Standard C Library (libc.a) The standard C library, libc.a, contains the standard C functions compiled for the MicroBlaze processor or the Cortex A9 processor. You can find the header files corresponding to these C standard functions in the <XILINX_SDK>/gnu/<processor>/<platform>/<processor-lib>/include folder, where: <XILINX_SDK> is the Xilinx SDK installation path <processor> is ARM or MicroBlaze <platform> is Solaris (sol), Windows (nt), or Linux (lin) <processor-lib> is arm-xilinx-eabi or microblaze-xilinx-elf The lib.c directories and functions are: _ansi.h fastmath.h machine/ reent.h stdlib.h utime.h _syslist.h fcntl.h malloc.h regdef.h string.h utmp.h ar.h float.h math.h setjmp.h sys/ assert.h grp.h paths.h signal.h termios.h ctype.h ieeefp.h process.h stdarg.h time.h dirent.h imits.h pthread.h stddef.h nctrl.h errno.h locale.h pwd.h stdio.h unistd.h Programs accessing standard C library functions must be compiled as follows: For MicroBlaze processors: mb-gcc <C files> For Cortex A9 processors: arm-xilinx-eabi-gcc <C files> The libc library is included automatically. For programs that access libm math functions, specify the lm option. For more information on the C runtime library, see MicroBlaze Processor Reference Guide (UG081). 156

157 Xilinx C Library (libxil.a) The Xilinx C library, libxil.a, contains the following object files for the MicroBlaze processor embedded processor: _exception_handler.o _interrupt_handler.o _program_clean.o _program_init.o Default exception and interrupt handlers are provided. The libxil.a library is included automatically. Programs accessing Xilinx C library functions must be compiled as follows: mb-gcc <C files> Memory Management Functions The MicroBlaze processor and Cortex A9 processor C libraries support the standard memory management functions such as malloc(), calloc(), and free(). Dynamic memory allocation provides memory from the program heap. The heap pointer starts at low memory and grows toward high memory. The size of the heap cannot be increased at runtime. Therefore an appropriate value must be provided for the heap size at compile time. The malloc() function requires the heap to be at least 128 bytes in size to be able to allocate memory dynamically (even if the dynamic requirement is less than 128 bytes). The return value of malloc must always be checked to ensure that it could actually allocate the memory requested. Arithmetic Operations Software implementations of integer and floating point arithmetic is available as library routines in libgcc.a for both processors. The compiler for both the processors inserts calls to these routines in the code produced, in case the hardware does not support the arithmetic primitive with an instruction. MicroBlaze Processor Details of the software implementations of integer and floating point arithmetic for MicroBlaze processors are listed below: 157

158 Integer Arithmetic By default, integer multiplication is done in software using the library function mulsi3. Integer multiplication is done in hardware if the -mno-xl-soft-mul mb-gcc option is specified. Integer divide and mod operations are done in software using the library functions divsi3 and modsi3. The MicroBlaze processor can also be customized to use a hard divider, in which case the div instruction is used in place of the divsi3 library routine. Double precision multiplication, division and mod functions are carried out by the library functions muldi3, divdi3, and moddi3 respectively. The unsigned version of these operations correspond to the signed versions described above, but are prefixed with an u instead of. Floating Point Arithmetic All floating point addition, subtraction, multiplication, division, and conversions are implemented using software functions in the C library. Thread Safety The standard C library provided with SDK is not built for a multi-threaded environment. STDIO functions like printf(), scanf() and memory management functions like malloc() and free() are common examples of functions that are not thread-safe. When using the C library in a multi-threaded environment, proper mutual exclusion techniques must be used to protect thread unsafe functions. Modules Input/Output Functions Input/Output Functions Overview The SDK libraries contains standard C functions for I/O, such as printf and scanf. These functions are large and might not be suitable for embedded processors. The prototypes for these functions are available in the stdio.h file. The C standard I/O routines such as printf, scanf, vfprintf are, by default, line buffered. To change the buffering scheme to no buffering, you must call setvbuf appropriately. For example: setvbuf (stdout, NULL, _IONBF, 0); These Input/Output routines require that a newline is terminated with both a CR and LF. Ensure that your terminal CR/LF behavior corresponds to this requirement. For more information on setting the standard input and standard output devices for a system, see Embedded System Tools Reference Manual (UG1043). In addition to the standard C functions, the SDK processors library provides the following smaller I/O functions: 158

159 Functions void print (char ) void putnum (int) void xil_printf (const char ctrl1,...) Function Documentation void print ( char ) This function prints a string to the peripheral designated as standard output in the Microprocessor Software Specification (MSS) file. This function outputs the passed string as is and there is no interpretation of the string passed. For example, a \n passed is interpreted as a new line character and not as a carriage return and a new line as is the case with ANSI C printf function. void putnum ( int ) This function converts an integer to a hexadecimal string and prints it to the peripheral designated as standard output in the MSS file. void xil_printf ( const char ctrl1,... ) xil_printf() is a light-weight implementation of printf. It is much smaller in size (only 1 Kb). It does not have support for floating point numbers. xil_printf() also does not support printing of long (such as 64-bit) numbers. About format string support: The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there can be (in order) zero or more flags, an optional minimum field width and an optional precision. Supported flag characters are: The character % is followed by zero or more of the following flags: 0 The value should be zero padded. For d, x conversions, the converted value is padded on the left with zeros rather than blanks. If the 0 and - flags both appear, the 0 flag is ignored. - The converted value is to be left adjusted on the field boundary. (The default is right justification.) Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given. About supported field widths Field widths are represented with an optional decimal digit string (with a nonzero in the first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it is padded with spaces on the left (or right, if the left-adjustment flag has been given). The supported conversion specifiers are: d The int argument is converted to signed decimal notation. 159

160 l The int argument is converted to a signed long notation. x The unsigned int argument is converted to unsigned hexadecimal notation. The letters abcdef are used for x conversions. c The int argument is converted to an unsigned char, and the resulting character is written. s The const char argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating NULL character; if a precision is specified, no more than the number specified are written. If a precision s given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating NULL character. 160

161 Appendix C: Standalone Library Reference v

162 Xilinx Hardware Abstraction Layer API Overview This section describes the Xilinx Hardware Abstraction Layer API, These APIs are applicable for all processors supported by Xilinx. Modules Assert APIs IO interfacing APIs Definitions for available xilinx platforms Data types for Xilinx Software IP Cores Customized APIs for memory operations Xilinx software status codes Test utilities for memory and caches Assert APIs Overview The xil_assert.h file contains the assert related functions. Macros #define Xil_AssertVoid(Expression) #define Xil_AssertNonvoid(Expression) #define Xil_AssertVoidAlways() #define Xil_AssertNonvoidAlways() Typedefs typedef void( Xil_AssertCallback) (const char8 File, s32 Line) 162

163 Functions void Xil_Assert (const char8 File, s32 Line) void XNullHandler (void NullParameter) void Xil_AssertSetCallback (Xil_AssertCallback Routine) Variables u32 Xil_AssertStatus s32 Xil_AssertWait Macro Definition Documentation #define Xil_AssertVoid( Expression ) This assert macro is to be used for void functions. This in conjunction with the Xil_AssertWait boolean can be used to accomodate tests so that asserts which fail allow execution to continue. Expression expression to be evaluated. If it evaluates to false, the assert occurs. void unless the Xil_AssertWait variable is true, in which case no return is made and an infinite loop is entered. #define Xil_AssertNonvoid( Expression ) This assert macro is to be used for functions that do return a value. This in conjunction with the Xil_AssertWait boolean can be used to accomodate tests so that asserts which fail allow execution to continue. Expression expression to be evaluated. If it evaluates to false, the assert occurs. 0 unless the Xil_AssertWait variable is true, in which case no return is made and an infinite loop is entered. 163

164 #define Xil_AssertVoidAlways( ) Always assert. This assert macro is to be used for void functions. Use for instances where an assert should always occur. void unless the Xil_AssertWait variable is true, in which case no return is made and an infinite loop is entered. #define Xil_AssertNonvoidAlways( ) Always assert. This assert macro is to be used for functions that do return a value. Use for instances where an assert should always occur. void unless the Xil_AssertWait variable is true, in which case no return is made and an infinite loop is entered. Typedef Documentation typedef void( Xil_AssertCallback) (const char8 File, s32 Line) This data type defines a callback to be invoked when an assert occurs. The callback is invoked only when asserts are enabled Function Documentation void Xil_Assert ( const char8 File, s32 Line ) Implement assert. Currently, it calls a user-defined callback function if one has been set. Then, it potentially enters an infinite loop depending on the value of the Xil_AssertWait variable. file line filename of the source linenumber within File 164

165 void XNullHandler ( void NullParameter ) Null handler function. This follows the XInterruptHandler signature for interrupt handlers. It can be used to assign a null handler (a stub) to an interrupt controller vector table. NullParameter arbitrary void pointer and not used. void Xil_AssertSetCallback ( Xil_AssertCallback Routine ) Set up a callback function to be invoked when an assert occurs. If a callback is already installed, then it will be replaced. routine callback to be invoked when an assert is taken This function has no effect if NDEBUG is set Variable Documentation u32 Xil_AssertStatus This variable allows testing to be done easier with asserts. An assert sets this variable such that a driver can evaluate this variable to determine if an assert occurred. 165

166 s32 Xil_AssertWait This variable allows the assert functionality to be changed for testing such that it does not wait infinitely. Use the debugger to disable the waiting during testing of asserts. IO interfacing APIs Overview The xil_io.h file contains the interface for the general IO component, which encapsulates the Input/Output functions for processors that do not require any special I/O handling. Functions u16 Xil_EndianSwap16 (u16 Data) u32 Xil_EndianSwap32 (u32 Data) static INLINE u8 Xil_In8 (UINTPTR Addr) static INLINE u16 Xil_In16 (UINTPTR Addr) static INLINE u32 Xil_In32 (UINTPTR Addr) static INLINE u64 Xil_In64 (UINTPTR Addr) static INLINE void Xil_Out8 (UINTPTR Addr, u8 Value) static INLINE void Xil_Out16 (UINTPTR Addr, u16 Value) static INLINE void Xil_Out32 (UINTPTR Addr, u32 Value) static INLINE void Xil_Out64 (UINTPTR Addr, u64 Value) static INLINE u16 Xil_In16LE (UINTPTR Addr) static INLINE u32 Xil_In32LE (UINTPTR Addr) static INLINE void Xil_Out16LE (UINTPTR Addr, u16 Value) static INLINE void Xil_Out32LE (UINTPTR Addr, u32 Value) static INLINE u16 Xil_In16BE (UINTPTR Addr) static INLINE u32 Xil_In32BE (UINTPTR Addr) static INLINE void Xil_Out16BE (UINTPTR Addr, u16 Value) static INLINE void Xil_Out32BE (UINTPTR Addr, u32 Value) Function Documentation 166

167 u16 Xil_EndianSwap16 ( u16 Data ) Perform a 16-bit endian converion. Data 16 bit value to be converted converted value. u32 Xil_EndianSwap32 ( u32 Data ) Perform a 32-bit endian converion. Data 32 bit value to be converted converted value. static INLINE u8 Xil_In8 ( UINTPTR Addr ) [static] Performs an input operation for an 8-bit memory location by reading from the specified address and returning the Value read from that address. Addr contains the address to perform the input operation at. The Value read from the specified input address. 167

168 static INLINE u16 Xil_In16 ( UINTPTR Addr ) [static] Performs an input operation for a 16-bit memory location by reading from the specified address and returning the Value read from that address. Addr contains the address to perform the input operation at. The Value read from the specified input address. static INLINE u32 Xil_In32 ( UINTPTR Addr ) [static] Performs an input operation for a 32-bit memory location by reading from the specified address and returning the Value read from that address. Addr contains the address to perform the input operation at. The Value read from the specified input address. static INLINE u64 Xil_In64 ( UINTPTR Addr ) [static] Performs an input operation for a 64-bit memory location by reading the specified Value to the the specified address. Addr Value contains the address to perform the output operation at. contains the Value to be output at the specified address. 168

169 static INLINE void Xil_Out8 ( UINTPTR Addr, u8 Value ) [static] Performs an output operation for an 8-bit memory location by writing the specified Value to the the specified address. Addr Value contains the address to perform the output operation at. contains the Value to be output at the specified address. static INLINE void Xil_Out16 ( UINTPTR Addr, u16 Value ) [static] Performs an output operation for a 16-bit memory location by writing the specified Value to the the specified address. Addr Value contains the address to perform the output operation at. contains the Value to be output at the specified address. 169

170 static INLINE void Xil_Out32 ( UINTPTR Addr, u32 Value ) [static] Performs an output operation for a 32-bit memory location by writing the specified Value to the the specified address. Addr Value contains the address to perform the output operation at. contains the Value to be output at the specified address. static INLINE void Xil_Out64 ( UINTPTR Addr, u64 Value ) [static] Performs an output operation for a 64-bit memory location by writing the specified Value to the the specified address. Addr Value contains the address to perform the output operation at. contains the Value to be output at the specified address. static INLINE u16 Xil_In16LE ( UINTPTR Addr ) [static] Perform a little-endian input operation for a 16-bit memory location by reading from the specified address and returning the value read from that address. Addr contains the address at which to perform the input operation. The value read from the specified input address with the proper endianness. The return value has the same endianness as that of the processor. For example, if the processor is big-endian, the return value is the byte-swapped value read from the address. 170

171 static INLINE u32 Xil_In32LE ( UINTPTR Addr ) [static] Perform a little-endian input operation for a 32-bit memory location by reading from the specified address and returning the value read from that address. Addr contains the address at which to perform the input operation. The value read from the specified input address with the proper endianness. The return value has the same endianness as that of the processor. For example, if the processor is big-endian, the return value is the byte-swapped value read from the address. static INLINE void Xil_Out16LE ( UINTPTR Addr, u16 Value ) [static] Perform a little-endian output operation for a 16-bit memory location by writing the specified value to the specified address. Addr Value contains the address at which to perform the output operation. contains the value to be output at the specified address. The value has the same endianness as that of the processor. For example, if the processor is big-endian, the byteswapped value is written to the address. static INLINE void Xil_Out32LE ( UINTPTR Addr, u32 Value ) [static] Perform a little-endian output operation for a 32-bit memory location by writing the specified value to the specified address. Addr Value contains the address at which to perform the output operation. contains the value to be output at the specified address. The value has the same endianness as that of the processor. For example, if the processor is big-endian, the byteswapped value is written to the address. 171

172 static INLINE u16 Xil_In16BE ( UINTPTR Addr ) [static] Perform an big-endian input operation for a 16-bit memory location by reading from the specified address and returning the value read from that address. Addr contains the address at which to perform the input operation. The value read from the specified input address with the proper endianness. The return value has the same endianness as that of the processor. For example, if the processor is little-endian, the return value is the byte-swapped value read from the address. static INLINE u32 Xil_In32BE ( UINTPTR Addr ) [static] Perform a big-endian input operation for a 32-bit memory location by reading from the specified address and returning the value read from that address. Addr contains the address at which to perform the input operation. The value read from the specified input address with the proper endianness. The return value has the same endianness as that of the processor. For example, if the processor is little-endian, the return value is the byte-swapped value read from the address. static INLINE void Xil_Out16BE ( UINTPTR Addr, u16 Value ) [static] Perform a big-endian output operation for a 16-bit memory location by writing the specified value to the specified address. Addr Value contains the address at which to perform the output operation. contains the value to be output at the specified address. The value has the same endianness as that of the processor. For example, if the processor is little-endian, the byteswapped value is written to the address. 172

173 static INLINE void Xil_Out32BE ( UINTPTR Addr, u32 Value ) [static] Perform a big-endian output operation for a 32-bit memory location by writing the specified value to the specified address. Addr Value contains the address at which to perform the output operation. contains the value to be output at the specified address. The value has the same endianness as that of the processor. For example, if the processor is little-endian, the byteswapped value is written to the address. Definitions for available xilinx platforms Overview The xplatform_info.h file contains definitions for various available Xilinx platforms. Functions u32 XGetPlatform_Info () u32 XGetPSVersion_Info () u32 XGet_Zynq_UltraMp_Platform_info () Function Documentation u32 XGetPlatform_Info ( ) This API is used to provide information about platform. The information about platform defined in xplatform_info.h 173

174 u32 XGetPSVersion_Info ( ) This API is used to provide information about PS Silicon version. The information about PS Silicon version. u32 XGet_Zynq_UltraMp_Platform_info ( ) This API is used to provide information about zynq ultrascale MP platform. The information about zynq ultrascale MP platform defined in xplatform_info.h Data types for Xilinx Software IP Cores Overview The xil_types.h file contains basic types for Xilinx software IP cores. These data types are applicable for all processors supported by Xilinx. Macros #define XIL_COMPONENT_IS_READY #define XIL_COMPONENT_IS_STARTED New types New simple types. typedef uint8_t u8 typedef uint16_t u16 typedef uint32_t u32 typedef char char8 typedef int8_t s8 174

175 typedef int16_t s16 typedef int32_t s32 typedef int64_t s64 typedef uint64_t u64 typedef int sint32 typedef intptr_t INTPTR typedef uintptr_t UINTPTR typedef ptrdiff_t PTRDIFF typedef long LONG typedef unsigned long ULONG typedef void( XInterruptHandler) (void InstancePtr) typedef void( XExceptionHandler) (void InstancePtr) #define XUINT64 #define XUINT64_MSW(x) #define XUINT64_LSW(x) #define ULONG64_HI_MASK #define ULONG64_LO_MASK #define UPPER_32_BITS(n) #define LOWER_32_BITS(n) Macro Definition Documentation #define XIL_COMPONENT_IS_READY component has been initialized #define XIL_COMPONENT_IS_STARTED component has been started #define XUINT64_MSW( x ) Return the most significant half of the 64 bit data type. x is the 64 bit word. The upper 32 bits of the 64 bit word. 175

176 #define XUINT64_LSW( x ) Return the least significant half of the 64 bit data type. x is the 64 bit word. The lower 32 bits of the 64 bit word. #define UPPER_32_BITS( n ) return bits of a number n : the number we're accessing bits of number A basic shift-right of a 64- or 32-bit quantity. Use this to suppress the "right shift count >= width of type" warning when that quantity is 32-bits. #define LOWER_32_BITS( n ) return bits 0-31 of a number n : the number we're accessing bits 0-31 of number Typedef Documentation 176

177 typedef uint8_t u8 guarded against xbasic_types.h. typedef char char8 xbasic_types.h does not typedef s or u64 typedef void( XInterruptHandler) (void InstancePtr) This data type defines an interrupt handler for a device. The argument points to the instance of the component typedef void( XExceptionHandler) (void InstancePtr) This data type defines an exception handler for a processor. The argument points to the instance of the component Customized APIs for memory operations Overview The xil_mem.h file contains prototypes for function related to memory operations. These APIs are applicable for all processors supported by Xilinx. Functions void Xil_MemCpy (void dst, const void src, u32 cnt) Function Documentation void Xil_MemCpy ( void dst, const void src, u32 cnt ) This function copies memory from once location to other. dst src cnt pointer pointing to destination memory pointer pointing to source memory 32 bit length of bytes to be copied 177

178 Xilinx software status codes Overview The xstatus.h file contains Xilinx software status codes. Status codes have their own data type called int. These codes are used throughout the Xilinx device drivers. Test utilities for memory and caches Overview The xil_testcache.h, xil_testio.h and the xil_testmem.h files contain utility functions to test cache and memory. Details of supported tests and subtests are listed below. Cache test : xil_testcache.h contains utility functions to test cache. I/O test : The Xil_testio.h file contains endian related memory IO functions. A subset of the memory tests can be selected or all of the tests can be run in order. If there is an error detected by a subtest, the test stops and the failure code is returned. Further tests are not run even if all of the tests are selected. Memory test : The xil_testmem.h file contains utility functions to test memory. A subset of the memory tests can be selected or all of the tests can be run in order. If there is an error detected by a subtest, the test stops and the failure code is returned. Further tests are not run even if all of the tests are selected. Following are descriptions of Memory test subtests: XIL_TESTMEM_ALLMEMTESTS: Runs all of the subtests. XIL_TESTMEM_INCREMENT: Incrementing Value Test. This test starts at XIL_TESTMEM_INIT_VALUE and uses the incrementing value as the test value for memory. XIL_TESTMEM_WALKONES: Walking Ones Test. This test uses a walking 1 as the test value for memory. location 1 = 0x location 2 = 0x XIL_TESTMEM_WALKZEROS: Walking Zero's Test. This test uses the inverse value of the walking ones test as the test value for memory. location 1 = 0xFFFFFFFE location 2 = 0xFFFFFFFD... XIL_TESTMEM_INVERSEADDR: Inverse Address Test. This test uses the inverse of the address of the location under test as the test value for memory. XIL_TESTMEM_FIXEDPATTERN: Fixed Pattern Test. This test uses the provided patters as the test value for memory. If zero is provided as the pattern the test uses 0xDEADBEEF. 178

179 WARNING: The tests are DESTRUCTIVE. Run before any initialized memory spaces have been set up. The address provided to the memory tests is not checked for validity except for the NULL case. It is possible to provide a code-space pointer for this test to start with and ultimately destroy executable code causing random failures. Used for spaces where the address range of the region is smaller than the data width. If the memory range is greater than 2 width, the patterns used in XIL_TESTMEM_WALKONES and XIL_TESTMEM_WALKZEROS will repeat on a boundary of a power of two making it more difficult to detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller regions of memory to allow the test patterns used not to repeat over the region tested. Functions s32 Xil_TestIO8 (u8 Addr, s32 Length, u8 Value) s32 Xil_TestIO16 (u16 Addr, s32 Length, u16 Value, s32 Kind, s32 Swap) s32 Xil_TestIO32 (u32 Addr, s32 Length, u32 Value, s32 Kind, s32 Swap) s32 Xil_TestMem32 (u32 Addr, u32 Words, u32 Pattern, u8 Subtest) s32 Xil_TestMem16 (u16 Addr, u32 Words, u16 Pattern, u8 Subtest) s32 Xil_TestMem8 (u8 Addr, u32 Words, u8 Pattern, u8 Subtest) Memory subtests #define XIL_TESTMEM_ALLMEMTESTS #define XIL_TESTMEM_INCREMENT #define XIL_TESTMEM_WALKONES #define XIL_TESTMEM_WALKZEROS #define XIL_TESTMEM_INVERSEADDR #define XIL_TESTMEM_FIXEDPATTERN #define XIL_TESTMEM_MAXTEST Macro Definition Documentation 179

180 #define XIL_TESTMEM_ALLMEMTESTS See the detailed description of the subtests in the file description. Function Documentation s32 Xil_TestIO8 ( u8 Addr, s32 Length, u8 Value ) Perform a destructive 8-bit wide register IO test where the register is accessed using Xil_Out8 and Xil_In8, and comparing the written values by reading them back. Addr Length Value a pointer to the region of memory to be tested. Length of the block. constant used for writting the memory. -1 is returned for a failure 0 is returned for a pass s32 Xil_TestIO16 ( u16 Addr, s32 Length, u16 Value, s32 Kind, s32 Swap ) Perform a destructive 16-bit wide register IO test. Each location is tested by sequentially writing a 16-bit wide register, reading the register, and comparing value. This function tests three kinds of register IO functions, normal register IO, little-endian register IO, and big-endian register IO. When testing little/big-endian IO, the function performs the following sequence, Xil_Out16LE/Xil_Out16BE, Xil_In16, Compare In-Out values, Xil_Out16, Xil_In16LE/Xil_In16BE, Compare In-Out values. Whether to swap the read-in value before comparing is controlled by the 5th argument. Addr Length Value Kind Swap a pointer to the region of memory to be tested. Length of the block. constant used for writting the memory. Type of test. Acceptable values are: XIL_TESTIO_DEFAULT, XIL_TESTIO_LE, XIL_TESTIO_BE. indicates whether to byte swap the read-in value. -1 is returned for a failure 0 is returned for a pass 180

181 s32 Xil_TestIO32 ( u32 Addr, s32 Length, u32 Value, s32 Kind, s32 Swap ) Perform a destructive 32-bit wide register IO test. Each location is tested by sequentially writing a 32-bit wide regsiter, reading the register, and comparing value. This function tests three kinds of register IO functions, normal register IO, little-endian register IO, and big-endian register IO. When testing little/big-endian IO, the function perform the following sequence, Xil_Out32LE/ Xil_Out32BE, Xil_In32, Compare, Xil_Out32, Xil_In32LE/Xil_In32BE, Compare. Whether to swap the read-in value before comparing is controlled by the 5th argument. Addr Length Value Kind Swap a pointer to the region of memory to be tested. Length of the block. constant used for writting the memory. type of test. Acceptable values are: XIL_TESTIO_DEFAULT, XIL_TESTIO_LE, XIL_TESTIO_BE. indicates whether to byte swap the read-in value. -1 is returned for a failure 0 is returned for a pass s32 Xil_TestMem32 ( u32 Addr, u32 Words, u32 Pattern, u8 Subtest ) Perform a destructive 32-bit wide memory test. Addr Words Pattern Subtest pointer to the region of memory to be tested. length of the block. constant used for the constant pattern test, if 0, 0xDEADBEEF is used. test type selected. See xil_testmem.h for possible values. 0 is returned for a pass 1 is returned for a failure 181

182 Used for spaces where the address range of the region is smaller than the data width. If the memory range is greater than 2 Width, the patterns used in XIL_TESTMEM_WALKONES and XIL_TESTMEM_WALKZEROS will repeat on a boundry of a power of two making it more difficult to detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller regions of memory to allow the test patterns used not to repeat over the region tested. s32 Xil_TestMem16 ( u16 Addr, u32 Words, u16 Pattern, u8 Subtest ) Perform a destructive 16-bit wide memory test. Addr Words Pattern Subtest pointer to the region of memory to be tested. length of the block. constant used for the constant Pattern test, if 0, 0xDEADBEEF is used. type of test selected. See xil_testmem.h for possible values is returned for a failure - 0 is returned for a pass Used for spaces where the address range of the region is smaller than the data width. If the memory range is greater than 2 Width, the patterns used in XIL_TESTMEM_WALKONES and XIL_TESTMEM_WALKZEROS will repeat on a boundry of a power of two making it more difficult to detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller regions of memory to allow the test patterns used not to repeat over the region tested. s32 Xil_TestMem8 ( u8 Addr, u32 Words, u8 Pattern, u8 Subtest ) Perform a destructive 8-bit wide memory test. Addr Words Pattern Subtest pointer to the region of memory to be tested. length of the block. constant used for the constant pattern test, if 0, 0xDEADBEEF is used. type of test selected. See xil_testmem.h for possible values. 182

183 -1 is returned for a failure 0 is returned for a pass Used for spaces where the address range of the region is smaller than the data width. If the memory range is greater than 2 Width, the patterns used in XIL_TESTMEM_WALKONES and XIL_TESTMEM_WALKZEROS will repeat on a boundry of a power of two making it more difficult to detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller regions of memory to allow the test patterns used not to repeat over the region tested. 183

184 MicroBlaze Processor API Overview This section provides a linked summary and detailed descriptions of the MicroBlaze Processor APIs. Modules MicroBlaze Pseudo-asm Macros and Interrupt handling APIs MicroBlaze exception APIs MicroBlaze Processor Cache APIs MicroBlaze Processor FSL Macros MicroBlaze PVR access routines and macros Sleep Routines for MicroBlaze MicroBlaze Pseudo-asm Macros and Interrupt handling APIs Overview Standalone includes macros to provide convenient access to various registers in the MicroBlaze processor. Some of these macros are very useful within exception handlers for retrieving information about the exception.also, the interrupt handling functions help manage interrupt handling on MicroBlaze processor devices.to use these functions, include the header file mb_interface.h in your source code Functions void microblaze_register_handler (XInterruptHandler Handler, void DataPtr) void microblaze_register_exception_handler (u32 ExceptionId, Xil_ExceptionHandler Handler, void DataPtr) 184

185 MicroBlaze pseudo-asm macros The following is a summary of the MicroBlaze processor pseudo-asm macros. #define mfgpr(rn) #define mfmsr() #define mfear() #define mfeare() #define mfesr() #define mffsr() Macro Definition Documentation #define mfgpr( rn ) Return value from the general purpose register (GPR) rn. rn General purpose register to be read. #define mfmsr( ) Return the current value of the MSR. None #define mfear( ) Return the current value of the Exception Address Register (EAR). None #define mfesr( ) Return the current value of the Exception Status Register (ESR). None 185

186 #define mffsr( ) Return the current value of the Floating Point Status (FPS). None Function Documentation void microblaze_register_handler ( XInterruptHandler Handler, void DataPtr ) Registers a top-level interrupt handler for the MicroBlaze. The argument provided in this call as the DataPtr is used as the argument for the handler when it is called. Handler DataPtr Top level handler. a reference to data that will be passed to the handler when it gets called. void microblaze_register_exception_handler ( u32 ExceptionId, Xil_ExceptionHandler Handler, void DataPtr ) Registers an exception handler for the MicroBlaze. The argument provided in this call as the DataPtr is used as the argument for the handler when it is called. ExceptionId Top DataPtr is the id of the exception to register this handler for. level handler. is a reference to data that will be passed to the handler when it gets called. 186

187 MicroBlaze exception APIs Overview The xil_exception.h file, available in the <install-directory>/src/microblaze folder, contains MicroBlaze specific exception related APIs and macros. Application programs can use these APIs for various exception related operations. For example, enable exception, disable exception, register exception hander. To use exception related functions, xil_exception.h must be added in source code Data Structures struct MB_ExceptionVectorTableEntry Typedefs typedef void( Xil_ExceptionHandler) (void Data) typedef void( XInterruptHandler) (void InstancePtr) Functions void Xil_ExceptionInit (void) void Xil_ExceptionEnable (void) void Xil_ExceptionDisable (void) void Xil_ExceptionRegisterHandler (u32 Id, Xil_ExceptionHandler Handler, void Data) void Xil_ExceptionRemoveHandler (u32 Id) Data Structure Documentation struct MB_ExceptionVectorTableEntry Currently HAL is an augmented part of standalone BSP, so the old definition of MB_ExceptionVectorTableEntry is used here. Typedef Documentation 187

188 typedef void( Xil_ExceptionHandler) (void Data) This typedef is the exception handler function. typedef void( XInterruptHandler) (void InstancePtr) This data type defines an interrupt handler for a device. The argument points to the instance of the component Function Documentation void Xil_ExceptionInit ( void ) Initialize exception handling for the processor. The exception vector table is setup with the stub handler for all exceptions. void Xil_ExceptionEnable ( void ) Enable Exceptions. void Xil_ExceptionDisable ( void ) Disable Exceptions. 188

189 void Xil_ExceptionRegisterHandler ( u32 Id, Xil_ExceptionHandler Handler, void Data ) Makes the connection between the Id of the exception source and the associated handler that is to run when the exception is recognized. The argument provided in this call as the DataPtr is used as the argument for the handler when it is called. Id contains the 32 bit ID of the exception source and should be XIL_EXCEPTION_INT or be in the range of 0 to XIL_EXCEPTION_LAST. See xil_mach_exception.h for further information. Handler Data handler function to be registered for exception a reference to data that will be passed to the handler when it gets called. void Xil_ExceptionRemoveHandler ( u32 Id ) Removes the handler for a specific exception Id. The stub handler is then registered for this exception Id. Id contains the 32 bit ID of the exception source and should be XIL_EXCEPTION_INT or in the range of 0 to XIL_EXCEPTION_LAST. See xexception_l.h for further information. MicroBlaze Processor Cache APIs Overview Cache functions provide access to cache related operations such as flush and invalidate for instruction and data caches. It gives option to perform the cache operations on a single cacheline, a range of memory and an entire cache. Macros void Xil_L1DCacheInvalidate() void Xil_L2CacheInvalidate() void Xil_L1DCacheInvalidateRange(Addr, Len) void Xil_L2CacheInvalidateRange(Addr, Len) void Xil_L1DCacheFlushRange(Addr, Len) 189

190 void Xil_L2CacheFlushRange(Addr, Len) void Xil_L1DCacheFlush() void Xil_L2CacheFlush() void Xil_L1ICacheInvalidateRange(Addr, Len) void Xil_L1ICacheInvalidate() void Xil_L1DCacheEnable() void Xil_L1DCacheDisable() void Xil_L1ICacheEnable() void Xil_L1ICacheDisable() void Xil_DCacheEnable() void Xil_ICacheEnable() Functions void Xil_DCacheDisable (void) void Xil_ICacheDisable (void) Macro Definition Documentation void Xil_L1DCacheInvalidate( ) Invalidate the entire L1 data cache. If the cacheline is modified (dirty), the modified contents are lost. Processor must be in real mode. 190

191 void Xil_L2CacheInvalidate( ) Invalidate the entire L2 data cache. If the cacheline is modified (dirty),the modified contents are lost. Processor must be in real mode. void Xil_L1DCacheInvalidateRange( Addr, Len ) Invalidate the L1 data cache for the given address range. If the bytes specified by the address (Addr) are cached by the L1 data cache, the cacheline containing that byte is invalidated.if the cacheline is modified (dirty), the modified contents are lost. Addr Len is address of ragne to be invalidated. is the length in bytes to be invalidated. Processor must be in real mode. 191

192 void Xil_L2CacheInvalidateRange( Addr, Len ) Invalidate the L1 data cache for the given address range. If the bytes specified by the address (Addr) are cached by the L1 data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost. Addr Len address of ragne to be invalidated. length in bytes to be invalidated. Processor must be in real mode. void Xil_L1DCacheFlushRange( Addr, Len ) Flush the L1 data cache for the given address range. If the bytes specified by the address (Addr) are cached by the data cache, and is modified (dirty), the cacheline will be written to system memory.the cacheline will also be invalidated. Addr Len the starting address of the range to be flushed. length in byte to be flushed. void Xil_L2CacheFlushRange( Addr, Len ) Flush the L2 data cache for the given address range. If the bytes specified by the address (Addr) are cached by the data cache, and is modified (dirty), the cacheline will be written to system memory. The cacheline will also be invalidated. Addr Len the starting address of the range to be flushed. length in byte to be flushed. 192

193 void Xil_L1DCacheFlush( ) Flush the entire L1 data cache. If any cacheline is dirty, the cacheline will be written to system memory. The entire data cache will be invalidated. void Xil_L2CacheFlush( ) Flush the entire L2 data cache. If any cacheline is dirty, the cacheline will be written to system memory. The entire data cache will be invalidated. void Xil_L1ICacheInvalidateRange( Addr, Len ) Invalidate the instruction cache for the given address range. Addr Len is address of ragne to be invalidated. is the length in bytes to be invalidated. void Xil_L1ICacheInvalidate( ) Invalidate the entire instruction cache. None 193

194 void Xil_L1DCacheEnable( ) Enable the L1 data cache. void Xil_L1DCacheDisable( ) Disable the L1 data cache. This is processor specific. void Xil_L1ICacheEnable( ) Enable the instruction cache. This is processor specific. void Xil_L1ICacheDisable( ) Disable the L1 Instruction cache. This is processor specific. 194

195 void Xil_DCacheEnable( ) Enable the data cache. None void Xil_ICacheEnable( ) Enable the instruction cache. None Function Documentation void Xil_DCacheDisable ( void ) Disable the data cache. None 195

196 void Xil_ICacheDisable ( void ) Disable the instruction cache. None MicroBlaze Processor FSL Macros Overview Standalone includes macros to provide convenient access to accelerators connected to the MicroBlaze Fast Simplex Link (FSL) Interfaces.To use these functions, include the header file fsl.h in your source code Macros #define getfslx(val, id, flags) #define putfslx(val, id, flags) #define tgetfslx(val, id, flags) #define tputfslx(id, flags) #define getdfslx(val, var, flags) #define putdfslx(val, var, flags) #define tgetdfslx(val, var, flags) #define tputdfslx(var, flags) Macro Definition Documentation #define getfslx( val, id, flags ) Performs a get function on an input FSL of the MicroBlaze processor val id flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags 196

197 #define putfslx( val, id, flags ) Performs a put function on an input FSL of the MicroBlaze processor val id flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags #define tgetfslx( val, id, flags ) Performs a test get function on an input FSL of the MicroBlaze processor val id flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags #define tputfslx( id, flags ) Performs a put function on an input FSL of the MicroBlaze processor id flags FSL identifier valid FSL macro flags #define getdfslx( val, var, flags ) Performs a get function on an input FSL of the MicroBlaze processor val var flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags 197

198 #define putdfslx( val, var, flags ) Performs a put function on an input FSL of the MicroBlaze processor val var flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags #define tgetdfslx( val, var, flags ) Performs a test get function on an input FSL of the MicroBlaze processor; val var flags literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later) FSL identifier valid FSL macro flags #define tputdfslx( var, flags ) Performs a put function on an input FSL of the MicroBlaze processor var flags FSL identifier valid FSL macro flags MicroBlaze PVR access routines and macros Overview MicroBlaze processor v5.00.a and later versions have configurable Processor Version Registers (PVRs). The contents of the PVR are captured using the pvr_t data structure, which is defined as an array of 32-bit words, with each word corresponding to a PVR register on hardware. The number of PVR words is determined by the number of PVRs configured in the hardware. You should not attempt to access PVR registers that are not present in hardware, as the pvr_t data structure is resized to hold only as many PVRs as are present in hardware. To access information in the PVR: 1. Use the microblaze_get_pvr() function to populate the PVR data into a pvr_t data structure. 2. In subsequent steps, you can use any one of the PVR access macros list to get individual data stored in the PVR. 3. pvr.h header file must be included to source to use PVR macros. 198

199 Macros #define MICROBLAZE_PVR_IS_FULL(_pvr) #define MICROBLAZE_PVR_USE_BARREL(_pvr) #define MICROBLAZE_PVR_USE_DIV(_pvr) #define MICROBLAZE_PVR_USE_HW_MUL(_pvr) #define MICROBLAZE_PVR_USE_FPU(_pvr) #define MICROBLAZE_PVR_USE_ICACHE(_pvr) #define MICROBLAZE_PVR_USE_DCACHE(_pvr) #define MICROBLAZE_PVR_MICROBLAZE_VERSION(_pvr) #define MICROBLAZE_PVR_USER1(_pvr) #define MICROBLAZE_PVR_USER2(_pvr) #define MICROBLAZE_PVR_D_LMB(_pvr) #define MICROBLAZE_PVR_D_PLB(_pvr) #define MICROBLAZE_PVR_I_LMB(_pvr) #define MICROBLAZE_PVR_I_PLB(_pvr) #define MICROBLAZE_PVR_INTERRUPT_IS_EDGE(_pvr) #define MICROBLAZE_PVR_EDGE_IS_POSITIVE(_pvr) #define MICROBLAZE_PVR_INTERCONNECT(_pvr) #define MICROBLAZE_PVR_USE_MUL64(_pvr) #define MICROBLAZE_PVR_OPCODE_0x0_ILLEGAL(_pvr) #define MICROBLAZE_PVR_UNALIGNED_EXCEPTION(_pvr) #define MICROBLAZE_PVR_ILL_OPCODE_EXCEPTION(_pvr) #define MICROBLAZE_PVR_IPLB_BUS_EXCEPTION(_pvr) #define MICROBLAZE_PVR_DPLB_BUS_EXCEPTION(_pvr) #define MICROBLAZE_PVR_DIV_ZERO_EXCEPTION(_pvr) #define MICROBLAZE_PVR_FPU_EXCEPTION(_pvr) #define MICROBLAZE_PVR_FSL_EXCEPTION(_pvr) #define MICROBLAZE_PVR_DEBUG_ENABLED(_pvr) #define MICROBLAZE_PVR_NUMBER_OF_PC_BRK(_pvr) #define MICROBLAZE_PVR_NUMBER_OF_RD_ADDR_BRK(_pvr) #define MICROBLAZE_PVR_NUMBER_OF_WR_ADDR_BRK(_pvr) #define MICROBLAZE_PVR_FSL_LINKS(_pvr) #define MICROBLAZE_PVR_ICACHE_ADDR_TAG_BITS(_pvr) #define MICROBLAZE_PVR_ICACHE_ALLOW_WR(_pvr) #define MICROBLAZE_PVR_ICACHE_LINE_LEN(_pvr) #define MICROBLAZE_PVR_ICACHE_BYTE_SIZE(_pvr) #define MICROBLAZE_PVR_DCACHE_ADDR_TAG_BITS(_pvr) #define MICROBLAZE_PVR_DCACHE_ALLOW_WR(_pvr) #define MICROBLAZE_PVR_DCACHE_LINE_LEN(_pvr) #define MICROBLAZE_PVR_DCACHE_BYTE_SIZE(_pvr) #define MICROBLAZE_PVR_ICACHE_BASEADDR(_pvr) #define MICROBLAZE_PVR_ICACHE_HIGHADDR(_pvr) #define MICROBLAZE_PVR_DCACHE_BASEADDR(_pvr) 199

200 #define MICROBLAZE_PVR_DCACHE_HIGHADDR(_pvr) #define MICROBLAZE_PVR_TARGET_FAMILY(_pvr) #define MICROBLAZE_PVR_MSR_RESET_VALUE(_pvr) #define MICROBLAZE_PVR_MMU_TYPE(_pvr) Functions int microblaze_get_pvr (pvr_t pvr) Macro Definition Documentation #define MICROBLAZE_PVR_IS_FULL( _pvr ) Return non-zero integer if PVR is of type FULL, 0 if basic _pvr pvr data structure #define MICROBLAZE_PVR_USE_BARREL( _pvr ) Return non-zero integer if hardware barrel shifter present. _pvr pvr data structure #define MICROBLAZE_PVR_USE_DIV( _pvr ) Return non-zero integer if hardware divider present. _pvr pvr data structure #define MICROBLAZE_PVR_USE_HW_MUL( _pvr ) Return non-zero integer if hardware multiplier present. _pvr pvr data structure 200

201 #define MICROBLAZE_PVR_USE_FPU( _pvr ) Return non-zero integer if hardware floating point unit (FPU) present. _pvr pvr data structure #define MICROBLAZE_PVR_USE_ICACHE( _pvr ) Return non-zero integer if I-cache present. _pvr pvr data structure #define MICROBLAZE_PVR_USE_DCACHE( _pvr ) Return non-zero integer if D-cache present. _pvr pvr data structure #define MICROBLAZE_PVR_MICROBLAZE_VERSION( _pvr ) Return MicroBlaze processor version encoding. Refer to the MicroBlaze Processor Reference Guide (UG081) for mappings from encodings to actual hardware versions. _pvr pvr data structure #define MICROBLAZE_PVR_USER1( _pvr ) Return the USER1 field stored in the PVR. _pvr pvr data structure 201

202 #define MICROBLAZE_PVR_USER2( _pvr ) Return the USER2 field stored in the PVR. _pvr pvr data structure #define MICROBLAZE_PVR_D_LMB( _pvr ) Return non-zero integer if Data Side PLB interface is present. _pvr pvr data structure #define MICROBLAZE_PVR_D_PLB( _pvr ) Return non-zero integer if Data Side PLB interface is present. _pvr pvr data structure #define MICROBLAZE_PVR_I_LMB( _pvr ) Return non-zero integer if Instruction Side Local Memory Bus (LMB) interface present. _pvr pvr data structure #define MICROBLAZE_PVR_I_PLB( _pvr ) Return non-zero integer if Instruction Side PLB interface present. _pvr pvr data structure 202

203 #define MICROBLAZE_PVR_INTERRUPT_IS_EDGE( _pvr ) Return non-zero integer if interrupts are configured as edge-triggered. _pvr pvr data structure #define MICROBLAZE_PVR_EDGE_IS_POSITIVE( _pvr ) Return non-zero integer if interrupts are configured as positive edge triggered. _pvr pvr data structure #define MICROBLAZE_PVR_INTERCONNECT( _pvr ) Return non-zero if MicroBlaze processor has PLB interconnect; otherwise return zero. _pvr pvr data structure #define MICROBLAZE_PVR_USE_MUL64( _pvr ) Return non-zero integer if MicroBlaze processor supports 64-bit products for multiplies. _pvr pvr data structure #define MICROBLAZE_PVR_OPCODE_0x0_ILLEGAL( _pvr ) Return non-zero integer if opcode 0x0 is treated as an illegal opcode. multiplies. _pvr pvr data structure 203

204 #define MICROBLAZE_PVR_UNALIGNED_EXCEPTION( _pvr ) Return non-zero integer if unaligned exceptions are supported. _pvr pvr data structure #define MICROBLAZE_PVR_ILL_OPCODE_EXCEPTION( _pvr ) Return non-zero integer if illegal opcode exceptions are supported. _pvr pvr data structure #define MICROBLAZE_PVR_IPLB_BUS_EXCEPTION( _pvr ) Return non-zero integer if I-PLB exceptions are supported. _pvr pvr data structure #define MICROBLAZE_PVR_DPLB_BUS_EXCEPTION( _pvr ) Return non-zero integer if I-PLB exceptions are supported. _pvr pvr data structure #define MICROBLAZE_PVR_DIV_ZERO_EXCEPTION( _pvr ) Return non-zero integer if divide by zero exceptions are supported. _pvr pvr data structure 204

205 #define MICROBLAZE_PVR_FPU_EXCEPTION( _pvr ) Return non-zero integer if FPU exceptions are supported. _pvr pvr data structure #define MICROBLAZE_PVR_FSL_EXCEPTION( _pvr ) Return non-zero integer if FSL exceptions are present. _pvr pvr data structure #define MICROBLAZE_PVR_DEBUG_ENABLED( _pvr ) Return non-zero integer if debug is enabled. _pvr pvr data structure #define MICROBLAZE_PVR_NUMBER_OF_PC_BRK( _pvr ) Return the number of hardware PC breakpoints available. _pvr pvr data structure #define MICROBLAZE_PVR_NUMBER_OF_RD_ADDR_BRK( _pvr ) Return the number of read address hardware watchpoints supported. _pvr pvr data structure 205

206 #define MICROBLAZE_PVR_NUMBER_OF_WR_ADDR_BRK( _pvr ) Return the number of write address hardware watchpoints supported. _pvr pvr data structure #define MICROBLAZE_PVR_FSL_LINKS( _pvr ) Return the number of FSL links present. _pvr pvr data structure #define MICROBLAZE_PVR_ICACHE_ADDR_TAG_BITS( _pvr ) Return the number of address tag bits for the I-cache. _pvr pvr data structure #define MICROBLAZE_PVR_ICACHE_ALLOW_WR( _pvr ) Return non-zero if writes to I-caches are allowed. _pvr pvr data structure #define MICROBLAZE_PVR_ICACHE_LINE_LEN( _pvr ) Return the length of each I-cache line in bytes. _pvr pvr data structure 206

207 #define MICROBLAZE_PVR_ICACHE_BYTE_SIZE( _pvr ) Return the size of the D-cache in bytes. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_ADDR_TAG_BITS( _pvr ) Return the number of address tag bits for the D-cache. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_ALLOW_WR( _pvr ) Return non-zero if writes to D-cache are allowed. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_LINE_LEN( _pvr ) Return the length of each line in the D-cache in bytes. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_BYTE_SIZE( _pvr ) Return the size of the D-cache in bytes. _pvr pvr data structure 207

208 #define MICROBLAZE_PVR_ICACHE_BASEADDR( _pvr ) Return the base address of the I-cache. _pvr pvr data structure #define MICROBLAZE_PVR_ICACHE_HIGHADDR( _pvr ) Return the high address of the I-cache. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_BASEADDR( _pvr ) Return the base address of the D-cache. _pvr pvr data structure #define MICROBLAZE_PVR_DCACHE_HIGHADDR( _pvr ) Return the high address of the D-cache. _pvr pvr data structure #define MICROBLAZE_PVR_TARGET_FAMILY( _pvr ) Return the encoded target family identifier. _pvr pvr data structure 208

209 #define MICROBLAZE_PVR_MSR_RESET_VALUE( _pvr ) Refer to the MicroBlaze Processor Reference Guide (UG081) for mappings from encodings to target family name strings. _pvr pvr data structure #define MICROBLAZE_PVR_MMU_TYPE( _pvr ) the value of C_USE_MMU. Refer to the MicroBlaze Processor Reference Guide (UG081) for mappings from MMU type values to MMU function. _pvr pvr data structure Function Documentation int microblaze_get_pvr ( pvr_t pvr ) Populate the PVR data structure to which pvr points with the values of the hardware PVR registers. pvr- address of PVR data structure to be populated 0 - SUCCESS -1 - FAILURE Sleep Routines for MicroBlaze Overview microblaze_sleep.h contains microblaze sleep APIs. These APIs provides delay for requested duration. microblaze_sleep.h may contain architecture-dependent items. Functions void MB_Sleep (u32 MilliSeconds) attribute (( deprecated )) 209

210 Function Documentation void MB_Sleep ( u32 MilliSeconds ) Provides delay for requested duration.. MilliSeconds- Delay time in milliseconds. Instruction cache should be enabled for this to work. 210

211 Cortex R5 Processor API Overview Standalone BSP contains boot code, cache, exception handling, file and memory management, configuration, time and processor-specific include functions. It supports gcc compiler. This section provides a linked summary and detailed descriptions of the Cortex R5 processor APIs. Modules Cortex R5 Processor Boot Code Cortex R5 Processor MPU specific APIs Cortex R5 Processor Cache Functions Cortex R5 Time Functions Cortex R5 Event Counters Functions Cortex R5 Processor Specific Include Files Cortex R5 Processor Boot Code Overview The boot.s file contains a minimal set of code for transferring control from the processor's reset location to the start of the application. The boot code performs minimum configuration which is required for an application to run starting from processor's reset state. Below is a sequence illustrating what all configuration is performed before control reaches to main function. 1. Program vector table base for exception handling 2. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system) 3. Disable instruction cache, data cache and MPU 4. Invalidate instruction and data cache 5. Configure MPU with short descriptor translation table format and program base address of translation table 211

212 6. Enable data cache, instruction cache and MPU 7. Enable Floating point unit 8. Transfer control to _start which clears BSS sections and jumping to main application Cortex R5 Processor MPU specific APIs Overview MPU functions provides access to MPU operations such as enable MPU, disable MPU and set attribute for section of memory. Boot code invokes Init_MPU function to configure the MPU. A total of 10 MPU regions are allocated with another 6 being free for users. Overview of the memory attributes for different MPU regions is as given below, Memory Range DDR 0x x7FFFFFFF PL 0x xBFFFFFFF QSPI 0xC xDFFFFFFF PCIe 0xE xEFFFFFFF STM_CORESIGHT 0xF xF8FFFFFF Attributes of MPURegion Normal write-back Cacheable Strongly Ordered Device Memory Device Memory Device Memory For a system where DDR is less than 2GB, region after DDR and before PL is marked as undefined in translation table 212

213 Memory Range RPU_R5_GIC 0xF xF90FFFFF FPS 0xFD xFDFFFFFF Attributes of MPURegion Device Memory Device Memory LPS 0xFE xFFFFFFFF OCM 0xFFFC0000-0xFFFFFFFF Device Memory 0xFE xFEFFFFFF upper LPS slaves, 0xFF xFFFFFFFF lower LPS slaves Normal write-back Cacheable Functions void Xil_SetTlbAttributes (INTPTR Addr, u32 attrib) void Xil_EnableMPU (void) void Xil_DisableMPU (void) void Xil_SetMPURegion (INTPTR addr, u64 size, u32 attrib) Function Documentation void Xil_SetTlbAttributes ( INTPTR addr, u32 attrib ) This function sets the memory attributes for a section covering 1MB, of memory in the translation table. Addr attrib 32-bit address for which memory attributes need to be set. Attribute for the given memory region. 213

214 void Xil_EnableMPU ( void ) Enable MPU for Cortex R5 processor. This function invalidates I cache and flush the D Caches, and then enables the MPU. void Xil_DisableMPU ( void ) Disable MPU for Cortex R5 processors. This function invalidates I cache and flush the D Caches, and then disabes the MPU. void Xil_SetMPURegion ( INTPTR addr, u64 size, u32 attrib ) Set the memory attributes for a section of memory in the translation table. Addr size attrib 32-bit address for which memory attributes need to be set.. size is the size of the region. Attribute for the given memory region. Cortex R5 Processor Cache Functions Overview Cache functions provide access to cache related operations such as flush and invalidate for instruction and data caches. It gives option to perform the cache operations on a single cacheline, a range of memory and an entire cache. 214

215 Functions void Xil_DCacheEnable (void) void Xil_DCacheDisable (void) void Xil_DCacheInvalidate (void) void Xil_DCacheInvalidateRange (INTPTR adr, u32 len) void Xil_DCacheFlush (void) void Xil_DCacheFlushRange (INTPTR adr, u32 len) void Xil_DCacheInvalidateLine (INTPTR adr) void Xil_DCacheFlushLine (INTPTR adr) void Xil_DCacheStoreLine (INTPTR adr) void Xil_ICacheEnable (void) void Xil_ICacheDisable (void) void Xil_ICacheInvalidate (void) void Xil_ICacheInvalidateRange (INTPTR adr, u32 len) void Xil_ICacheInvalidateLine (INTPTR adr) Function Documentation void Xil_DCacheEnable ( void ) Enable the Data cache. void Xil_DCacheDisable ( void ) Disable the Data cache. 215

216 void Xil_DCacheInvalidate ( void ) Invalidate the entire Data cache. void Xil_DCacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the Data cache for the given address range. If the bytes specified by the address (adr) are cached by the Data cache,the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are NOT written to system memory before the line is invalidated. adr len 32bit start address of the range to be invalidated. Length of range to be invalidated in bytes. void Xil_DCacheFlush ( void ) Flush the entire Data cache. 216

217 void Xil_DCacheFlushRange ( INTPTR adr, u32 len ) Flush the Data cache for the given address range. If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing those bytes is invalidated.if the cacheline is modified (dirty), the written to system memory before the lines are invalidated. adr len 32bit start address of the range to be flushed. Length of the range to be flushed in bytes void Xil_DCacheInvalidateLine ( INTPTR adr ) Invalidate a Data cache line. If the byte specified by the address (adr) is cached by the data cache, the cacheline containing that byte is invalidated.if the cacheline is modified (dirty), the modified contents are lost and are NOT written to system memory before the line is invalidated. adr 32bit address of the data to be flushed. The bottom 4 bits are set to 0, forced by architecture. void Xil_DCacheFlushLine ( INTPTR adr ) Flush a Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 32bit address of the data to be flushed. 217

218 The bottom 4 bits are set to 0, forced by architecture. void Xil_DCacheStoreLine ( INTPTR adr ) Store a Data cache line. If the byte specified by the address (adr) is cached by the Data cache and the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory.after the store completes, the cacheline is marked as unmodified (not dirty). adr 32bit address of the data to be stored The bottom 4 bits are set to 0, forced by architecture. void Xil_ICacheEnable ( void ) Enable the instruction cache. void Xil_ICacheDisable ( void ) Disable the instruction cache. 218

219 void Xil_ICacheInvalidate ( void ) Invalidate the entire instruction cache. void Xil_ICacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the instruction cache for the given address range. If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing that byte is invalidated. If the cachelineis modified (dirty), the modified contents are lost and are NOT written to system memory before the line is invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_ICacheInvalidateLine ( INTPTR adr ) Invalidate an instruction cache line.if the instruction specified by the address is cached by the instruction cache, the cacheline containing that instruction is invalidated. adr 32bit address of the instruction to be invalidated. The bottom 4 bits are set to 0, forced by architecture. 219

220 Cortex R5 Time Functions Overview The xtime_l.c file and corresponding xtime_l.h include file provide access to the 32-bit counter in TTC. The sleep.c, usleep.c file and the corresponding sleep.h include file implement sleep functions. Sleep functions are implemented as busy loops. Functions void XTime_StartTimer (void) void XTime_SetTime (XTime Xtime_Global) void XTime_GetTime (XTime Xtime_Global) Function Documentation void XTime_StartTimer ( void ) Starts the TTC timer 3 counter 0 if present and if it is not already running with desired parameters for sleep functionalities. When this function is called by any one processor in a multi- processor environment, reference time will reset/lost for all processors. void XTime_SetTime ( XTime Xtime_Global ) TTC Timer runs continuously and the time can not be set as desired. This API doesn't contain anything. It is defined to have uniformity across platforms. Xtime_Global 32 bit value to be written to the timer counter register. 220

221 In multiprocessor environment reference time will reset/lost for all processors, when this function called by any one processor. void XTime_GetTime ( XTime Xtime_Global ) Get the time from the timer counter register. Xtime_Global Pointer to the 32 bit location to be updated with the time current value of timer counter register. Cortex R5 Event Counters Functions Overview Cortex R5 event counter functions can be utilized to configure and control the Cortex-R5 performance monitor events. Cortex-R5 Performance Monitor has 6 event counters which can be used to count a variety of events described in Coretx-R5 TRM. xpm_counter.h defines configurations XPM_CNTRCFGx which can be used to program the event counters to count a set of events. It doesn't handle the Cortex-R5 cycle counter, as the cycle counter is being used for time keeping. Functions void Xpm_SetEvents (s32 PmcrCfg) void Xpm_GetEventCounters (u32 PmCtrValue) Function Documentation 221

222 void Xpm_SetEvents ( s32 PmcrCfg ) This function configures the Cortex R5 event counters controller, with the event codes, in a configuration selected by the user and enables the counters. PmcrCfg Configuration value based on which the event counters are configured.xpm_cntrcfg values defined in xpm_counter.h can be utilized for setting configuration void Xpm_GetEventCounters ( u32 PmCtrValue ) This function disables the event counters and returns the counter values. PmCtrValue Pointer to an array of type u32 PmCtrValue[6]. It is an output parameter which is used to return the PM counter values. Cortex R5 Processor Specific Include Files Overview The xpseudo_asm.h file includes xreg_cortexr5.h and xpseudo_asm_gcc.h. The xreg_cortexr5.h include file contains the register numbers and the register bits for the ARM Cortex-R5 processor. The xpseudo_asm_gcc.h file contains the definitions for the most often used inline assembler instructions, available as macros. These can be very useful for tasks such as setting or getting special purpose registers, synchronization,or cache manipulation. These inline assembler instructions can be used from drivers and user applications written in C. 222

223 ARM Processor Common API Overview This section provides a linked summary and detailed descriptions of the ARM Processor Common APIs. Modules ARM Processor Exception Handling ARM Processor Exception Handling Overview ARM processors specific exception related APIs for cortex A53,A9 and R5 can utilized for enabling/disabling IRQ, registering/removing handler for exceptions or initializing exception vector table with null handler. Macros #define Xil_ExceptionEnableMask(Mask) #define Xil_ExceptionEnable() #define Xil_ExceptionDisableMask(Mask) #define Xil_ExceptionDisable() #define Xil_EnableNestedInterrupts() #define Xil_DisableNestedInterrupts() Typedefs typedef void( Xil_ExceptionHandler) (void data) Functions void Xil_ExceptionRegisterHandler (u32 Exception_id, Xil_ExceptionHandler Handler, void Data) 223

224 void Xil_ExceptionRemoveHandler (u32 Exception_id) void Xil_ExceptionInit (void) void Xil_DataAbortHandler (void CallBackRef) void Xil_PrefetchAbortHandler (void CallBackRef) void Xil_UndefinedExceptionHandler (void CallBackRef) Macro Definition Documentation #define Xil_ExceptionEnableMask( Mask ) Enable Exceptions. Mask for exceptions to be enabled. If bit is 0, exception is enabled. C-Style signature: void Xil_ExceptionEnableMask(Mask) #define Xil_ExceptionEnable( ) Enable the IRQ exception. #define Xil_ExceptionDisableMask( Mask ) Disable Exceptions. Mask for exceptions to be enabled. 224

225 If bit is 1, exception is disabled. C-Style signature: Xil_ExceptionDisableMask(Mask) #define Xil_ExceptionDisable( ) Disable the IRQ exception. #define Xil_EnableNestedInterrupts( ) Enable nested interrupts by clearing the I and F bits in CPSR. This API is defined for cortex-a9 and cortex-r5. This macro is supposed to be used from interrupt handlers. In the interrupt handler the interrupts are disabled by default (I and F are 1). To allow nesting of interrupts, this macro should be used. It clears the I and F bits by changing the ARM mode to system mode. Once these bits are cleared and provided the preemption of interrupt conditions are met in the GIC, nesting of interrupts will start happening. Caution: This macro must be used with caution. Before calling this macro, the user must ensure that the source of the current IRQ is appropriately cleared. Otherwise, as soon as we clear the I and F bits, there can be an infinite loop of interrupts with an eventual crash (all the stack space getting consumed). #define Xil_DisableNestedInterrupts( ) Disable the nested interrupts by setting the I and F bits. This API is defined for cortex-a9 and cortex-r5. This macro is meant to be called in the interrupt service routines. This macro cannot be used independently. It can only be used when nesting of interrupts have been enabled by using the macro Xil_EnableNestedInterrupts(). In a typical flow, the user first calls the Xil_EnableNestedInterrupts in the ISR at the appropriate point. The user then must call this macro before exiting the interrupt service routine. This macro puts the ARM back in IRQ/FIQ mode and hence sets back the I and F bits. Typedef Documentation 225

226 typedef void( Xil_ExceptionHandler) (void data) This typedef is the exception handler function. Function Documentation void Xil_ExceptionRegisterHandler ( u32 Exception_id, Xil_ExceptionHandler Handler, void Data ) Register a handler for a specific exception. This handler is being called when the processor encounters the specified exception. exception_id Handler Data contains the ID of the exception source and should be in the range of 0 to XIL_EXCEPTION_ID_LAST. See xil_exception.h for further information. to the Handler for that exception. is a reference to Data that will be passed to the Handler when it gets called. void Xil_ExceptionRemoveHandler ( u32 Exception_id ) Removes the Handler for a specific exception Id. The stub Handler is then registered for this exception Id. exception_id contains the ID of the exception source and should be in the range of 0 to XIL_EXCEPTION_ID_LAST. See xil_exception.h for further information. 226

227 void Xil_ExceptionInit ( void ) The function is a common API used to initialize exception handlers across all supported arm processors. For ARM Cortex-A53, Cortex-R5, and Cortex-A9, the exception handlers are being initialized statically and this function does not do anything. However, it is still present to take care of backward compatibility issues (in earlier versions of BSPs, this API was being used to initialize exception handlers). void Xil_DataAbortHandler ( void CallBackRef ) Default Data abort handler which prints data fault status register through which information about data fault can be acquired None void Xil_PrefetchAbortHandler ( void CallBackRef ) Default Prefetch abort handler which prints prefetch fault status register through which information about instruction prefetch fault can be acquired None 227

228 void Xil_UndefinedExceptionHandler ( void CallBackRef ) Default undefined exception handler which prints address of the undefined instruction if debug prints are enabled None 228

229 Cortex A9 Processor API Overview Standalone BSP contains boot code, cache, exception handling, file and memory management, configuration, time and processor-specific include functions. It supports gcc compilers. Modules Cortex A9 Processor Boot Code Cortex A9 Processor Cache Functions Cortex A9 Processor MMU Functions Cortex A9 Time Functions Cortex A9 Event Counter Function PL310 L2 Event Counters Functions Cortex A9 Processor and pl310 Errata Support Cortex A9 Processor Specific Include Files Cortex A9 Processor Boot Code Overview The boot.s file contains a minimal set of code for transferring control from the processor reset location to the start of the application. The boot code performs minimum configuration which is required for an application to run starting from processor's reset state. Below is a sequence illustrating what all configuration is performed before control reaches to main function. 1. Program vector table base for exception handling 2. Invalidate instruction cache, data cache and TLBs 3. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system) 4. Configure MMU with short descriptor translation table format and program base address of translation table 5. Enable data cache, instruction cache and MMU 229

230 6. Enable Floating point unit 7. Transfer control to _start which clears BSS sections, initializes global timer and runs global constructor before jumping to main application The translation_table.s file contains a static page table required by MMU for cortex-a9. This translation table is flat mapped (input address = output address) with default memory attributes defined for zynq architecture. It utilizes short descriptor translation table format with each section defining 1MB of memory. The overview of translation table memory attributes is described below. Memory Range DDR 0x x3FFFFFFF PL 0x xBFFFFFFF Reserved 0xC xDFFFFFFF Definition in Translation Table Normal write-back Cacheable Strongly Ordered Unassigned For a system where DDR is less than 1GB, region after DDR and before PL is marked as undefined/reserved in translation table Memory mapped devices 0xE xE02FFFFF Device Memory Reserved 0xE xE0FFFFFF NAND, NOR 0xE xE3FFFFFF SRAM 0xE xE5FFFFFF Reserved 0xE xF7FFFFFF AMBA APB Peripherals 0xF xF8FFFFFF Unassigned Device memory Normal write-back Cacheable Unassigned Device Memory 0xF8000C00-0xF8000FFF, 0xF xF88FFFFF and 0xF8F03000 to 0xF8FFFFFF are reserved but due to granual size of 1MB, it is not possible to define separate regions for them 230

231 Memory Range Reserved 0xF xFBFFFFFF Linear QSPI - XIP 0xFC xFDFFFFFF Reserved 0xFE xFFEFFFFF OCM 0xFFF xFFFFFFFF Definition in Translation Table Unassigned Normal write-through cacheable Unassigned Normal inner write-back cacheable 0xFFF00000 to 0xFFFB0000 is reserved but due to 1MB granual size, it is not possible to define separate region for it Cortex A9 Processor Cache Functions Overview Cache functions provide access to cache related operations such as flush and invalidate for instruction and data caches. It gives option to perform the cache operations on a single cacheline, a range of memory and an entire cache. Functions void Xil_DCacheEnable (void) void Xil_DCacheDisable (void) void Xil_DCacheInvalidate (void) void Xil_DCacheInvalidateRange (INTPTR adr, u32 len) void Xil_DCacheFlush (void) void Xil_DCacheFlushRange (INTPTR adr, u32 len) void Xil_ICacheEnable (void) void Xil_ICacheDisable (void) void Xil_ICacheInvalidate (void) void Xil_ICacheInvalidateRange (INTPTR adr, u32 len) void Xil_DCacheInvalidateLine (u32 adr) void Xil_DCacheFlushLine (u32 adr) void Xil_DCacheStoreLine (u32 adr) void Xil_ICacheInvalidateLine (u32 adr) void Xil_L1DCacheEnable (void) void Xil_L1DCacheDisable (void) 231

232 void Xil_L1DCacheInvalidate (void) void Xil_L1DCacheInvalidateLine (u32 adr) void Xil_L1DCacheInvalidateRange (u32 adr, u32 len) void Xil_L1DCacheFlush (void) void Xil_L1DCacheFlushLine (u32 adr) void Xil_L1DCacheFlushRange (u32 adr, u32 len) void Xil_L1DCacheStoreLine (u32 adr) void Xil_L1ICacheEnable (void) void Xil_L1ICacheDisable (void) void Xil_L1ICacheInvalidate (void) void Xil_L1ICacheInvalidateLine (u32 adr) void Xil_L1ICacheInvalidateRange (u32 adr, u32 len) void Xil_L2CacheEnable (void) void Xil_L2CacheDisable (void) void Xil_L2CacheInvalidate (void) void Xil_L2CacheInvalidateLine (u32 adr) void Xil_L2CacheInvalidateRange (u32 adr, u32 len) void Xil_L2CacheFlush (void) void Xil_L2CacheFlushLine (u32 adr) void Xil_L2CacheFlushRange (u32 adr, u32 len) void Xil_L2CacheStoreLine (u32 adr) Function Documentation void Xil_DCacheEnable ( void ) Enable the Data cache. 232

233 void Xil_DCacheDisable ( void ) Disable the Data cache. void Xil_DCacheInvalidate ( void ) Invalidate the entire Data cache. void Xil_DCacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the Data cache for the given address range. If the bytes specified by the address range are cached by the Data cache, the cachelines containing those bytes are invalidated. If the cachelines are modified (dirty), the modified contents are lost and NOT written to the system memory before the lines are invalidated. In this function, if start address or end address is not aligned to cache-line, particular cache-line containing unaligned start or end address is flush first and then invalidated the others as invalidating the same unaligned cache line may result into loss of data. This issue raises few possibilities. If the address to be invalidated is not cache-line aligned, the following choices are available: 1. Invalidate the cache line when required and do not bother much for the side effects. Though it sounds good, it can result in hard-to-debug issues. The problem is, if some other variable are allocated in the same cache line and had been recently updated (in cache), the invalidation would result in loss of data. 2. Flush the cache line first. This will ensure that if any other variable present in the same cache line and updated recently are flushed out to memory. Then it can safely be invalidated. Again it sounds good, but this can result in issues. For example, when the invalidation happens in a typical ISR (after a DMA transfer has updated the memory), then flushing the cache line means, loosing data that were updated recently before the ISR got invoked. 233

234 Linux prefers the second one. To have uniform implementation (across standalone and Linux), the second option is implemented. This being the case, follwoing needs to be taken care of: 1. Whenever possible, the addresses must be cache line aligned. Please nore that, not just start address, even the end address must be cache line aligned. If that is taken care of, this will always work. 2. Avoid situations where invalidation has to be done after the data is updated by peripheral/dma directly into the memory. It is not tough to achieve (may be a bit risky). The common use case to do invalidation is when a DMA happens. Generally for such use cases, buffers can be allocated first and then start the DMA. The practice that needs to be followed here is, immediately after buffer allocation and before starting the DMA, do the invalidation. With this approach, invalidation need not to be done after the DMA transfer is over. This is going to always work if done carefully. However, the concern is, there is no guarantee that invalidate has not needed to be done after DMA is complete. For example, because of some reasons if the first cache line or last cache line (assuming the buffer in question comprises of multiple cache lines) are brought into cache (between the time it is invalidated and DMA completes) because of some speculative prefetching or reading data for a variable present in the same cache line, then we will have to invalidate the cache after DMA is complete. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_DCacheFlush ( void ) Flush the entire Data cache. 234

235 void Xil_DCacheFlushRange ( INTPTR adr, u32 len ) Flush the Data cache for the given address range. If the bytes specified by the address range are cached by the data cache, the cachelines containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to the system memory before the lines are invalidated. adr len 32bit start address of the range to be flushed. Length of the range to be flushed in bytes. void Xil_ICacheEnable ( void ) Enable the instruction cache. void Xil_ICacheDisable ( void ) Disable the instruction cache. 235

236 void Xil_ICacheInvalidate ( void ) Invalidate the entire instruction cache. void Xil_ICacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the instruction cache for the given address range. If the instructions specified by the address range are cached by the instrunction cache, the cachelines containing those instructions are invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_DCacheInvalidateLine ( u32 adr ) Invalidate a Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are NOT written to the system memory before the line is invalidated. adr 32bit address of the data to be flushed. 236

237 The bottom 4 bits are set to 0, forced by architecture. void Xil_DCacheFlushLine ( u32 adr ) Flush a Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 32bit address of the data to be flushed. The bottom 4 bits are set to 0, forced by architecture. void Xil_DCacheStoreLine ( u32 adr ) Store a Data cache line. If the byte specified by the address (adr) is cached by the Data cache and the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory. After the store completes, the cacheline is marked as unmodified (not dirty). adr 32bit address of the data to be stored. The bottom 4 bits are set to 0, forced by architecture. 237

238 void Xil_ICacheInvalidateLine ( u32 adr ) Invalidate an instruction cache line. If the instruction specified by the address is cached by the instruction cache, the cacheline containing that instruction is invalidated. adr 32bit address of the instruction to be invalidated. The bottom 4 bits are set to 0, forced by architecture. void Xil_L1DCacheEnable ( void ) Enable the level 1 Data cache. void Xil_L1DCacheDisable ( void ) Disable the level 1 Data cache. 238

239 void Xil_L1DCacheInvalidate ( void ) Invalidate the level 1 Data cache. In Cortex A9, there is no cp instruction for invalidating the whole D-cache. This function invalidates each line by set/way. void Xil_L1DCacheInvalidateLine ( u32 adr ) Invalidate a level 1 Data cache line. If the byte specified by the address (Addr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are NOT written to system memory before the line is invalidated. adr 32bit address of the data to be invalidated. The bottom 5 bits are set to 0, forced by architecture. void Xil_L1DCacheInvalidateRange ( u32 adr, u32 len ) Invalidate the level 1 Data cache for the given address range. If the bytes specified by the address range are cached by the Data cache, the cachelines containing those bytes are invalidated. If the cachelines are modified (dirty), the modified contents are lost and NOT written to the system memory before the lines are invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. 239

240 void Xil_L1DCacheFlush ( void ) Flush the level 1 Data cache. In Cortex A9, there is no cp instruction for flushing the whole D-cache. Need to flush each line. void Xil_L1DCacheFlushLine ( u32 adr ) Flush a level 1 Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 32bit address of the data to be flushed. The bottom 5 bits are set to 0, forced by architecture. 240

241 void Xil_L1DCacheFlushRange ( u32 adr, u32 len ) Flush the level 1 Data cache for the given address range. If the bytes specified by the address range are cached by the Data cache, the cacheline containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to system memory before the lines are invalidated. adr len 32bit start address of the range to be flushed. Length of the range to be flushed in bytes. void Xil_L1DCacheStoreLine ( u32 adr ) Store a level 1 Data cache line. If the byte specified by the address (adr) is cached by the Data cache and the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory. After the store completes, the cacheline is marked as unmodified (not dirty). Address to be stored. The bottom 5 bits are set to 0, forced by architecture. void Xil_L1ICacheEnable ( void ) Enable the level 1 instruction cache. 241

242 void Xil_L1ICacheDisable ( void ) Disable level 1 the instruction cache. void Xil_L1ICacheInvalidate ( void ) Invalidate the entire level 1 instruction cache. void Xil_L1ICacheInvalidateLine ( u32 adr ) Invalidate a level 1 instruction cache line. If the instruction specified by the address is cached by the instruction cache, the cacheline containing that instruction is invalidated. adr 32bit address of the instruction to be invalidated. 242

243 The bottom 5 bits are set to 0, forced by architecture. void Xil_L1ICacheInvalidateRange ( u32 adr, u32 len ) Invalidate the level 1 instruction cache for the given address range. If the instrucions specified by the address range are cached by the instruction cache, the cacheline containing those bytes are invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_L2CacheEnable ( void ) Enable the L2 cache. void Xil_L2CacheDisable ( void ) Disable the L2 cache. 243

244 void Xil_L2CacheInvalidate ( void ) Invalidate the entire level 2 cache. void Xil_L2CacheInvalidateLine ( u32 adr ) Invalidate a level 2 cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are NOT written to system memory before the line is invalidated. adr 32bit address of the data/instruction to be invalidated. The bottom 4 bits are set to 0, forced by architecture. 244

245 void Xil_L2CacheInvalidateRange ( u32 adr, u32 len ) Invalidate the level 2 cache for the given address range. If the bytes specified by the address range are cached by the L2 cache, the cacheline containing those bytes are invalidated. If the cachelines are modified (dirty), the modified contents are lost and are NOT written to system memory before the lines are invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_L2CacheFlush ( void ) Flush the entire level 2 cache. void Xil_L2CacheFlushLine ( u32 adr ) Flush a level 2 cache line. If the byte specified by the address (adr) is cached by the L2 cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 32bit address of the data/instruction to be flushed. 245

246 The bottom 4 bits are set to 0, forced by architecture. void Xil_L2CacheFlushRange ( u32 adr, u32 len ) Flush the level 2 cache for the given address range. If the bytes specified by the address range are cached by the L2 cache, the cacheline containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to the system memory before the lines are invalidated. adr len 32bit start address of the range to be flushed. Length of the range to be flushed in bytes. void Xil_L2CacheStoreLine ( u32 adr ) Store a level 2 cache line. If the byte specified by the address (adr) is cached by the L2 cache and the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory. After the store completes, the cacheline is marked as unmodified (not dirty). adr 32bit address of the data/instruction to be stored. The bottom 4 bits are set to 0, forced by architecture. Cortex A9 Processor MMU Functions Overview MMU functions equip users to enable MMU, disable MMU and modify default memory attributes of MMU table as per the need. 246

247 Functions void Xil_SetTlbAttributes (INTPTR Addr, u32 attrib) void Xil_EnableMMU (void) void Xil_DisableMMU (void) Function Documentation void Xil_SetTlbAttributes ( INTPTR Addr, u32 attrib ) This function sets the memory attributes for a section covering 1MB of memory in the translation table. Addr 32-bit address for which memory attributes need to be set. attrib Attribute for the given memory region. xil_mmu.h contains definitions of commonly used memory attributes which can be utilized for this function. The MMU or D-cache does not need to be disabled before changing a translation table entry. void Xil_EnableMMU ( void ) Enable MMU for cortex A9 processor. This function invalidates the instruction and data caches, and then enables MMU. 247

248 void Xil_DisableMMU ( void ) Disable MMU for Cortex A9 processors. This function invalidates the TLBs, Branch Predictor Array and flushed the D Caches before disabling the MMU. When the MMU is disabled, all the memory accesses are treated as strongly ordered. Cortex A9 Time Functions Overview xtime_l.h provides access to the 64-bit Global Counter in the PMU. This counter increases by one at every two processor cycles. These functions can be used to get/set time in the global timer. Functions void XTime_SetTime (XTime Xtime_Global) void XTime_GetTime (XTime Xtime_Global) Function Documentation void XTime_SetTime ( XTime Xtime_Global ) Set the time in the Global Timer Counter Register. Xtime_Global 64-bit Value to be written to the Global Timer Counter Register. When this function is called by any one processor in a multi- processor environment, reference time will reset/lost for all processors. 248

249 void XTime_GetTime ( XTime Xtime_Global ) Get the time from the Global Timer Counter Register. Xtime_Global Pointer to the 64-bit location which will be updated with the current timer value. Cortex A9 Event Counter Function Overview Cortex A9 event counter functions can be utilized to configure and control the Cortex-A9 performance monitor events. Cortex-A9 performance monitor has six event counters which can be used to count a variety of events described in Coretx-A9 TRM. xpm_counter.h defines configurations XPM_CNTRCFGx which can be used to program the event counters to count a set of events. It doesn't handle the Cortex-A9 cycle counter, as the cycle counter is being used for time keeping. Functions void Xpm_SetEvents (s32 PmcrCfg) void Xpm_GetEventCounters (u32 PmCtrValue) Function Documentation void Xpm_SetEvents ( s32 PmcrCfg ) This function configures the Cortex A9 event counters controller, with the event codes, in a configuration selected by the user and enables the counters. PmcrCfg Configuration value based on which the event counters are configured. XPM_CNTRCFG values defined in xpm_counter.h can be utilized for setting configuration. 249

250 void Xpm_GetEventCounters ( u32 PmCtrValue ) This function disables the event counters and returns the counter values. PmCtrValue Pointer to an array of type u32 PmCtrValue[6]. It is an output parameter which is used to return the PM counter values. PL310 L2 Event Counters Functions Overview xl2cc_counter.h contains APIs for configuring and controlling the event counters in PL310 L2 cache controller. PL310 has two event counters which can be used to count variety of events like DRHIT, DRREQ, DWHIT, DWREQ, etc. xl2cc_counter.h contains definitions for different configurations which can be used for the event counters to count a set of events. Functions void XL2cc_EventCtrInit (s32 Event0, s32 Event1) void XL2cc_EventCtrStart (void) void XL2cc_EventCtrStop (u32 EveCtr0, u32 EveCtr1) Function Documentation 250

251 void XL2cc_EventCtrInit ( s32 Event0, s32 Event1 ) This function initializes the event counters in L2 Cache controller with a set of event codes specified by the user. Event0 Event code for counter 0. Event1 Event code for counter 1. The definitions for event codes XL2CC_ can be found in xl2cc_counter.h. void XL2cc_EventCtrStart ( void ) This function starts the event counters in L2 Cache controller. void XL2cc_EventCtrStop ( u32 EveCtr0, u32 EveCtr1 ) This function disables the event counters in L2 Cache controller, saves the counter values and resets the counters. EveCtr0 Output parameter which is used to return the value in event counter 0. EveCtr1: Output parameter which is used to return the value in event counter

252 Cortex A9 Processor and pl310 Errata Support Overview Various ARM errata are handled in the standalone BSP. The implementation for errata handling follows ARM guidelines and is based on the open source Linux support for these errata. The errata handling is enabled by default. To disable handling of all the errata globally, un-define the macro ENABLE_ARM_ERRATA in xil_errata.h. To disable errata on a per-erratum basis, un-define relevant macros in xil_errata.h. errata_definitions The errata conditions handled in the standalone BSP are listed below #define ENABLE_ARM_ERRATA #define CONFIG_ARM_ERRATA_ #define CONFIG_ARM_ERRATA_ #define CONFIG_ARM_ERRATA_ #define CONFIG_ARM_ERRATA_ #define CONFIG_PL310_ERRATA_ #define CONFIG_PL310_ERRATA_ #define CONFIG_PL310_ERRATA_ Macro Definition Documentation #define CONFIG_ARM_ERRATA_ Errata No: Description: DMB operation may be faulty #define CONFIG_ARM_ERRATA_ Errata No: Description: Faulty hazard checking in the Store Buffer may lead to data corruption. 252

253 #define CONFIG_ARM_ERRATA_ Errata No: Description: A data cache maintenance operation which aborts, might lead to deadlock #define CONFIG_ARM_ERRATA_ Errata No: Description: Speculative instruction fetches with MMU disabled might not comply with architectural requirements #define CONFIG_PL310_ERRATA_ PL310 L2 Cache Errata Errata No: Description: Clean & Invalidate maintenance operations do not invalidate clean lines #define CONFIG_PL310_ERRATA_ Errata No: Description: Background Clean and Invalidate by Way operation can cause data corruption #define CONFIG_PL310_ERRATA_ Errata No: Description: Cache sync operation may be faulty Cortex A9 Processor Specific Include Files The xpseudo_asm.h includes xreg_cortexa9.h and xpseudo_asm_gcc.h. The xreg_cortexa9.h file contains definitions for inline assembler code. It provides inline definitions for Cortex A9 GPRs, SPRs, MPE registers, co-processor registers and Debug registers. The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler instructions, available as macros. These can be very useful for tasks such as setting or getting special purpose registers, synchronization, or cache manipulation etc. These inline assembler instructions can be used from drivers and user applications written in C. 253

254 Cortex A53 32-bit Processor API Overview Cortex-A53 standalone BSP contains two separate BSPs for 32-bit mode and 64-bit mode. The 32-bit mode of cortex-a53 is compatible with ARMv7-A architecture. Modules Cortex A53 32-bit Processor Boot Code Cortex A53 32-bit Processor Cache Functions Cortex A53 32-bit Processor MMU Handling Cortex A53 32-bit Mode Time Functions Cortex A53 32-bit Processor Specific Include Files Cortex A53 32-bit Processor Boot Code Overview The boot.s file contains a minimal set of code for transferring control from the processor reset location to the start of the application. The boot code performs minimum configuration which is required for an application to run starting from processor's reset state. Below is a sequence illustrating what all configuration is performed before control reaches to main function. 1. Program vector table base for exception handling 2. Invalidate instruction cache, data cache and TLBs 3. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system) 4. Program counter frequency 5. Configure MMU with short descriptor translation table format and program base address of translation table 6. Enable data cache, instruction cache and MMU 254

255 7. Transfer control to _start which clears BSS sections and runs global constructor before jumping to main application The translation_table.s file contains a static page table required by MMU for cortex-a53. This translation table is flat mapped (input address = output address) with default memory attributes defined for zynq ultrascale+ architecture. It utilizes short descriptor translation table format with each section defining 1MB of memory. The overview of translation table memory attributes is described below. Memory Range DDR 0x x7FFFFFFF PL 0x xBFFFFFFF QSPI, lower PCIe 0xC xEFFFFFFF Reserved 0xF xF7FFFFFF STM Coresight 0xF xF8FFFFFF GIC 0xF xF90FFFFF Reserved 0xF xFCFFFFFF FPS, LPS slaves 0xFD xFFBFFFFF CSU, PMU 0xFFC xFFDFFFFF TCM, OCM 0xFFE xFFFFFFFF Definition in Translation Table Normal write-back Cacheable Strongly Ordered Device Memory Unassigned Device Memory Device memory Unassigned Device memory Device Memory Normal write-back cacheable For a system where DDR is less than 2GB, region after DDR and before PL is marked as undefined/reserved in translation table This region contains CSU and PMU memory which are marked as Device since it is less than 1MB and falls in a region with device memory 255

256 Cortex A53 32-bit Processor Cache Functions Overview Cache functions provide access to cache related operations such as flush and invalidate for instruction and data caches. It gives option to perform the cache operations on a single cacheline, a range of memory and an entire cache. Functions void Xil_DCacheEnable (void) void Xil_DCacheDisable (void) void Xil_DCacheInvalidate (void) void Xil_DCacheInvalidateRange (INTPTR adr, u32 len) void Xil_DCacheInvalidateLine (u32 adr) void Xil_DCacheFlush (void) void Xil_DCacheFlushLine (u32 adr) void Xil_ICacheEnable (void) void Xil_ICacheDisable (void) void Xil_ICacheInvalidate (void) void Xil_ICacheInvalidateRange (INTPTR adr, u32 len) void Xil_ICacheInvalidateLine (u32 adr) Function Documentation void Xil_DCacheEnable ( void ) Enable the Data cache. 256

257 void Xil_DCacheDisable ( void ) Disable the Data cache. void Xil_DCacheInvalidate ( void ) Invalidate the Data cache. The contents present in the data cache are cleaned and invalidated. In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate to avoid such corruption. void Xil_DCacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the Data cache for the given address range. The cachelines present in the adderss range are cleaned and invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. 257

258 In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate to avoid such corruption. void Xil_DCacheInvalidateLine ( u32 adr ) Invalidate a Data cache line. The cacheline is cleaned and invalidated. adr 32 bit address of the data to be invalidated. In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate to avoid such corruption. void Xil_DCacheFlush ( void ) Flush the Data cache. 258

259 void Xil_DCacheFlushLine ( u32 adr ) Flush a Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 32bit address of the data to be flushed. The bottom 4 bits are set to 0, forced by architecture. void Xil_ICacheEnable ( void ) Enable the instruction cache. void Xil_ICacheDisable ( void ) Disable the instruction cache. 259

260 void Xil_ICacheInvalidate ( void ) Invalidate the entire instruction cache. void Xil_ICacheInvalidateRange ( INTPTR adr, u32 len ) Invalidate the instruction cache for the given address range. If the instructions specified by the address range are cached by the instrunction cache, the cachelines containing those instructions are invalidated. adr len 32bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. void Xil_ICacheInvalidateLine ( u32 adr ) Invalidate an instruction cache line. If the instruction specified by the address is cached by the instruction cache, the cachecline containing that instruction is invalidated. adr 32bit address of the instruction to be invalidated.. The bottom 4 bits are set to 0, forced by architecture. 260

261 Cortex A53 32-bit Processor MMU Handling Overview MMU functions equip users to enable MMU, disable MMU and modify default memory attributes of MMU table as per the need. Functions void Xil_SetTlbAttributes (INTPTR Addr, u32 attrib) void Xil_EnableMMU (void) void Xil_DisableMMU (void) Function Documentation void Xil_SetTlbAttributes ( INTPTR Addr, u32 attrib ) This function sets the memory attributes for a section covering 1MB of memory in the translation table. Addr attrib 32-bit address for which the attributes need to be set. Attributes for the specified memory region. xil_mmu.h contains commonly used memory attributes definitions which can be utilized for this function. The MMU or D-cache does not need to be disabled before changing a translation table entry. void Xil_EnableMMU ( void ) Enable MMU for Cortex-A53 processor in 32bit mode. This function invalidates the instruction and data caches before enabling MMU. 261

262 void Xil_DisableMMU ( void ) Disable MMU for Cortex A53 processors in 32bit mode. This function invalidates the TLBs, Branch Predictor Array and flushed the data cache before disabling the MMU. When the MMU is disabled, all the memory accesses are treated as strongly ordered. Cortex A53 32-bit Mode Time Functions Overview The xtime_l.c file and corresponding xtime_l.h include file provide access to the 64-bit generic counter in Cortex-A53. The sleep.c, usleep.c file and the corresponding sleep.h include file implement sleep functions. Sleep functions are implemented as busy loops. Functions void XTime_StartTimer (void) void XTime_SetTime (XTime Xtime_Global) void XTime_GetTime (XTime Xtime_Global) Function Documentation void XTime_StartTimer ( void ) Start the 64-bit physical timer counter. 262

263 The timer is initialized only if it is disabled. If the timer is already running this function does not perform any operation. void XTime_SetTime ( XTime Xtime_Global ) Timer of A53 runs continuously and the time can not be set as desired. This API doesn't contain anything. It is defined to have uniformity across platforms. Xtime_Global 64bit Value to be written to the Global Timer Counter Register. void XTime_GetTime ( XTime Xtime_Global ) Get the time from the physical timer counter register. Xtime_Global Pointer to the 64-bit location to be updated with the current value in physical timer counter. Cortex A53 32-bit Processor Specific Include Files The xreg_cortexa53.h file contains definitions for inline assembler code. It provides inline definitions for Cortex A53 GPRs, SPRs and floating point registers. The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler instructions, available as macros. These can be very useful for tasks such as setting or getting special purpose registers, synchronization, or cache manipulation. These inline assembler instructions can be used from drivers and user applications written in C. 263

264 Cortex A53 64-bit Processor API Overview Cortex-A53 standalone BSP contains two separate BSPs for 32-bit mode and 64-bit mode. The 64-bit mode of cortex-a53 contains ARMv8-A architecture. This section provides a linked summary and detailed descriptions of the Cortex A53 64-bit Processor APIs. Modules Cortex A53 64-bit Processor Boot Code Cortex A53 64-bit Processor Cache Functions Cortex A53 64-bit Processor MMU Handling Cortex A53 64-bit Mode Time Functions Cortex A53 64-bit Processor Specific Include Files Cortex A53 64-bit Processor Boot Code Overview The boot.s file contains a minimal set of code for transferring control from the processor reset location to the start of the application. The boot code performs minimum configuration which is required for an application to run starting from processor's reset state. Cortex-A53 starts execution from EL3 and currently application is also run from EL3. Below is a sequence illustrating what all configuration is performed before control reaches to main function. 1. Program vector table base for exception handling 2. Set reset vector table base address 3. Program stack pointer for EL3 4. Routing of interrupts to EL3 5. Enable ECC protection 6. Program generic counter frequency 264

265 7. Invalidate instruction cache, data cache and TLBs 8. Configure MMU registers and program base address of translation table 9. Transfer control to _start which clears BSS sections and runs global constructor before jumping to main application Cortex A53 64-bit Processor Cache Functions Overview Cache functions provide access to cache related operations such as flush and invalidate for instruction and data caches. It gives option to perform the cache operations on a single cacheline, a range of memory and an entire cache. Functions void Xil_DCacheEnable (void) void Xil_DCacheDisable (void) void Xil_DCacheInvalidate (void) void Xil_DCacheInvalidateRange (INTPTR adr, INTPTR len) void Xil_DCacheInvalidateLine (INTPTR adr) void Xil_DCacheFlush (void) void Xil_DCacheFlushLine (INTPTR adr) void Xil_ICacheEnable (void) void Xil_ICacheDisable (void) void Xil_ICacheInvalidate (void) void Xil_ICacheInvalidateRange (INTPTR adr, INTPTR len) void Xil_ICacheInvalidateLine (INTPTR adr) Function Documentation void Xil_DCacheEnable ( void ) Enable the Data cache. 265

266 void Xil_DCacheDisable ( void ) Disable the Data cache. void Xil_DCacheInvalidate ( void ) Invalidate the Data cache. The contents present in the cache are cleaned and invalidated. In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate which avoids such corruption. 266

267 void Xil_DCacheInvalidateRange ( INTPTR adr, INTPTR len ) Invalidate the Data cache for the given address range. The cachelines present in the adderss range are cleaned and invalidated. adr len 64bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate which avoids such corruption. void Xil_DCacheInvalidateLine ( INTPTR adr ) Invalidate a Data cache line. The cacheline is cleaned and invalidated. adr 64bit address of the data to be flushed. In Cortex-A53, functionality to simply invalide the cachelines is not present. Such operations are a problem for an environment that supports virtualisation. It would allow one OS to invalidate a line belonging to another OS. This could lead to the other OS crashing because of the loss of essential data. Hence, such operations are promoted to clean and invalidate which avoids such corruption. 267

268 void Xil_DCacheFlush ( void ) Flush the Data cache. void Xil_DCacheFlushLine ( INTPTR adr ) Flush a Data cache line. If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are written to system memory before the line is invalidated. adr 64bit address of the data to be flushed. The bottom 6 bits are set to 0, forced by architecture. void Xil_ICacheEnable ( void ) Enable the instruction cache. 268

269 void Xil_ICacheDisable ( void ) Disable the instruction cache. void Xil_ICacheInvalidate ( void ) Invalidate the entire instruction cache. void Xil_ICacheInvalidateRange ( INTPTR adr, INTPTR len ) Invalidate the instruction cache for the given address range. If the instructions specified by the address range are cached by the instrunction cache, the cachelines containing those instructions are invalidated. adr len 64bit start address of the range to be invalidated. Length of the range to be invalidated in bytes. 269

270 void Xil_ICacheInvalidateLine ( INTPTR adr ) Invalidate an instruction cache line. If the instruction specified by the parameter adr is cached by the instruction cache, the cacheline containing that instruction is invalidated. adr 64bit address of the instruction to be invalidated. The bottom 6 bits are set to 0, forced by architecture. Cortex A53 64-bit Processor MMU Handling Overview MMU function equip users to modify default memory attributes of MMU table as per the need. Functions void Xil_SetTlbAttributes (INTPTR Addr, u64 attrib) Function Documentation void Xil_SetTlbAttributes ( INTPTR Addr, u64 attrib ) brief It sets the memory attributes for a section, in the translation table. If the address (defined by Addr) is less than 4GB, the memory attribute(attrib) is set for a section of 2MB memory. If the address (defined by Addr) is greater than 4GB, the memory attribute (attrib) is set for a section of 1GB memory. Addr attrib 64-bit address for which attributes are to be set. Attribute for the specified memory region. xil_mmu.h contains commonly used memory attributes definitions which can be utilized for this function. 270

271 The MMU and D-cache need not be disabled before changing an translation table attribute. Cortex A53 64-bit Mode Time Functions Overview The xtime_l.c file and corresponding xtime_l.h include file provide access to the 64-bit generic counter in Cortex-A53. The sleep.c, usleep.c file and the corresponding sleep.h include file implement sleep functions. Sleep functions are implemented as busy loops. Functions void XTime_StartTimer (void) void XTime_SetTime (XTime Xtime_Global) void XTime_GetTime (XTime Xtime_Global) Function Documentation void XTime_StartTimer ( void ) Start the 64-bit physical timer counter. The timer is initialized only if it is disabled. If the timer is already running this function does not perform any operation. 271

272 void XTime_SetTime ( XTime Xtime_Global ) Timer of A53 runs continuously and the time can not be set as desired. This API doesn't contain anything. It is defined to have uniformity across platforms. Xtime_Global 64bit value to be written to the physical timer counter register. void XTime_GetTime ( XTime Xtime_Global ) Get the time from the physical timer counter register. Xtime_Global Pointer to the 64-bit location to be updated with the current value of physical timer counter register. Cortex A53 64-bit Processor Specific Include Files The xreg_cortexa53.h file contains definitions for inline assembler code. It provides inline definitions for Cortex A53 GPRs, SPRs and floating point registers. The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler instructions, available as macros. These can be very useful for tasks such as setting or getting special purpose registers, synchronization, or cache manipulation. These inline assembler instructions can be used from drivers and user applications written in C. 272

273 Appendix D: XilFlash Library v

274 Overview The XilFlash library provides read/write/erase/lock/unlock features to access a parallel flash device. This library implements the functionality for flash memory devices that conform to the "Common Flash Interface" (CFI) standard. CFI allows a single flash library to be used for an entire family of parts and helps us determine the algorithm to utilize during runtime. All the calls in the library are blocking in nature in that the control is returned back to user only after the current operation is completed successfully or an error is reported. Library Initialization The XFlash_Initialize() function should be called by the application before any other function in the library. The initialization function checks for the device family and initializes the XFlash instance with the family specific data. The VT table (contains the function pointers to family specific APIs) is setup and family specific initialization routine is called. Device Geometry The device geometry varies for different flash device families. Following sections describes the geometry of different flash device families: Intel Flash Device Geometry Flash memory space is segmented into areas called blocks. The size of each block is based on a power of 2. A region is defined as a contiguous set of blocks of the same size. Some parts have several regions while others have one. The arrangement of blocks and regions is referred to by this module as the part's geometry. Some Intel flash supports multiple banks on the same device. This library supports single and multiple bank flash devices. AMD Flash Device Geometry Flash memory space is segmented into areas called banks and further in to regions and blocks. The size of each block is based on a power of 2. A region is defined as a contiguous set of blocks of the same size. Some parts have several regions while others have one. A bank is defined as a contiguous set of blocks. The bank 274

275 may contain blocks of different size. The arrangement of blocks, regions and banks is referred to by this module as the part's geometry. The cells within the part can be programmed from a logic 1 to a logic 0 and not the other way around. To change a cell back to a logic 1, the entire block containing that cell must be erased. When a block is erased all bytes contain the value 0xFF. The number of times a block can be erased is finite. Eventually the block will wear out and will no longer be capable of erasure. As of this writing, the typical flash block can be erased 100,000 or more times. Write Operation The write call can be used to write a minimum of zero bytes and a maximum entire flash. If the Offset Address specified to write is out of flash or if the number of bytes specified from the Offset address exceed flash boundaries an error is reported back to the user. The write is blocking in nature in that the control is returned back to user only after the write operation is completed successfully or an error is reported. Read Operation The read call can be used to read a minimum of zero bytes and maximum of entire flash. If the Offset Address specified to write is out of flash boundary an error is reported back to the user. The read function reads memory locations beyond Flash boundary. Care should be taken by the user to make sure that the Number of Bytes + Offset address is within the Flash address boundaries. The write is blocking in nature in that the control is returned back to user only after the read operation is completed successfully or an error is reported. Erase Operation The erase operations are provided to erase a Block in the Flash memory. The erase call is blocking in nature in that the control is returned back to user only after the erase operation is completed successfully or an error is reported. Sector Protection The Flash Device is divided into Blocks. Each Block can be protected individually from unwarranted writing/erasing. The Block locking can be achieved using XFlash_Lock() lock. All the memory locations from the Offset address specified will be locked. The block can be unlocked using XFlash_UnLock() call. All the Blocks which are previously locked will be unlocked. The Lock and Unlock calls are blocking in nature in that the control is returned back to user only after the operation is completed successfully or an error is reported. The AMD flash device requires high voltage on Reset pin to perform lock and unlock operation. User must provide this high voltage (As defined in datasheet) to reset pin before calling lock and unlock API for AMD flash devices. Lock and Unlock features are not tested for AMD flash device. Device Control Functionalities specific to a Flash Device Family are implemented as Device Control. The following are the Intel specific device control: 275

276 Retrieve the last error data. Get Device geometry. Get Device properties. Set RYBY pin mode. Set the Configuration register (Platform Flash only). The following are the AMD specific device control: Get Device geometry. Get Device properties. Erase Resume. Erase Suspend. Enter Extended Mode. Exit Extended Mode. Get Protection Status of Block Group. Erase Chip. This library needs to know the type of EMC core (AXI or XPS) used to access the cfi flash, to map the correct APIs. This library should be used with the emc driver, v3_01_a and above, so that this information can be automatically obtained from the emc driver. This library is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads, mutual exclusion, virtual memory, cache control, or HW write protection management must be satisfied by the layer above this library. All writes to flash occur in units of bus-width bytes. If more than one part exists on the data bus, then the parts are written in parallel. Reads from flash are performed in any width up to the width of the data bus. It is assumed that the flash bus controller or local bus supports these types of accesses. 276

277 XilFlash Library API Overview This chapter provides a linked summary and detailed descriptions of the LibXil Flash library APIs. Functions int XFlash_Initialize (XFlash InstancePtr, u32 BaseAddress, u8 BusWidth, int IsPlatformFlash) int XFlash_Reset (XFlash InstancePtr) int XFlash_DeviceControl (XFlash InstancePtr, u32 Command, DeviceCtrlParam ) int XFlash_Read (XFlash InstancePtr, u32 Offset, u32 Bytes, void DestPtr) int XFlash_Write (XFlash InstancePtr, u32 Offset, u32 Bytes, void SrcPtr) int XFlash_Erase (XFlash InstancePtr, u32 Offset, u32 Bytes) int XFlash_Lock (XFlash InstancePtr, u32 Offset, u32 Bytes) int XFlash_Unlock (XFlash InstancePtr, u32 Offset, u32 Bytes) int XFlash_IsReady (XFlash InstancePtr) Function Documentation int XFlash_Initialize ( XFlash InstancePtr, u32 BaseAddress, u8 BusWidth, int IsPlatformFlash ) This function initializes a specific XFlash instance. The initialization entails: Check the Device family type. Issuing the CFI query command. Get and translate relevant CFI query information. Set default options for the instance. Setup the VTable. Call the family initialize function of the instance. 277

278 Initialize the Xilinx Platform Flash XL to Async mode if the user selects to use the Platform Flash XL in the MLD. The Platform Flash XL is an Intel CFI complaint device. InstancePtr BaseAddress BusWidth IsPlatformFlash Pointer to the XFlash instance. Base address of the flash memory. Total width of the flash memory, in bytes. Used to specify if the flash is a platform flash. XST_SUCCESS if successful. XFLASH_PART_NOT_SUPPORTED if the command set algorithm or Layout is not supported by any flash family compiled into the system. XFLASH_CFI_QUERY_ERROR if the device would not enter CFI query mode. Either the device(s) do not support CFI, the wrong BaseAddress param was used, an unsupported part layout exists, or a hardware problem exists with the part. BusWidth is not the width of an individual part. Its the total operating width. For example, if there are two 16-bit parts, with one tied to data lines D0-D15 and other tied to D15-D31, BusWidth would be (32 / 8) = 4. If a single 16-bit flash is in 8-bit mode, then BusWidth should be (8 / 8) = 1. int XFlash_Reset ( XFlash InstancePtr ) This function resets the flash device and places it in read mode. InstancePtr Pointer to the XFlash instance. XST_SUCCESS if successful. XFLASH_BUSY if the flash devices were in the middle of an operation and could not be reset. XFLASH_ERROR if the device(s) have experienced an internal error during the operation. XFlash_DeviceControl() must be used to access the cause of the device specific error. condition. 278

279 int XFlash_DeviceControl ( XFlash InstancePtr, u32 Command, DeviceCtrlParam ) This function is used to execute device specific commands. For a list of device specific commands, see the xilflash.h. InstancePtr Command Pointer to the XFlash instance. Device specific command to issue. Specifies the arguments passed to the device control function. XST_SUCCESS if successful. XFLASH_NOT_SUPPORTED if the command is not recognized/supported by the device(s). int XFlash_Read ( XFlash InstancePtr, u32 Offset, u32 Bytes, void DestPtr ) This function reads the data from the Flash device and copies it into the specified user buffer. The source and destination addresses can be on any alignment supported by the processor. The device is polled until an error or the operation completes successfully. InstancePtr Offset Bytes DestPtr Pointer to the XFlash instance. Offset into the device(s) address space from which to read. Number of bytes to copy. Destination address to copy data to. XST_SUCCESS if successful. XFLASH_ADDRESS_ERROR if the source address does not start within the addressable areas of the device(s). This function allows the transfer of data past the end of the device's address space. If this occurs, then results are undefined. 279

280 int XFlash_Write ( XFlash InstancePtr, u32 Offset, u32 Bytes, void SrcPtr ) This function programs the flash device(s) with data specified in the user buffer. The source and destination address must be aligned to the width of the flash's data bus. The device is polled until an error or the operation completes successfully. InstancePtr Offset Bytes SrcPtr Pointer to the XFlash instance. Offset into the device(s) address space from which to begin programming. Must be aligned to the width of the flash's data bus. Number of bytes to program. Source address containing data to be programmed. Must be aligned to the width of the flash's data bus. The SrcPtr doesn't have to be aligned to the flash width if the processor supports unaligned access. But, since this library is generic, and some processors(eg. Microblaze) do not support unaligned access; this API requires the SrcPtr to be aligned. XST_SUCCESS if successful. XFLASH_ERROR if a write error occurred. This error is usually device specific. Use XFlash_DeviceControl() to retrieve specific error conditions. When this error is returned, it is possible that the target address range was only partially programmed. int XFlash_Erase ( XFlash InstancePtr, u32 Offset, u32 Bytes ) This function erases the specified address range in the flash device. The number of bytes to erase can be any number as long as it is within the bounds of the device(s). The device is polled until an error or the operation completes successfully. InstancePtr Offset Bytes Pointer to the XFlash instance. Offset into the device(s) address space from which to begin erasure. Number of bytes to erase. 280

281 XST_SUCCESS if successful. XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s). Due to flash memory design, the range actually erased may be larger than what was specified by the Offset & Bytes parameters. This will occur if the parameters do not align to block boundaries. int XFlash_Lock ( XFlash InstancePtr, u32 Offset, u32 Bytes ) This function Locks the blocks in the specified range of the flash device(s). The device is polled until an error or the operation completes successfully. InstancePtr Offset Bytes Pointer to the XFlash instance. Offset into the device(s) address space from which to begin block locking. The first three bytes of every block is reserved for special purpose. The offset should be atleast three bytes from start of the block. Number of bytes to Lock in the Block starting from Offset. XST_SUCCESS if successful. XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s). Due to flash memory design, the range actually locked may be larger than what was specified by the Offset & Bytes parameters. This will occur if the parameters do not align to block boundaries. int XFlash_Unlock ( XFlash InstancePtr, u32 Offset, u32 Bytes ) This function Unlocks the blocks in the specified range of the flash device(s). The device is polled until an error or the operation completes successfully. 281

282 InstancePtr Offset Bytes Pointer to the XFlash instance. Offset into the device(s) address space from which to begin block UnLocking. The first three bytes of every block is reserved for special purpose. The offset should be atleast three bytes from start of the block. Number of bytes to UnLock in the Block starting from Offset. XST_SUCCESS if successful. XFLASH_ADDRESS_ERROR if the destination address range is not completely within the addressable areas of the device(s). int XFlash_IsReady ( XFlash InstancePtr ) This function checks the readiness of the device, which means it has been successfully initialized. InstancePtr Pointer to the XFlash instance. TRUE if the device has been initialized (but not necessarily started), and FALSE otherwise. 282

283 Library in MSS File XilFlash Library can be integrated with a system using the following snippet in the Microprocessor Software Specification (MSS) file: BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilflash PARAMETER LIBRARY_VER = 4.3 PARAMETER PROC_INSTANCE = microblaze_0 PARAMETER ENABLE_INTEL = true PARAMETER ENABLE_AMD = false END The table below describes the libgen customization parameters. Parameter Default Value Description LIBRARY_NAME xilflash Specifies the library name. LIBRARY_VER 4.3 Specifies the library version. PROC_INSTANCE microblaze_0 Specifies the processor name. ENABLE_INTEL true/false Enables or disables the Intel flash device family. ENABLE_AMD true/false Enables or disables the AMD flash device family. 283

284 Appendix E: XilIsf Library v

285 Overview The LibXil Isf library: Allows you to Write, Read, and Erase the Serial Flash. Allows protection of the data stored in the Serial Flash from unwarranted modification by enabling the Sector Protection feature. Supports multiple instances of Serial Flash at a time, provided they are of the same device family (Atmel, Intel, STM, Winbond, SST, or Spansion) as the device family is selected at compile time. Allows the user application to perform Control operations on Intel, STM, Winbond, SST, and Spansion Serial Flash. Requires the underlying hardware platform to contain the axi_quad_spi, ps7_spi, ps7_qspi, psu_qspi or psu_spi device for accessing the Serial Flash. Uses the Xilinx SPI interface drivers in interrupt-driven mode or polled mode for communicating with the Serial Flash. In interrupt mode, the user application must acknowledge any associated interrupts from the Interrupt Controller. Additional information: In interrupt mode, the application is required to register a callback to the library and the library registers an internal status handler to the selected interface driver. When the user application requests a library operation, it is initiated and control is given back to the application. The library tracks the status of the interface transfers, and notifies the user application upon completion of the selected library operation. Added support in the library for SPI PS and QSPI PS. You must select one of the interfaces at compile time. Added support for QSPIPSU and SPIPS flash interface on Zynq UltraScale+ MPSoC. When the user application requests selection of QSPIPS interface during compilation, the QSPI PS or QSPI PSU interface, based on the hardware platform, are selected. Similarly, if the SPIPS interface is selected during compilation, SPI PS or SPI PSU interface are selected. 285

286 Supported Devices The table below lists the supported Xilinx in-system and external serial flash memories. Device Series AT45DB011D AT45DB021D AT45DB041D AT45DB081D AT45DB161D AT45DB321D AT45DB642D Manufacturer Atmel W25Q16 W25Q32 W25Q64 W25Q80 W25Q128 W25X10 W25X20 W25X40 W25X80 W25X16 W25X32 W25X64 Winbond S25FL004 S25FL008 S25FL016 S25FL032 S25FL064 S25FL128 S25FL129 S25FL256 S25FL512 S70FL01G Spansion SST25WF080 SST 286

287 Device Series N25Q032 N25Q064 N25Q128 N25Q256 N25Q512 N25Q00AA MT25Q01 MT25Q02 Manufacturer Micron Intel, STM, and Numonyx serial flash devices are now a part of Serial Flash devices provided by Micron. References Spartan-3AN FPGA In-System Flash User Guide (UG333): Atmel Serial Flash Memory website (AT45XXXD): Intel (Numonyx) S33 Serial Flash Memory website (S33): STM (Numonyx) M25PXX Serial Flash Memory website (M25PXX): M25PTechnicalDocuments.aspx Winbond Serial Flash Page: FlashMemory/SerialFlash/ Spansion website: SST SST25WF080: Micron N25Q flash family: 287

288 XilIsf Library API Overview This chapter provides a linked summary and detailed descriptions of the XilIsf library APIs. Functions int XIsf_Initialize (XIsf InstancePtr, XIsf_Iface SpiInstPtr, u8 SlaveSelect, u8 WritePtr) int XIsf_GetStatus (XIsf InstancePtr, u8 ReadPtr) int XIsf_GetStatusReg2 (XIsf InstancePtr, u8 ReadPtr) int XIsf_GetDeviceInfo (XIsf InstancePtr, u8 ReadPtr) int XIsf_Write (XIsf InstancePtr, XIsf_WriteOperation Operation, void OpParamPtr) int XIsf_Read (XIsf InstancePtr, XIsf_ReadOperation Operation, void OpParamPtr) int XIsf_Erase (XIsf InstancePtr, XIsf_EraseOperation Operation, u32 Address) int XIsf_MicronFlashEnter4BAddMode (XIsf InstancePtr) int XIsf_MicronFlashExit4BAddMode (XIsf InstancePtr) int XIsf_SectorProtect (XIsf InstancePtr, XIsf_SpOperation Operation, u8 BufferPtr) int XIsf_Ioctl (XIsf InstancePtr, XIsf_IoctlOperation Operation) int XIsf_WriteEnable (XIsf InstancePtr, u8 WriteEnable) void XIsf_RegisterInterface (XIsf InstancePtr) int XIsf_SetSpiConfiguration (XIsf InstancePtr, XIsf_Iface SpiInstPtr, u32 Options, u8 PreScaler) void XIsf_SetStatusHandler (XIsf InstancePtr, XIsf_Iface XIfaceInstancePtr, XIsf_StatusHandler XilIsf_Handler) void XIsf_IfaceHandler (void CallBackRef, u32 StatusEvent, unsigned int ByteCount) Function Documentation int XIsf_Initialize ( XIsf InstancePtr, XIsf_Iface SpiInstPtr, u8 SlaveSelect, u8 WritePtr ) This API when called initializes the SPI interface with default settings. 288

289 With custom settings, user should call XIsf_SetSpiConfiguration() and then call this API. The geometry of the underlying Serial Flash is determined by reading the Joint Electron Device Engineering Council (JEDEC) Device Information and the Status Register of the Serial Flash. InstancePtr SpiInstPtr SlaveSelect WritePtr Pointer to the XIsf instance. Pointer to XIsf_Iface instance to be worked on. It is a 32-bit mask with a 1 in the bit position of slave being selected. Only one slave can be selected at a time. Pointer to the buffer allocated by the user to be used by the In-system and Serial Flash Library to perform any read/write operations on the Serial Flash device. User applications must pass the address of this buffer for the Library to work. Write operations : The size of this buffer should be equal to the Number of bytes to be written to the Serial Flash + XISF_CMD_MAX_EXTRA_BYTES. The size of this buffer should be large enough for usage across all the applications that use a common instance of the Serial Flash. A minimum of one byte and a maximum of ISF_PAGE_SIZE bytes can be written to the Serial Flash, through a single Write operation. Read operations : The size of this buffer should be equal to XISF_CMD_MAX_EXTRA_BYTES, if the application only reads from the Serial Flash (no write operations). XST_SUCCESS if successful. XST_DEVICE_IS_STOPPED if the device must be started before transferring data. XST_FAILURE, otherwise. The XIsf_Initialize() API is a blocking call (for both polled and interrupt modes of the Spi driver). It reads the JEDEC information of the device and waits till the transfer is complete before checking if the information is valid. This library can support multiple instances of Serial Flash at a time, provided they are of the same device family (either Atmel, Intel or STM, Winbond or Spansion) as the device family is selected at compile time. 289

290 int XIsf_GetStatus ( XIsf InstancePtr, u8 ReadPtr ) This API reads the Serial Flash Status Register. InstancePtr ReadPtr Pointer to the XIsf instance. Pointer to the memory where the Status Register content is copied. XST_SUCCESS if successful else XST_FAILURE. The contents of the Status Register is stored at second byte pointed by the ReadPtr. int XIsf_GetStatusReg2 ( XIsf InstancePtr, u8 ReadPtr ) This API reads the Serial Flash Status Register 2. InstancePtr ReadPtr Pointer to the XIsf instance. Pointer to the memory where the Status Register content is copied. XST_SUCCESS if successful else XST_FAILURE. The contents of the Status Register 2 is stored at the second byte pointed by the ReadPtr. This operation is available only in Winbond Serial Flash. int XIsf_GetDeviceInfo ( XIsf InstancePtr, u8 ReadPtr ) This API reads the Joint Electron Device Engineering Council (JEDEC) information of the Serial Flash. InstancePtr ReadPtr Pointer to the XIsf instance. Pointer to the buffer where the Device information is copied. 290

291 XST_SUCCESS if successful else XST_FAILURE. The Device information is stored at the second byte pointed by the ReadPtr. int XIsf_Write ( XIsf InstancePtr, XIsf_WriteOperation Operation, void OpParamPtr ) This API writes the data to the Serial Flash. InstancePtr Operation Pointer to the XIsf instance. Type of write operation to be performed on the Serial Flash. The different operations are XISF_WRITE: Normal Write XISF_DUAL_IP_PAGE_WRITE: Dual Input Fast Program XISF_DUAL_IP_EXT_PAGE_WRITE: Dual Input Extended Fast Program XISF_QUAD_IP_PAGE_WRITE: Quad Input Fast Program XISF_QUAD_IP_EXT_PAGE_WRITE: Quad Input Extended Fast Program XISF_AUTO_PAGE_WRITE: Auto Page Write XISF_BUFFER_WRITE: Buffer Write XISF_BUF_TO_PAGE_WRITE_WITH_ERASE: Buffer to Page Transfer with Erase XISF_BUF_TO_PAGE_WRITE_WITHOUT_ERASE: Buffer to Page Transfer without Erase XISF_WRITE_STATUS_REG: Status Register Write XISF_WRITE_STATUS_REG2: 2 byte Status Register Write XISF_OTP_WRITE: OTP Write. OpParamPtr Pointer to a structure variable which contains operational parameters of the specified operation. This parameter type is dependant on value of first argument(operation). For more details, refer Operations. 291

292 Operations Normal Write(XISF_WRITE), Dual Input Fast Program (XISF_DUAL_IP_PAGE_WRITE), Dual Input Extended Fast Program(XISF_DUAL_IP_EXT_PAGE_WRITE), Quad Input Fast Program(XISF_QUAD_IP_PAGE_WRITE), Quad Input Extended Fast Program (XISF_QUAD_IP_EXT_PAGE_WRITE): The OpParamPtr must be of type struct XIsf_WriteParam. OpParamPtr->Address is the start address in the Serial Flash. OpParamPtr->WritePtr is a pointer to the data to be written to the Serial Flash. OpParamPtr->NumBytes is the number of bytes to be written to Serial Flash. This operation is supported for Atmel, Intel, STM, Winbond and Spansion Serial Flash. Auto Page Write (XISF_AUTO_PAGE_WRITE): The OpParamPtr must be of 32 bit unsigned integer variable. This is the address of page number in the Serial Flash which is to be refreshed. This operation is only supported for Atmel Serial Flash. Buffer Write (XISF_BUFFER_WRITE): The OpParamPtr must be of type struct XIsf_BufferToFlashWriteParam. OpParamPtr->BufferNum specifies the internal SRAM Buffer of the Serial Flash. The valid values are XISF_PAGE_BUFFER1 or XISF_PAGE_BUFFER2. XISF_PAGE_BUFFER2 is not valid in case of AT45DB011D Flash as it contains a single buffer. OpParamPtr->WritePtr is a pointer to the data to be written to the Serial Flash SRAM Buffer. OpParamPtr->ByteOffset is byte offset in the buffer from where the data is to be written. OpParamPtr->NumBytes is number of bytes to be written to the Buffer. This operation is supported only for Atmel Serial Flash. Buffer To Memory Write With Erase (XISF_BUF_TO_PAGE_WRITE_WITH_ERASE)/ Buffer To Memory Write Without Erase (XISF_BUF_TO_PAGE_WRITE_WITHOUT_ERASE): The OpParamPtr must be of type struct XIsf_BufferToFlashWriteParam. OpParamPtr->BufferNum specifies the internal SRAM Buffer of the Serial Flash. The valid values are XISF_PAGE_BUFFER1 or XISF_PAGE_BUFFER2. XISF_PAGE_BUFFER2 is not valid in case of AT45DB011D Flash as it contains a single buffer. OpParamPtr->Address is starting address in the Serial Flash memory from where the data is to be written. These operations are only supported for Atmel Serial Flash. Write Status Register (XISF_WRITE_STATUS_REG): The OpParamPtr must be of type of 8 bit unsigned integer variable. This is the value to be written to the Status Register. This operation is only supported for Intel, STM Winbond and Spansion Serial Flash. Write Status Register2 (XISF_WRITE_STATUS_REG2): 292

293 The OpParamPtr must be of type (u8 ) and should point to two 8 bit unsigned integer values. This is the value to be written to the 16 bit Status Register. This operation is only supported in Winbond (W25Q) Serial Flash. One Time Programmable Area Write(XISF_OTP_WRITE): The OpParamPtr must be of type struct XIsf_WriteParam. OpParamPtr->Address is the address in the SRAM Buffer of the Serial Flash to which the data is to be written. OpParamPtr->WritePtr is a pointer to the data to be written to the Serial Flash. OpParamPtr->NumBytes should be set to 1 when performing OTPWrite operation. This operation is only supported for Intel Serial Flash. XST_SUCCESS if successful else XST_FAILURE. Application must fill the structure elements of the third argument and pass its pointer by type casting it with void pointer. For Intel, STM, Winbond and Spansion Serial Flash, the user application must call the XIsf_WriteEnable() API by passing XISF_WRITE_ENABLE as an argument, before calling the XIsf_Write() API. 293

294 int XIsf_Read ( XIsf InstancePtr, XIsf_ReadOperation Operation, void OpParamPtr ) This API reads the data from the Serial Flash. InstancePtr Operation Pointer to the XIsf instance. Type of the read operation to be performed on the Serial Flash. The different operations are XISF_READ: Normal Read XISF_FAST_READ: Fast Read XISF_PAGE_TO_BUF_TRANS: Page to Buffer Transfer XISF_BUFFER_READ: Buffer Read XISF_FAST_BUFFER_READ: Fast Buffer Read XISF_OTP_READ: One Time Programmable Area (OTP) Read XISF_DUAL_OP_FAST_READ: Dual Output Fast Read XISF_DUAL_IO_FAST_READ: Dual Input/Output Fast Read XISF_QUAD_OP_FAST_READ: Quad Output Fast Read XISF_QUAD_IO_FAST_READ: Quad Input/Output Fast Read OpParamPtr Pointer to structure variable which contains operational parameter of specified Operation. This parameter type is dependant on the type of Operation to be performed. For more details, refer Operations. Operations Normal Read (XISF_READ), Fast Read (XISF_FAST_READ), One Time Programmable Area Read(XISF_OTP_READ), Dual Output Fast Read (XISF_CMD_DUAL_OP_FAST_READ), Dual Input/Output Fast Read (XISF_CMD_DUAL_IO_FAST_READ), Quad Output Fast Read (XISF_CMD_QUAD_OP_FAST_READ) and Quad Input/Output Fast Read (XISF_CMD_QUAD_IO_FAST_READ): The OpParamPtr must be of type struct XIsf_ReadParam. OpParamPtr->Address is start address in the Serial Flash. OpParamPtr->ReadPtr is a pointer to the memory where the data read from the Serial Flash is stored. OpParamPtr->NumBytes is number of bytes to read. OpParamPtr->NumDummyBytes is the number of dummy bytes to be transmitted for the Read command. This parameter is only used in case of Dual and Quad reads. 294

295 Normal Read and Fast Read operations are supported for Atmel, Intel, STM, Winbond and Spansion Serial Flash. Dual and quad reads are supported for Winbond (W25QXX), Numonyx(N25QXX) and Spansion (S25FL129) quad flash. OTP Read operation is only supported in Intel Serial Flash. Page To Buffer Transfer (XISF_PAGE_TO_BUF_TRANS): The OpParamPtr must be of type struct XIsf_FlashToBufTransferParam. OpParamPtr->BufferNum specifies the internal SRAM Buffer of the Serial Flash. The valid values are XISF_PAGE_BUFFER1 or XISF_PAGE_BUFFER2. XISF_PAGE_BUFFER2 is not valid in case of AT45DB011D Flash as it contains a single buffer. OpParamPtr->Address is start address in the Serial Flash. This operation is only supported in Atmel Serial Flash. Buffer Read (XISF_BUFFER_READ) and Fast Buffer Read(XISF_FAST_BUFFER_READ): The OpParamPtr must be of type struct XIsf_BufferReadParam. OpParamPtr->BufferNum specifies the internal SRAM Buffer of the Serial Flash. The valid values are XISF_PAGE_BUFFER1 or XISF_PAGE_BUFFER2. XISF_PAGE_BUFFER2 is not valid in case of AT45DB011D Flash as it contains a single buffer. OpParamPtr->ReadPtr is pointer to the memory where data read from the SRAM buffer is to be stored. OpParamPtr->ByteOffset is byte offset in the SRAM buffer from where the first byte is read. OpParamPtr->NumBytes is the number of bytes to be read from the Buffer. These operations are supported only in Atmel Serial Flash. XST_SUCCESS if successful else XST_FAILURE. Application must fill the structure elements of the third argument and pass its pointer by type casting it with void pointer. The valid data is available from the fourth location pointed to by the ReadPtr for Normal Read and Buffer Read operations. The valid data is available from fifth location pointed to by the ReadPtr for Fast Read, Fast Buffer Read and OTP Read operations. The valid data is available from the (4 + NumDummyBytes)th location pointed to by ReadPtr for Dual/Quad Read operations. 295

296 int XIsf_Erase ( XIsf InstancePtr, XIsf_EraseOperation Operation, u32 Address ) This API erases the contents of the specified memory in the Serial Flash. InstancePtr Operation Pointer to the XIsf instance. Type of Erase operation to be performed on the Serial Flash. The different operations are XISF_PAGE_ERASE: Page Erase XISF_BLOCK_ERASE: Block Erase XISF_SECTOR_ERASE: Sector Erase XISF_BULK_ERASE: Bulk Erase Address Address of the Page/Block/Sector to be erased. The address can be either Page address, Block address or Sector address based on the Erase operation to be performed. XST_SUCCESS if successful else XST_FAILURE. The erased bytes will read as 0xFF. For Intel, STM, Winbond or Spansion Serial Flash the user application must call XIsf_WriteEnable() API by passing XISF_WRITE_ENABLE as an argument before calling XIsf_Erase() API. Atmel Serial Flash support Page/Block/Sector Erase operations. Intel, Winbond, Numonyx (N25QXX) and Spansion Serial Flash support Sector/Block/Bulk Erase operations. STM (M25PXX) Serial Flash support Sector/Bulk Erase operations. int XIsf_MicronFlashEnter4BAddMode ( XIsf InstancePtr ) This API enters the Micron flash device into 4 bytes addressing mode. As per the Micron spec, before issuing the command to enter into 4 byte addr mode, a write enable command is issued. 296

297 InstancePtr Pointer to the XIsf instance. XST_SUCCESS if successful. XST_FAILURE if it fails. Applicable only for Micron flash devices int XIsf_MicronFlashExit4BAddMode ( XIsf InstancePtr ) This API exits the Micron flash device from 4 bytes addressing mode. As per the Micron spec, before issuing this command a write enable command is first issued. InstancePtr Pointer to the XIsf instance. XST_SUCCESS if successful. XST_FAILURE if it fails. Applicable only for Micron flash devices int XIsf_SectorProtect ( XIsf InstancePtr, XIsf_SpOperation Operation, u8 BufferPtr ) This API is used for performing Sector Protect related operations. 297

298 InstancePtr Operation Pointer to the XIsf instance. Type of Sector Protect operation to be performed on the Serial Flash. The different operations are XISF_SPR_READ: Read Sector Protection Register XISF_SPR_WRITE: Write Sector Protection Register XISF_SPR_ERASE: Erase Sector Protection Register XISF_SP_ENABLE: Enable Sector Protection XISF_SP_DISABLE: Disable Sector Protection BufferPtr Pointer to the memory where the SPR content is read to/written from. This argument can be NULL if the Operation is SprErase, SpEnable and SpDisable. XST_SUCCESS if successful else XST_FAILURE. The SPR content is stored at the fourth location pointed by the BufferPtr when performing XISF_SPR_READ operation. For Intel, STM, Winbond and Spansion Serial Flash, the user application must call the XIsf_WriteEnable() API by passing XISF_WRITE_ENABLE as an argument, before calling the XIsf_SectorProtect() API, for Sector Protect Register Write (XISF_SPR_WRITE) operation. Atmel Flash supports all these Sector Protect operations. Intel, STM, Winbond and Spansion Flash support only Sector Protect Read and Sector Protect Write operations. int XIsf_Ioctl ( XIsf InstancePtr, XIsf_IoctlOperation Operation ) This API configures and controls the Intel, STM, Winbond and Spansion Serial Flash. 298

299 InstancePtr Operation Pointer to the XIsf instance. Type of Control operation to be performed on the Serial Flash. The different control operations are XISF_RELEASE_DPD: Release from Deep Power Down (DPD) Mode XISF_ENTER_DPD: Enter DPD Mode XISF_CLEAR_SR_FAIL_FLAGS: Clear Status Register Fail Flags XST_SUCCESS if successful else XST_FAILURE. Atmel Serial Flash does not support any of these operations. Intel Serial Flash support Enter/Release from DPD Mode and Clear Status Register Fail Flags. STM, Winbond and Spansion Serial Flash support Enter/Release from DPD Mode. Winbond (W25QXX) Serial Flash support Enable High Performance mode. int XIsf_WriteEnable ( XIsf InstancePtr, u8 WriteEnable ) This API Enables/Disables writes to the Intel, STM, Winbond and Spansion Serial Flash. InstancePtr WriteEnable Pointer to the XIsf instance. Specifies whether to Enable (XISF_CMD_ENABLE_WRITE) or Disable (XISF_CMD_DISABLE_WRITE) the writes to the Serial Flash. XST_SUCCESS if successful else XST_FAILURE. This API works only for Intel, STM, Winbond and Spansion Serial Flash. If this API is called for Atmel Flash, XST_FAILURE is returned. 299

300 void XIsf_RegisterInterface ( XIsf InstancePtr ) This API registers the interface SPI/SPI PS/QSPI PS. InstancePtr Pointer to the XIsf instance. None int XIsf_SetSpiConfiguration ( XIsf InstancePtr, XIsf_Iface SpiInstPtr, u32 Options, u8 PreScaler ) This API sets the configuration of SPI. This will set the options and clock prescaler (if applicable). InstancePtr SpiInstPtr Options PreScaler Pointer to the XIsf instance. Pointer to XIsf_Iface instance to be worked on. Specified options to be set. Value of the clock prescaler to set. XST_SUCCESS if successful else XST_FAILURE. This API can be called before calling XIsf_Initialize() to initialize the SPI interface in other than default options mode. PreScaler is only applicable to PS SPI/QSPI. void XIsf_SetStatusHandler ( XIsf InstancePtr, XIsf_Iface XIfaceInstancePtr, XIsf_StatusHandler XilIsf_Handler ) This API is to set the Status Handler when an interrupt is registered. InstancePtr QspiInstancePtr XilIsf_Handler Pointer to the XIsf Instance. Pointer to the XIsf_Iface instance to be worked on. Status handler for the application. 300

301 None void XIsf_IfaceHandler ( void CallBackRef, u32 StatusEvent, unsigned int ByteCount ) This API is the handler which performs processing for the QSPI driver. It is called from an interrupt context such that the amount of processing performed should be minimized. It is called when a transfer of QSPI data completes or an error occurs. This handler provides an example of how to handle QSPI interrupts but is application specific. CallBackRef Reference passed to the handler. StatusEvent Status of the QSPI. ByteCount Number of bytes transferred. None 301

302 Library in MSS File XilIsf Library can be integrated with a system using the following snippet in the Microprocessor Software Specification (MSS) file: BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilisf PARAMETER LIBRARY_VER = 5.8 PARAMETER serial_flash_family = 1 PARAMETER serial_flash_interface = 1 END The table below describes the libgen customization parameters. Parameter Default Value Description LIBRARY_NAME xilisf Specifies the library name. LIBRARY_VER 5.8 Specifies the library version. serial_flash_family 1 Specifies the serial flash family. Supported numerical values are: 1 = Xilinx In-system Flash or Atmel Serial Flash 2 = Intel (Numonyx) S33 Serial Flash 3 = STM (Numonyx) M25PXX/N25QXX Serial Flash 4 = Winbond Serial Flash 5 = Spansion Serial Flash/Micron Serial Flash 6 = SST Serial Flash Serial_flash_interface 1 Specifies the serial flash interface. Supported numerical values are: 1 = AXI QSPI Interface 2 = SPI PS Interface 3 = QSPI PS Interface or QSPI PSU Interface 302

303 Intel, STM, and Numonyx serial flash devices are now a part of Serial Flash devices provided by Micron. 303

304 Appendix F: XilFFS Library Reference

305 Overview The LibXil fat file system (FFS) library consists of a file system and a glue layer. This FAT file system can be used with an interface supported in the glue layer. The file system code is open source and is used as it is. Glue layer implementation supports SD/eMMC interface presently. Application should make use of APIs provided in ff.h. These file system APIs access the driver functions through the glue layer. File System Files The table below describes the file system files. File ff.c ff.h ffconf.h integer.h Description Implements all the file system APIs File system header File system configuration header File system configurations such as READ_ONLY, MINIMAL. can be set here. This library uses _FS_MINIMIZE and _FS_TINY and Read/Write (NOT read only) Contains type definitions used by file system 305

306 Glue Layer Files The table below describes the glue layer files. File diskio.c diskio.h Description Glue layer implements the function used by file system to call the driver APIs Glue layer header Selecting a File System with an SD Interface To select a file system with an SD interface: 1. Launch Xilinx SDK and create a new bsp 2. Select the xilffs library. 3. In xilffs options, set fs_interface = 1 to select SD/eMMC. This is the default value. When this option is set, ensure that an SD/eMMC interface is available. 4. Build the bsp and application to use the file system with SD/eMMC. 5. SD or emmc will be recognized by the low level driver. Library in MSS File XilFFS Library can be integrated with a system using the following snippet in the Microprocessor Software Specification (MSS) file: parameter LIBRARY_NAME = xilffs parameter LIBRARY_VER = 3.6 parameter fs_interface = 1 parameter read_only = false parameter use_lfn = false parameter enable_multi_partition = false parameter num_logical_vol = 2 parameter use_mkfs = true The table below describes the libgen customization parameters. Parameter LIBRARY_NAME LIBRARY_VER fs_interface Description Specifies the library name. Specifies the library version. File system interface. Currently SD/eMMC is the only interface supported. Default is

307 Parameter read_only use_lfn enable_multi_partition num_logical_vol use_mkfs Description Enables the file system in Read Only mode, if true. Default is false. Zynq UltraScale+ MPSoC fsbl sets this option as true. Enables the long file name (LFN) support, if true. Default is false. Enables the multi partition support, if true. Default is false. Number of volumes (logical drives, from 1 to 10) to be used. Default is 2 Enables the mkfs support, if true. Default is true. For Zynq UltraScale+ MPSOC fsbl, set this option as false. File System The file system supports FAT16 and FAT32. The APIs are standard file system APIs. A detailed description can be found at Revision R0.10b is used in the library. 307

308 Appendix G: XilRSA Library v

309 Overview The XilRSA library provides APIs to use RSA encryption and decryption algorithms and SHA algorithms for Zynq All Programmable SoC devices. The RSA-2048 bit is used for RSA and the SHA-256 bit is used for hash. For an example on usage of this library, refer to the RSA Authentication application and its documentation. Source Files The following is a list of source files shipped as a part of the XilRSA library: librsa.a: Pre-compiled file which contains the implementation. xilrsa.h: This file contains the APIs for SHA2 and RSA Usage of SHA-256 Functions When all the data is available on which sha2 must be calculated, the sha_256() function can be used with appropriate parameters, as described. When all the data is not available on which sha2 must be calculated, use the sha2 functions in the following order: 1. sha2_update() can be called multiple times till input data is completed. 2. sha2_context is updated by the library only; do not change the values of the context. SHA2 API Example Usage sha2_context ctx; sha2_starts(&ctx); sha2_update(&ctx, (unsigned char *)in, size); sha2_finish(&ctx, out); Following is the source code of the sha2_context class. typedef struct { unsigned int state[8]; unsigned char buffer[sha_blkbytes]; unsigned long long bytes; } sha2_context; 309

310 XilRSA APIs Overview This section provides detailed descriptions of the XilRSA library APIs. Functions void rsa2048_exp (const unsigned char base, const unsigned char modular, const unsigned char modular_ext, const unsigned char exponent, unsigned char result) void rsa2048_pubexp (RSA_NUMBER a, RSA_NUMBER x, unsigned long e, RSA_NUMBER m, RSA_NUMBER rrm) void sha_256 (const unsigned char in, const unsigned int size, unsigned char out) void sha2_starts (sha2_context ctx) void sha2_update (sha2_context ctx, unsigned char input, unsigned int ilen) void sha2_finish (sha2_context ctx, unsigned char output) Function Documentation void rsa2048_exp ( const unsigned char base, const unsigned char modular, const unsigned char modular_ext, const unsigned char exponent, unsigned char result ) This function is used to encrypt the data using 2048 bit private key. modular modular_ext exponent result A char pointer which contains the key modulus A char pointer which contains the key modulus extension A char pointer which contains the private key exponent A char pointer which contains the encrypted data 310

311 None void rsa2048_pubexp ( RSA_NUMBER a, RSA_NUMBER x, unsigned long e, RSA_NUMBER m, RSA_NUMBER rrm ) This function is used to decrypt the data using 2048 bit public key. a x e m rrm RSA_NUMBER containing the decrypted data. RSA_NUMBER containing the input data Unsigned number containing the public key exponent RSA_NUMBER containing the public key modulus RSA_NUMBER containing the public key modulus extension. None void sha_256 ( const unsigned char in, const unsigned int size, unsigned char out ) This function calculates the hash for the input data using SHA-256 algorithm. This function internally calls the sha2_init, updates and finishes functions and updates the result. In Size Out Char pointer which contains the input data. Length of the input data Pointer to location where resulting hash will be written. None void sha2_starts ( sha2_context ctx ) This function initializes the SHA2 context. 311

312 ctx Pointer to sha2_context structure that stores status and buffer. None void sha2_update ( sha2_context ctx, unsigned char input, unsigned int ilen ) This function adds the input data to SHA256 calculation. ctx input Out Pointer to sha2_context structure that stores status and buffer. Pointer to the data to add. Length of the input data. None void sha2_finish ( sha2_context ctx, unsigned char output ) This function finishes the SHA calculation. ctx output Pointer to sha2_context structure that stores status and buffer. Pointer to the calculated hash data. None 312

313 Appendix H: XilSKey Library v

314 Overview The XilSKey library provides APIs for programming and reading efuse bits and for programming the battery-backed RAM (BBRAM) of Zynq All Programmable SoC, UltraScale and the Zynq UltraScale+ MPSoC devices. In Zynq-7000 devices: PS efuse holds the RSA primary key hash bits and user feature bits, which can enable or disable some Zynq-7000 processor features. PL efuse holds the AES key, the user key and some of the feature bits. PL BBRAM holds the AES key. In UltraScale: PL efuse holds the AES key, 32 bit and 128 bit user key, RSA hash and some of the feature bits. PL BBRAM holds AES key with or without DPA protection enable or obfuscated key programming. In Zynq UltraScale+ MPSoC: PS efuse holds the AES key, the user fuses, PPK0 and PPK1 hash, SPK ID and some user feature bits which can be used to enable or disable some Zynq UltraScale+ MPSoC features. BBRAM holds the AES key. Hardware Setup This section describes the hardware setup required for programming PL BBRAM or PL efuse. Hardware setup for Zynq PL This chapter describes the hardware setup required for programming BBRAM or efuse of Zynq PL devices. PL efuse or PL BBRAM is accessed through PS via MIO pins which are used for communication PL efuse or PL BBRAM through JTAG signals, these can be changed depending on the hardware setup. A hardware setup which dedicates four MIO pins for JTAG signals should be used and the MIO pins should be mentioned in application header file (xilskey_input.h). There should be a method to download this example and have the MIO pins connected to JTAG before running this application. You can change the listed pins at your discretion. 314

315 MUX Usage Requirements To write the PL efuse or PL BBRAM using a driver you must: Use four MIO lines (TCK,TMS,TDO,TDI) Connect the MIO lines to a JTAG port If you want to switch between the external JTAG and JTAG operation driven by the MIOs, you must: Include a MUX between the external JTAG and the JTAG operation driven by the MIOs Assign a MUX selection PIN To rephrase, to select JTAG for PL EFUSE or PL BBRAM writing, you must define the following: The MIOs used for JTAG operations (TCK,TMS,TDI,TDO). The MIO used for the MUX Select Line. The Value on the MUX Select line, to select JTAG for PL efuse or PL BBRAM writing. The following graphic illustrates the correct MUX usage. Figure 19.1: MUX Usage If you use the Vivado Device Programmer tool to burn PL efuses, there is no need for MUX circuitry or MIO pins. 315

316 Hardware setup for UltraScale This chapter describes the hardware setup required for programming BBRAM or efuse of UltraScale devices. Accessing UltraScale MicroBlaze efuse is done by using block RAM initialization. UltraScale efuse programming is done through MASTER JTAG. Crucial Programming sequence will be taken care by Hardware module. It is mandatory to add Hardware module in the design. Use hardware module's vhd code and instructions provided to add Hardware module in the design. You need to add the Master JTAG primitive to design, that is, the MASTER_JTAG_inst instantiation has to be performed and AXI GPIO pins have to be connected to TDO, TDI, TMS and TCK signals of the MASTER_JTAG primitive. For programming efuse, along with master JTAG, hardware module(hwm) has to be added in design and it's signals XSK_EFUSEPL_AXI_GPIO_HWM_READY, XSK_EFUSEPL_AXI_GPIO_HWM_END and XSK_EFUSEPL_AXI_GPIO_HWM_START, needs to be connected to AXI GPIO pins to communicate with HWM. Hardware module is not mandatory for programming BBRAM. If your design has a HWM, it is not harmful for accessing BBRAM. All inputs (Master JTAG's TDO and HWM's HWM_READY, HWM_END) and all outputs (Master JTAG TDI, TMS, TCK and HWM's HWM_START) can be connected in one channel (or) inputs in one channel and outputs in other channel. Some of the outputs of GPIO in one channel and some others in different channels are not supported. The design should contain AXI BRAM control memory mapped (1MB). MASTER_JTAG will disable all other JTAGs. For providing inputs of MASTER JTAG signals and HWM signals connected to the GPIO pins and GPIO channels, refer GPIO Pins Used for PL Master JTAG Signal and GPIO Channels sections of the UltraScale User-Configurable PL efuse and UltraScale User-Configurable PL BBRAM. The procedure for programming BBRAM of efuse of UltraScale can be referred at UltraScale BBRAM Access Procedure and UltraScale efuse Access Procedure. Source Files The following is a list of efuse and BBRAM application project files, folders and macros. xilskey_efuse_example.c: This file contains the main application code. The file helps in the PS/PL structure initialization and writes/reads the PS/PL efuse based on the user settings provided in the xilskey_input.h file. xilskey_input.h: This file ontains all the actions that are supported by the efuse library. Using the preprocessor directives given in the file, you can read/write the bits in the PS/PL efuse. More explanation of each directive is provided in the following sections. Burning or reading the PS/PL efuse bits is based on the values set in the xilskey_input.h file. Also contains GPIO pins and channels connected to MASTER JTAG primitive and hardware module to access Ultrascale efuse. In this file: 316

317 specify the 256 bit key to be programmed into BBRAM. specify the AES(256 bit) key, User (32 bit and 128 bit) keys and RSA key hash(384 bit) key to be programmed into UltraScale efuse. XSK_EFUSEPS_DRIVER: Define to enable the writing and reading of PS efuse. XSK_EFUSEPL_DRIVER: Define to enable the writing of PL efuse. xilskey_bbram_example.c: This file contains the example to program a key into BBRAM and verify the key. This algorithm only works when programming and verifying key are both executed in the recommended order. xilskey_efuseps_zynqmp_example.c: This file contains the example code to program the PS efuse and read back of efuse bits from the cache. xilskey_efuseps_zynqmp_input.h: This file contains all the inputs supported for efuse PS of Zynq UltraScale+ MPSoC. efuse bits are programmed based on the inputs from the xilskey_efuseps_zynqmp_input.h file. xilskey_bbramps_zynqmp_example.c: This file contains the example code to program and verify BBRAM key. Default is zero. You can modify this key on top of the file. xilskey_bbram_ultrascale_example.c: This file contains example code to program and verify BBRAM key of UltraScale. Programming and verification of BBRAM key cannot be done separately. xilskey_bbram_ultrascale_input.h: This file contains all the preprocessor directives you need to provide. In this file, specify BBRAM AES key or Obfuscated AES key to be programmed, DPA protection enable and, GPIO pins and channels connected to MASTER JTAG primitive. xilskey_puf_registration.c: This file contains all the PUF related code. This example illustrates PUF registration and generating black key and programming efuse with PUF helper data, CHash and Auxilary data along with the Black key. xilskey_puf_registration.h: This file contains all the preprocessor directives based on which read/write the efuse bits and Syndrome data generation. More explanation of each directive is provided in the following sections. WARNING: Ensure that you enter the correct information before writing or 'burning' efuse bits. Once burned, they cannot be changed. The BBRAM key can be programmed any number of times. POR reset is required for the efuse values to be recognized. 317

318 BBRAM PL API Overview This chapter provides a linked summary and detailed descriptions of the battery-backed RAM (BBRAM) APIs of Zynq PL and UltraScale devices. Example Usage Zynq BBRAM PL example usage: The Zynq BBRAM PL example application should contain the xilskey_bbram_example.c and xilskey_input.h files. You should provide user configurable parameters in the xilskey_input.h file. information, refer Zynq User-Configurable PL BBRAM. UltraScale BBRAM example usage: For more The UltraScale BBRAM example application should contain the xilskey_bbram_ultrascale_input.h and xilskey_bbram_ultrascale_example.c files. You should provide user configurable parameters in the xilskey_bbram_ultrascale_input.h file. For more information, refer UltraScale User-Configurable BBRAM PL. It is assumed that you have set up your hardware prior to working on the example application. For more information, refer Hardware Setup. 318

319 Functions int XilSKey_Bbram_Program (XilSKey_Bbram InstancePtr) Function Documentation int XilSKey_Bbram_Program ( XilSKey_Bbram InstancePtr ) This function implements the BBRAM algorithm for programming and verifying key. The program and verify will only work together in and in that order. InstancePtr Pointer to XilSKey_Bbram XST_FAILURE - In case of failure XST_SUCCESS - In case of Success This function will program BBRAM of Ultrascale and Zynq as well. 319

320 Zynq UltraScale+ MPSoC BBRAM PS API Overview This chapter provides a linked summary and detailed descriptions of the battery-backed RAM (BBRAM) APIs for Zynq UltraScale+ MPSoC devices. Example Usage The Zynq UltraScale+ MPSoc example application should contain the xilskey_bbramps_zynqmp_example.c file. User configurable key can be modified in the same file (xilskey_bbramps_zynqmp_example.c), at the XSK_ZYNQMP_BBRAMPS_AES_KEY macro. Functions u32 XilSKey_ZynqMp_Bbram_Program (u32 AesKey) void XilSKey_ZynqMp_Bbram_Zeroise () Function Documentation u32 XilSKey_ZynqMp_Bbram_Program ( u32 AesKey ) This function implements the BBRAM programming and verifying the key written. Program and verification of AES will work only together. CRC of the provided key will be calculated internally and verified. AesKey Pointer to the key which has to be programmed. 320

321 Error code from XskZynqMp_Ps_Bbram_ErrorCodes enum if it fails XST_SUCCESS if programming is done. void XilSKey_ZynqMp_Bbram_Zeroise ( ) This function zeroize's Bbram Key. BBRAM key will be zeroized. 321

322 Zynq efuse PS API Overview This chapter provides a linked summary and detailed descriptions of the Zynq efuse PS APIs. Example Usage The Zynq efuse PS example application should contain the xilskey_efuse_example.c and the xilskey_input.h files. There is no need of any hardware setup. By default, both the efuse PS and PL are enabled in the application. You can comment 'XSK_EFUSEPL_DRIVER' to execute only the PS. For more details, refer Zynq User-Configurable PS efuse. Functions u32 XilSKey_EfusePs_Write (XilSKey_EPs PsInstancePtr) u32 XilSKey_EfusePs_Read (XilSKey_EPs PsInstancePtr) u32 XilSKey_EfusePs_ReadStatus (XilSKey_EPs InstancePtr, u32 StatusBits) Function Documentation u32 XilSKey_EfusePs_Write ( XilSKey_EPs InstancePtr ) PS efuse interface functions. PS efuse interface functions. InstancePtr Pointer to the PsEfuseHandle which describes which PS efuse bit should be burned. 322

323 XST_SUCCESS. Incase of error, value is as defined in xilskey_utils.h Error value is a combination of Upper 8 bit value and Lower 8 bit value. For example, 0x8A03 should be checked in error.h as 0x8A00 and 0x03. Upper 8 bit value signifies the major error and lower 8 bit values tells more precisely. When called, this API Initializes the timer, XADC subsystems. Unlocks the PS efuse controller. Configures the PS efuse controller. Writes the hash and control bits if requested. Programs the PS efuse to enable the RSA authentication if requested. Locks the PS efuse controller. an error if: The reference clock frequency is not in between 20 and 60 MHz The system not in a position to write the requested PS efuse bits (because the bits are already written or not allowed to write) The temperature and voltage are not within range u32 XilSKey_EfusePs_Read ( XilSKey_EPs InstancePtr ) This function is used to read the PS efuse. InstancePtr Pointer to the PsEfuseHandle which describes which PS efuse should be burned. XST_SUCCESS no errors occured. Incase of error, value is as defined in xilskey_utils.h. Error value is a combination of Upper 8 bit value and Lower 8 bit value. For example, 0x8A03 should be checked in error.h as 0x8A00 and 0x03. Upper 8 bit value signifies the major error and lower 8 bit values tells more precisely. When called: This API initializes the timer, XADC subsystems. Unlocks the PS efuse Controller. Configures the PS efuse Controller and enables read-only mode. Reads the PS efuse (Hash Value), and enables read-only mode. Locks the PS efuse Controller. error if: The reference clock frequency is not in between 20 and 60MHz. Unable to unlock PS efuse controller or requested address corresponds to restricted bits. Temperature and voltage are not within range u32 XilSKey_EfusePs_ReadStatus ( XilSKey_EPs InstancePtr, u32 StatusBits ) This function is used to read the PS efuse status register. 323

324 InstancePtr StatusBits Pointer to the PS efuse instance. Buffer to store the status register read. XST_SUCCESS. XST_FAILURE This API unlocks the controller and reads the Zynq PS efuse status register. 324

325 Zynq UltraScale+ MPSoC efuse PS API Overview This chapter provides a linked summary and detailed descriptions of the Zynq MPSoC UltraScale+ efuse PS APIs. Example Usage For programming efuse other than PUF, the Zynq UltraScale+ MPSoC example application should contain the xilskey_efuseps_zynqmp_example.c and the xilskey_efuseps_zynqmp_input.h files. For PUF registration and programming PUF, the the Zynq UltraScale+ MPSoC example application should contain the xilskey_puf_registration.c and the xilskey_puf_registration.h files. For more details on the user configurable parameters, refer Zynq UltraScale+ MPSoC User-Configurable PS efuse and Zynq UltraScale+ MPSoC User-Configurable PS PUF. Functions u32 XilSKey_ZynqMp_EfusePs_CheckAesKeyCrc (u32 CrcValue) u32 XilSKey_ZynqMp_EfusePs_ReadUserFuse (u32 UseFusePtr, u8 UserFuse_Num, u8 ReadOption) u32 XilSKey_ZynqMp_EfusePs_ReadPpk0Hash (u32 Ppk0Hash, u8 ReadOption) u32 XilSKey_ZynqMp_EfusePs_ReadPpk1Hash (u32 Ppk1Hash, u8 ReadOption) u32 XilSKey_ZynqMp_EfusePs_ReadSpkId (u32 SpkId, u8 ReadOption) void XilSKey_ZynqMp_EfusePs_ReadDna (u32 DnaRead) u32 XilSKey_ZynqMp_EfusePs_ReadSecCtrlBits (XilSKey_SecCtrlBits ReadBackSecCtrlBits, u8 ReadOption) u32 XilSKey_ZynqMp_EfusePs_Write (XilSKey_ZynqMpEPs InstancePtr) u32 XilSKey_ZynqMp_EfusePs_WritePufHelprData (XilSKey_Puf InstancePtr) u32 XilSKey_ZynqMp_EfusePs_ReadPufHelprData (u32 Address) u32 XilSKey_ZynqMp_EfusePs_WritePufChash (XilSKey_Puf InstancePtr) u32 XilSKey_ZynqMp_EfusePs_ReadPufChash (u32 Address, u8 ReadOption) u32 XilSKey_ZynqMp_EfusePs_WritePufAux (XilSKey_Puf InstancePtr) 325

326 u32 XilSKey_ZynqMp_EfusePs_ReadPufAux (u32 Address, u8 ReadOption) u32 XilSKey_Write_Puf_EfusePs_SecureBits (XilSKey_Puf_Secure WriteSecureBits) u32 XilSKey_Read_Puf_EfusePs_SecureBits (XilSKey_Puf_Secure SecureBitsRead, u8 ReadOption) u32 XilSKey_Puf_Debug2 (XilSKey_Puf InstancePtr) u32 XilSKey_Puf_Registration (XilSKey_Puf InstancePtr) Function Documentation u32 XilSKey_ZynqMp_EfusePs_CheckAesKeyCrc ( u32 CrcValue ) This function performs CRC check of AES key. CrcValue 32 bit CRC of expected AES key. XST_SUCCESS - On success ErrorCode - on Failure For Calculating CRC of AES key use XilSKey_CrcCalculation() API or XilSkey_CrcCalculation_AesKey() API. u32 XilSKey_ZynqMp_EfusePs_ReadUserFuse ( u32 UseFusePtr, u8 UserFuse_Num, u8 ReadOption ) This function is used to read user fuse from efuse or cache based on user's read option. UseFusePtr Pointer to an array which holds the readback user fuse in. UserFuse_Num A variable which holds the user fuse number. Range is (User fuses: 0 to 7) ReadOption A variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0 Reads from cache 1 Reads from efuse array 326

327 XST_SUCCESS - On success ErrorCode - on Failure u32 XilSKey_ZynqMp_EfusePs_ReadPpk0Hash ( u32 Ppk0Hash, u8 ReadOption ) This function is used to read PPK0 hash from efuse or cache based on user's read option. Ppk0Hash ReadOption A pointer to an array which holds the readback PPK0 hash in. A variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0 Reads from cache 1 Reads from efuse array XST_SUCCESS - On success ErrorCode - on Failure u32 XilSKey_ZynqMp_EfusePs_ReadPpk1Hash ( u32 Ppk1Hash, u8 ReadOption ) This function is used to read PPK1 hash from efuse or cache based on user's read option. Ppk1Hash ReadOption Pointer to an array which holds the readback PPK1 hash in. A variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0 Reads from cache 1 Reads from efuse array XST_SUCCESS - On success ErrorCode - on Failure 327

328 u32 XilSKey_ZynqMp_EfusePs_ReadSpkId ( u32 SpkId, u8 ReadOption ) This function is used to read SPKID from efuse or cache based on user's read option. SpkId ReadOption Pointer to a 32 bit variable which holds SPK ID. A variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0 Reads from cache 1 Reads from efuse array XST_SUCCESS - On success ErrorCode - on Failure void XilSKey_ZynqMp_EfusePs_ReadDna ( u32 DnaRead ) This function is used to read DNA from efuse. DnaRead Pointer to 32 bit variable which holds the readback DNA in. u32 XilSKey_ZynqMp_EfusePs_ReadSecCtrlBits ( XilSKey_SecCtrlBits ReadBackSecCtrlBits, u8 ReadOption ) This function is used to read the PS efuse secure control bits from cache or efuse based on user input provided. 328

329 ReadBackSecCtrlBits ReadOption Pointer to the XilSKey_SecCtrlBits which holds the read secure control bits. Variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0 Reads from cache 1 Reads from efuse array XST_SUCCESS if reads successfully XST_FAILURE if reading is failed Cache reload is required for obtaining updated values for ReadOption 0. u32 XilSKey_ZynqMp_EfusePs_Write ( XilSKey_ZynqMpEPs InstancePtr ) This function is used to program the PS efuse of ZynqMP, based on user inputs. InstancePtr Pointer to the XilSKey_ZynqMpEPs. XST_SUCCESS if programs successfully. Errorcode on failure Cache reload is required for obtaining updated values through cache, XilSKey_ZynqMp_EfusePs_CacheLoad() API. to reload cache use u32 XilSKey_ZynqMp_EfusePs_WritePufHelprData ( XilSKey_Puf InstancePtr ) This function programs the PS efuse's with puf helper data of ZynqMp. 329

330 InstancePtr Pointer to the XilSKey_Puf instance. XST_SUCCESS if programs successfully. Errorcode on failure To generate PufSyndromeData please use XilSKey_Puf_Registration API u32 XilSKey_ZynqMp_EfusePs_ReadPufHelprData ( Address ) This function reads the puf helper data from efuse. u32 Address Pointer to data array which holds the Puf helper data read from ZynqMp efuse. XST_SUCCESS if reads successfully. Errorcode on failure. This function only reads from efuse non-volatile memory. There is no option to read from Cache. u32 XilSKey_ZynqMp_EfusePs_WritePufChash ( XilSKey_Puf InstancePtr ) This API programs efuse with CHash value. InstancePtr Pointer to the XilSKey_Puf instance. XST_SUCCESS if chash is programmed successfully. Errorcode on failure To generate CHash value please use XilSKey_Puf_Registration API 330

331 u32 XilSKey_ZynqMp_EfusePs_ReadPufChash ( u32 Address, u8 ReadOption ) This API reads efuse puf CHash Data from efuse array or cache based on the user read option. Address ReadOption Pointer which holds the read back value of chash A u8 variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0(XSK_EFUSEPS_READ_FROM_CACHE)Reads from cache 1(XSK_EFUSEPS_READ_FROM_EFUSE)Reads from efuse array XST_SUCCESS if programs successfully. Errorcode on failure Cache reload is required for obtaining updated values for ReadOption 0. u32 XilSKey_ZynqMp_EfusePs_WritePufAux ( XilSKey_Puf InstancePtr ) This API programs efuse puf Auxilary Data. InstancePtr Pointer to the XilSKey_Puf instance. XST_SUCCESS if programs successfully. Errorcode on failure To generate Auxilary data please use the below API u32 XilSKey_Puf_Registration(XilSKey_Puf InstancePtr) 331

332 u32 XilSKey_ZynqMp_EfusePs_ReadPufAux ( u32 Address, u8 ReadOption ) This API reads efuse puf Auxilary Data from efuse array or cache based on user read option. Address ReadOption Pointer which holds the read back value of Auxilary A u8 variable which has to be provided by user based on this input reading is happend from cache or from efuse array. 0(XSK_EFUSEPS_READ_FROM_CACHE)Reads from cache 1(XSK_EFUSEPS_READ_FROM_EFUSE)Reads from efuse array XST_SUCCESS if programs successfully. Errorcode on failure Cache reload is required for obtaining updated values for ReadOption 0. u32 XilSKey_Write_Puf_EfusePs_SecureBits ( XilSKey_Puf_Secure WriteSecureBits ) This function programs the efuse PUF secure bits. WriteSecureBits Pointer to the XilSKey_Puf_Secure structure XST_SUCCESS - On success ErrorCode - on Failure u32 XilSKey_Read_Puf_EfusePs_SecureBits ( XilSKey_Puf_Secure SecureBitsRead, u8 ReadOption ) This function is used to read the PS efuse PUF secure bits from cache or from efuse array based on user selection. 332

333 SecureBits ReadOption Pointer to the XilSKey_Puf_Secure which holds the read efuse secure bits of PUF. A u8 variable which has to be provided by user based on this input reading is happened from cache or from efuse array. 0(XSK_EFUSEPS_READ_FROM_CACHE) Reads from cache 1(XSK_EFUSEPS_READ_FROM_EFUSE) Reads from efuse array XST_SUCCESS - On success ErrorCode - on Failure u32 XilSKey_Puf_Debug2 ( XilSKey_Puf InstancePtr ) PUF Debug 2 operation. InstancePtr Pointer to the XilSKey_Puf instance. XST_SUCCESS if debug 2 mode was successful. ERROR if registration was unsuccessful. Updates the Debug 2 mode InstancePtr->Debug2Data u32 XilSKey_Puf_Registration ( XilSKey_Puf InstancePtr ) PUF Registration/Re-registration. InstancePtr Pointer to the XilSKey_Puf instance. XST_SUCCESS if registration/re-registration was successful. ERROR if registration was unsuccessful 333

334 Updates the syndrome InstancePtr->SyndromeData 334

335 efuse PL API Overview This chapter provides a linked summary and detailed descriptions of the efuse APIs of Zynq efuse PL and UltraScale efuse. Example Usage The Zynq efuse PL and UltraScale example application should contain the xilskey_efuse_example.c and the xilskey_input.h files. By default, both the efuse PS and PL are enabled in the application. 'XSK_EFUSEPL_DRIVER' to execute only the PS. You can comment For UltraScale, it is mandatory to comment XSK_EFUSEPS_DRIVER else the example will generate an error. For more details on the user configurable parameters, refer Zynq User-Configurable PL efuse and UltraScale User-Configurable PL efuse. Requires hardware setup to program PL efuse of Zynq or UltraScale. Functions u32 XilSKey_EfusePl_Program (XilSKey_EPl PlInstancePtr) u32 XilSKey_EfusePl_ReadStatus (XilSKey_EPl InstancePtr, u32 StatusBits) u32 XilSKey_EfusePl_ReadKey (XilSKey_EPl InstancePtr) u32 XilSKey_CrcCalculation (u8 Key) Function Documentation u32 XilSKey_EfusePl_Program ( XilSKey_EPl InstancePtr ) Programs PL efuse with input data given through InstancePtr. 335

336 When called, this API: Initializes the timer, XADC/xsysmon and JTAG server subsystems. Writes the AES & User Keys if requested. In UltraScale, if requested it also programs the RSA Hash Writes the Control Bits if requested. an error if: In Zynq the reference clock frequency is not in between 20 and 60 MHz. The PL DAP ID is not identified. The system is not in a position to write the requested PL efuse bits (because the bits are already written or not allowed to write) Temperature and voltage are not within range. InstancePtr Pointer to PL efuse instance which holds the input data to be written to PL efuse. XST_FAILURE - In case of failure XST_SUCCESS - In case of Success In Zynq Updates the global variable ErrorCode with error code(if any). u32 XilSKey_EfusePl_ReadStatus ( XilSKey_EPl InstancePtr, u32 StatusBits ) Reads the PL efuse status bits and gets all secure and control bits. InstancePtr StatusBits Pointer to PL efuse instance. Buffer to store the status bits read. XST_FAILURE - In case of failure XST_SUCCESS - In case of Success In Zynq Updates the global variable ErrorCode with error code(if any). 336

337 u32 XilSKey_EfusePl_ReadKey ( XilSKey_EPl InstancePtr ) Reads the PL efuse keys and stores them in the corresponding arrays in instance structure, it initializes the timer, XADC and JTAG server subsystems, if not already done so. In Zynq - Reads AES key and User keys In Ultrascale - 32 bit and 128 bit User keys and RSA hash But in Ultrascale AES key cannot be read directly it can be verified with CRC check, for that we need to update the instance with 32 bit CRC value, API updates whether provided CRC value is matched with actuals or not. To calculate the CRC of expected AES key one can use any of the following APIs XilSKey_CrcCalculation() or XilSkey_CrcCalculation_AesKey() InstancePtr Pointer to PL efuse instance. XST_FAILURE - In case of failure XST_SUCCESS - In case of Success In Zynq updates the global variable ErrorCode with error code(if any). u32 XilSKey_CrcCalculation ( u8 Key ) Calculates CRC value of provided key, this API expects key in string format. Key is the string contains AES key in hexa decimal of length less than or equal to 64. On Success returns the Crc of AES key value. On failure returns the error code when string length is greater than 64 This API calculates CRC of AES key for Ultrascale Microblaze's PL efuse and ZynqMp UltraScale PS efuse. If length of the string provided is lesser than 64, API appends the string with zeros. 337

338 CRC Calculation API Overview This chapter provides a linked summary and detailed descriptions of the CRC calculation APIs. For UltraScale and Zynq UltraScale+ MPSoC devices, programmed AES cannot be read back. The programmed AES key can only be confirmed by doing CRC check of AES key. Functions u32 XilSKey_CrcCalculation (u8 Key) u32 XilSkey_CrcCalculation_AesKey (u8 Key) Function Documentation u32 XilSKey_CrcCalculation ( u8 Key ) Calculates CRC value of provided key, this API expects key in string format. Key is the string contains AES key in hexa decimal of length less than or equal to 64. On Success returns the Crc of AES key value. On failure returns the error code when string length is greater than 64 This API calculates CRC of AES key for Ultrascale Microblaze's PL efuse and ZynqMp UltraScale PS efuse. If length of the string provided is lesser than 64, API appends the string with zeros. 338

339 u32 XilSkey_CrcCalculation_AesKey ( u8 Key ) Calculates CRC value of the provided key. Key should be provided in hexa buffer. Key Pointer to an array of size 32 which contains AES key in hexa decimal. Crc of provided AES key value. This API calculates CRC of AES key for Ultrascale Microblaze's PL efuse and ZynqMp Ultrascale's PS efuse. This API calculates CRC on AES key provided in hexa format. To calculate CRC on the AES key in string format please use XilSKey_CrcCalculation. To call this API one can directly pass array of AES key which exists in an instance. Example for storing key into Buffer: If Key is "123456" buffer should be {0x12 0x34 0x56} 339

340 User-Configurable Overview This chapter provides detailed descriptions of the various user configurable parameters. Modules Zynq User-Configurable PS efuse Zynq User-Configurable PL efuse Zynq User-Configurable PL BBRAM UltraScale User-Configurable BBRAM PL UltraScale User-Configurable PL efuse Zynq UltraScale+ MPSoC User-Configurable PS efuse Zynq UltraScale+ MPSoC User-Configurable PS BBRAM Zynq UltraScale+ MPSoC User-Configurable PS PUF Zynq User-Configurable PS efuse Define the XSK_EFUSEPS_DRIVER macro to use the PS efuse. After defining the macro, provide the inputs defined with XSK_EFUSEPS_DRIVER to burn the bits in PS efuse. If the bit is to be burned, define the macro as TRUE; otherwise define the macro as FALSE. For details, refer the following table. 340

341 Macro Name XSK_EFUSEPS_ENABLE_WRITE_PROTECT XSK_EFUSEPS_ENABLE_RSA_AUTH XSK_EFUSEPS_ENABLE_ROM_128K_CRC XSK_EFUSEPS_ENABLE_RSA_KEY_HASH Description Default = FALSE. TRUE to burn the write-protect bits in efuse array. Write protect has two bits. When either of the bits is burned, it is considered write-protected. So, while burning the write-protected bits, even if one bit is blown, write API returns success. As previously mentioned, POR reset is required after burning for write protection of the efuse bits to go into effect. It is recommended to do the POR reset after write protection. Also note that, after write-protect bits are burned, no more efuse writes are possible. If the write-protect macro is TRUE with other macros, write protect is burned in the last iteration, after burning all the defined values, so that for any error while burning other macros will not effect the total efuse array. FALSE does not modify the write-protect bits. Default = FALSE. Use TRUE to burn the RSA enable bit in the PS efuse array. After enabling the bit, every successive boot must be RSA-enabled apart from JTAG. Before burning (blowing) this bit, make sure that efuse array has the valid PPK hash. If the PPK hash burning is enabled, only after writing the hash successfully, RSA enable bit will be blown. For the RSA enable bit to take effect, POR reset is required. FALSE does not modify the RSA enable bit. Default = FALSE. TRUE burns the ROM 128K CRC bit. In every successive boot, BootROM calculates 128k CRC. FALSE does not modify the ROM CRC 128K bit. Default = FALSE. TRUE burns (blows) the efuse hash, that is given in XSK_EFUSEPS_RSA_KEY_HASH_VALUE when write API is used. TRUE reads the efuse hash when the read API is used and is read into structure. FALSE ignores the provided value. 341

342 Macro Name Description XSK_EFUSEPS_RSA_KEY_HASH_VALUE Default = The specified value is converted to a hexadecimal buffer and written into the PS efuse array when the write API is used. This value should be the Primary Public Key (PPK) hash provided in string format. The buffer must be 64 characters long: valid characters are 0-9, a-f, and A-F. Any other character is considered an invalid string and will not burn RSA hash. When the Xilskey_EfusePs_Write() API is used, the RSA hash is written, and the XSK_EFUSEPS_ENABLE_RSA_KEY_HASH must have a value of TRUE. XSK_EFUSEPS_DISABLE_DFT_JTAG XSK_EFUSEPS_DISABLE_DFT_MODE Default = FALSE TRUE disables DFT JTAG permanently. FALSE will not modify the efuse PS DFT JTAG disable bit. Default = FALSE TRUE disables DFT mode permanently. FALSE will not modify the efuse PS DFT mode disable bit. Zynq User-Configurable PL efuse Overview Define the XSK_EFUSEPL_DRIVER macro to use the PL efuse. After defining the macro, provide the inputs defined with XSK_EFUSEPL_DRIVER to burn the bits in PL efuse bits. If the bit is to be burned, define the macro as TRUE; otherwise define the macro as FALSE. The table below lists the user-configurable PL efuse parameters for Zynq devices. Macro Name XSK_EFUSEPL_FORCE_PCYCLE_RECONFIG XSK_EFUSEPL_DISABLE_KEY_WRITE Description Default = FALSE If the value is set to TRUE, then the part has to be power-cycled to be reconfigured. FALSE does not set the efuse control bit. Default = FALSE TRUE disables the efuse write to FUSE_AES and FUSE_USER blocks. FALSE does not affect the EFUSE bit. 342

343 Macro Name XSK_EFUSEPL_DISABLE_AES_KEY_READ XSK_EFUSEPL_DISABLE_USER_KEY_READ XSK_EFUSEPL_DISABLE_FUSE_CNTRL_WRITE XSK_EFUSEPL_FORCE_USE_AES_ONLY XSK_EFUSEPL_DISABLE_JTAG_CHAIN XSK_EFUSEPL_BBRAM_KEY_DISABLE Description Default = FALSE TRUE disables the write to FUSE_AES and FUSE_USER key and disables the read of FUSE_AES. FALSE does not affect the efuse bit. Default = FALSE. TRUE disables the write to FUSE_AES and FUSE_USER key and disables the read of FUSE_USER. FALSE does not affect the efuse bit. Default = FALSE. TRUE disables the efuse write to FUSE_CTRL block. FALSE does not affect the efuse bit. Default = FALSE. TRUE forces the use of secure boot with efuse AES key only. FALSE does not affect the efuse bit. Default = FALSE. TRUE permanently disables the Zynq ARM DAP and PL TAP. FALSE does not affect the efuse bit. Default = FALSE. TRUE forces the efuse key to be used if booting Secure Image. FALSE does not affect the efuse bit. Modules MIO Pins for Zynq PL efuse JTAG Operations MUX Selection Pin for Zynq PL efuse JTAG Operations MUX Parameter for Zynq PL efuse JTAG Operations AES and User Key MIO Pins for Zynq PL efuse JTAG Operations The table below lists the MIO pins for Zynq PL efuse JTAG operations. You can change the listed pins at your discretion. 343

344 The pin numbers listed in the table below are examples. You must assign appropriate pin numbers as per your hardware design. Pin Name Pin Number XSK_EFUSEPL_MIO_JTAG_TDI (17) XSK_EFUSEPL_MIO_JTAG_TDO (18) XSK_EFUSEPL_MIO_JTAG_TCK (19) XSK_EFUSEPL_MIO_JTAG_TMS (20) MUX Selection Pin for Zynq PL efuse JTAG Operations The table below lists the MUX selection pin. Pin Name Pin Number Description XSK_EFUSEPL_MIO_JTAG_ MUX_SELECT (21) This pin toggles between the external JTAG or MIO driving JTAG operations. MUX Parameter for Zynq PL efuse JTAG Operations The table below lists the MUX parameter. Parameter Name XSK_EFUSEPL_MIO_MUX_SEL_DEFAULT_VAL Description Default = LOW. LOW writes zero on the MUX select line before PL_eFUSE writing. HIGH writes one on the MUX select line before PL_eFUSE writing. 344

345 AES and User Key The table below lists the AES and user key parameters. Parameter Name XSK_EFUSEPL_PROGRAM_AES_AND_USER_ LOW_KEY XSK_EFUSEPL_PROGRAM_USER_HIGH_KEY Description Default = FALSE. TRUE burns the AES and User Low hash key, which are given in the XSK_EFUSEPL_AES_KEY and the XSK_EFUSEPL_USER_LOW_KEY respectively. FALSE ignores the provided values. You cannot write the AES Key and the User Low Key separately. Default =FALSE. TRUE burns the User High hash key, given in XSK_EFUSEPL_PROGRAM_USER_HIGH_KEY. FALSE ignores the provided values. XSK_EFUSEPL_AES_KEY Default = This value converted to hex buffer and written into the PL efuse array when write API is used. This value should be the AES Key, given in string format. It must be 64 characters long. Valid characters are 0-9, a-f, A-F. Any other character is considered an invalid string and will not burn AES Key. To write AES Key, XSK_EFUSEPL_PROGRAM_AES_AND_USER_ LOW_KEY must have a value of TRUE. XSK_EFUSEPL_USER_LOW_KEY Default = 00 This value is converted to a hexadecimal buffer and written into the PL efuse array when the write API is used. This value is the User Low Key given in string format. It must be two characters long; valid characters are 0-9,a-f, and A-F. Any other character is considered as an invalid string and will not burn the User Low Key. To write the User Low Key, XSK_EFUSEPL_PROGRAM_AES_AND_USER_ LOW_KEY must have a value of TRUE. 345

346 Parameter Name Description XSK_EFUSEPL_USER_HIGH_KEY Default = The default value is converted to a hexadecimal buffer and written into the PL efuse array when the write API is used. This value is the User High Key given in string format. The buffer must be six characters long: valid characters are 0-9, a-f, A-F. Any other character is considered to be an invalid string and does not burn User High Key. To write the User High Key, the XSK_EFUSEPL_PROGRAM_USER_HIGH_ KEY must have a value of TRUE. Zynq User-Configurable PL BBRAM Overview The table below lists the MIO pins for Zynq PL BBRAM JTAG operations. The pin numbers listed in the table below are examples. You must assign appropriate pin numbers as per your hardware design. Pin Name Pin Number XSK_BBRAM_MIO_JTAG_TDI (17) XSK_BBRAM_MIO_JTAG_TDO (21) XSK_BBRAM_MIO_JTAG_TCK (19) XSK_BBRAM_MIO_JTAG_TMS (20) The table below lists the MUX selection pin for Zynq BBRAM PL JTAG operations. Pin Name Pin Number XSK_BBRAM_MIO_JTAG_MUX_SELECT (11) Modules MUX Parameter for Zynq BBRAM PL JTAG Operations AES and User Key 346

347 MUX Parameter for Zynq BBRAM PL JTAG Operations The table below lists the MUX parameter for Zynq BBRAM PL JTAG operations. Parameter Name XSK_BBRAM_MIO_MUX_SEL_DEFAULT_VAL Description Default = LOW. LOW writes zero on the MUX select line before PL_eFUSE writing. HIGH writes one on the MUX select line before PL_eFUSE writing. AES and User Key The table below lists the AES and user key parameters. Parameter Name XSK_BBRAM_AES_KEY Description Default = XX. AES key (in HEX) that must be programmed into BBRAM. XSK_BBRAM_AES_KEY_SIZE_IN_BITS Default = 256. Size of AES key. Must be 256 bits. UltraScale User-Configurable BBRAM PL Overview Following parameters need to be configured. Based on your inputs, BBRAM is programmed with the provided AES key. Modules AES Keys and Related DPA Protection for BBRAM key GPIO Pins Used for PL Master JTAG and HWM Signals GPIO Channels AES Keys and Related The following table shows AES key related parameters. 347

348 Parameter Name XSK_BBRAM_PGM_OBFUSCATED_KEY XSK_BBRAM_OBFUSCATED_KEY Description Default = FALSE By default XSK_BBRAM_PGM_OBFUSCATED_KEY is FALSE, BBRAM is programmed with a non-obfuscated key provided in XSK_BBRAM_AES_KEY and DPA protection can be either in enabled/disabled state. TRUE programs the BBRAM with key provided in XSK_BBRAM_OBFUSCATED_KEY and DPA protection cannot be enabled. Default = b1c276899d71fb4cdd4a0a7905ea46c2e1 1f9574d09c7ea23b70b67de713ccd1 The value mentioned in this will be converted to hex buffer and the key is programmed into BBRAM, when program API is called. It should be 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not program BBRAM. For writing the OBFUSCATED Key, XSK_BBRAM_PGM_OBFUSCATED_KEY should have TRUE value. XSK_BBRAM_AES_KEY Default = a63950bcedaf eadcdeabaadee aaaabbaaa The value mentioned in this will be converted to hex buffer and the key is programmed into BBRAM,when program API is called. It should be 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not program BBRAM. For programming BBRAM with the key, XSK_BBRAM_PGM_OBFUSCATED_KEY should have a FALSE value. XSK_BBRAM_AES_KEY_SIZE_IN_BITS Default= 256 Size of AES key must be 256 bits. 348

349 DPA Protection for BBRAM key The following table shows DPA protection configurable parameter. Parameter Name XSK_BBRAM_DPA_PROTECT_ENABLE Description Default = FALSE By default, the DPA protection will be in disabled state. TRUE will enable DPA protection with provided DPA count and configuration in XSK_BBRAM_DPA_COUNT and XSK_BBRAM_DPA_MODE respectively. DPA protection cannot be enabled if BBRAM is been programmed with an obfuscated key. XSK_BBRAM_DPA_COUNT Default = 0 This input is valid only when DPA protection is enabled. Valid range of values are when DPA protection is enabled else 0. XSK_BBRAM_DPA_MODE Default = XSK_BBRAM_INVALID_CONFIGURATIONS When DPA protection is enabled it can be XSK_BBRAM_INVALID_CONFIGURATIONS or XSK_BBRAM_ALL_CONFIGURATIONS If DPA protection is disabled this input provided over here is ignored. GPIO Pins Used for PL Master JTAG and HWM Signals In Ultrascale the following GPIO pins are used for connecting MASTER_JTAG pins to access BBRAM. These can be changed depending on your hardware.the table below shows the GPIO pins used for PL MASTER JTAG signals. Master JTAG Signal Default PIN Number XSK_BBRAM_AXI_GPIO_JTAG_TDO 0 XSK_BBRAM_AXI_GPIO_JTAG_TDI 0 XSK_BBRAM_AXI_GPIO_JTAG_TMS 1 XSK_BBRAM_AXI_GPIO_JTAG_TCK 2 GPIO Channels The following table shows GPIO channel number. 349

350 Parameter Default Channel Number Master JTAG Signal Connected XSK_BBRAM_GPIO_INPUT_CH 2 TDO XSK_BBRAM_GPIO_OUTPUT_CH 1 TDI, TMS, TCK All inputs and outputs of GPIO can be configured in single channel. For example, XSK_BBRAM_GPIO_INPUT_CH = XSK_BBRAM_GPIO_OUTPUT_CH = 1 or 2. Among (TDI, TCK, TMS) Outputs of GPIO cannot be connected to different GPIO channels all the 3 signals should be in same channel. TDO can be a other channel of (TDI, TCK, TMS) or the same. DPA protection can be enabled only when programming non-obfuscated key. UltraScale User-Configurable PL efuse Overview The table below lists the user-configurable PL efuse parameters for UltraScale devices. Macro Name XSK_EFUSEPL_DISABLE_AES_KEY_READ XSK_EFUSEPL_DISABLE_USER_KEY_READ XSK_EFUSEPL_DISABLE_SECURE_READ XSK_EFUSEPL_DISABLE_FUSE_CNTRL_WRITE Description Default = FALSE TRUE will permanently disable the write to FUSE_AES and check CRC for AES key by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable the write to 32 bit FUSE_USER and read of FUSE_USER key by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable the write to FUSE_Secure block and reading of secure block by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to FUSE_CNTRL block by programming control bit of FUSE. FALSE will not modify this control bit of efuse. 350

351 Macro Name XSK_EFUSEPL_DISABLE_RSA_KEY_READ XSK_EFUSEPL_DISABLE_KEY_WRITE XSK_EFUSEPL_DISABLE_USER_KEY_WRITE XSK_EFUSEPL_DISABLE_SECURE_WRITE XSK_EFUSEPL_DISABLE_RSA_HASH_WRITE XSK_EFUSEPL_DISABLE_128BIT_USER_KEY _WRITE XSK_EFUSEPL_ALLOW_ENCRYPTED_ONLY XSK_EFUSEPL_FORCE_USE_FUSE_AES_ONLY XSK_EFUSEPL_ENABLE_RSA_AUTH Description Default = FALSE. TRUE will permanently disable the write to FUSE_RSA block and reading of FUSE_RSA Hash by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to FUSE_AES block by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to FUSE_USER block by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to FUSE_SECURE block by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to FUSE_RSA authentication key by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently disable the write to 128 bit FUSE_USER by programming control bit of FUSE. FALSE will not modify this control bit of efuse. Default = FALSE. TRUE will permanently allow encrypted bitstream only. FALSE will not modify this Secure bit of efuse. Default = FALSE. TRUE then allows only FUSE's AES key as source of encryption FALSE then allows FPGA to configure an unencrypted bitstream or bitstream encrypted using key stored BBRAM or efuse. Default = FALSE. TRUE will enable RSA authentication of bitstream FALSE will not modify this secure bit of efuse. 351

352 Macro Name XSK_EFUSEPL_DISABLE_JTAG_CHAIN XSK_EFUSEPL_DISABLE_TEST_ACCESS XSK_EFUSEPL_DISABLE_AES_DECRYPTOR Description Default = FALSE. TRUE will disable JTAG permanently. FALSE will not modify this secure bit of efuse. Default = FALSE. TRUE will disables Xilinx test access. FALSE will not modify this secure bit of efuse. Default = FALSE. TRUE will disables decoder completely. FALSE will not modify this secure bit of efuse. Modules GPIO Pins Used for PL Master JTAG Signal GPIO Channels AES Keys and Related GPIO Pins Used for PL Master JTAG Signal In Ultrascale the following GPIO pins are used for connecting MASTER_JTAG pins to access BBRAM. These can be changed depending on your hardware.the table below shows the GPIO pins used for PL MASTER JTAG signals. Master JTAG Signal Default PIN Number XSK_EFUSEPL_AXI_GPIO_JTAG_TDO 0 XSK_EFUSEPL_AXI_GPIO_HWM_READY 0 XSK_EFUSEPL_AXI_GPIO_HWM_END 1 XSK_EFUSEPL_AXI_GPIO_JTAG_TDI 2 XSK_EFUSEPL_AXI_GPIO_JTAG_TMS 1 XSK_EFUSEPL_AXI_GPIO_JTAG_TCK 2 XSK_EFUSEPL_AXI_GPIO_HWM_START 3 352

353 GPIO Channels The following table shows GPIO channel number. Parameter Default Channel Number Master JTAG Signal Connected XSK_EFUSEPL_GPIO_INPUT_ CH XSK_EFUSEPL_GPIO_OUTPUT_ CH 2 TDO 1 TDI, TMS, TCK All inputs and outputs of GPIO can be configured in single channel. For example, XSK_BBRAM_GPIO_INPUT_CH = XSK_BBRAM_GPIO_OUTPUT_CH = 1 or 2. Among (TDI, TCK, TMS) Outputs of GPIO cannot be connected to different GPIO channels all the 3 signals should be in same channel. TDO can be a other channel of (TDI, TCK, TMS) or the same. DPA protection can be enabled only when programming non-obfuscated key. AES Keys and Related The following table shows AES key related parameters. Parameter Name XSK_EFUSEPL_PROGRAM_AES_KEY_ULTRA XSK_EFUSEPL_PROGRAM_USER_KEY_ULTRA XSK_EFUSEPL_PROGRAM_RSA_HASH_ULTRA XSK_EFUSEPL_PROGRAM_USER_KEY_128BIT Description Default = FALSE TRUE will burn the AES key given in XSK_EFUSEPL_AES_KEY. FALSE will ignore the values given. Default = FALSE TRUE will burn 32 bit User key given in XSK_EFUSEPL_USER_KEY. FALSE will ignore the values given. Default = FALSE TRUE will burn RSA hash given in XSK_EFUSEPL_RSA_KEY_HASH_VALUE. FALSE will ignore the values given. Default = FALSE TRUE will burn 128 bit User key given in XSK_EFUSEPL_USER_KEY_128BIT_0, XSK_EFUSEPL_USER_KEY_128BIT_1, XSK_EFUSEPL_USER_KEY_128BIT_2, XSK_EFUSEPL_USER_KEY_128BIT_3 FALSE will ignore the values given. 353

354 Parameter Name XSK_EFUSEPL_CHECK_AES_KEY_ULTRA XSK_EFUSEPL_READ_USER_KEY_ULTRA XSK_EFUSEPL_READ_RSA_HASH_ULTRA XSK_EFUSEPL_READ_USER_KEY128_BIT Description Default = FALSE TRUE will perform CRC check of FUSE_AES with provided CRC value in macro XSK_EFUSEPL_CRC_OF_EXPECTED_AES_KEY. And result of CRC check will be updated in XilSKey_EPl instance parameter AESKeyMatched with either TRUE or FALSE. FALSE CRC check of FUSE_AES will not be performed. Default = FALSE TRUE will read 32 bit FUSE_USER from UltraScale efuse and updates in XilSKey_EPl instance parameter UserKeyReadback. FALSE 32-bit FUSE_USER key read will not be performed. Default = FALSE TRUE will read FUSE_USER from UltraScale efuse and updates in XilSKey_EPl instance parameter RSAHashReadback. FALSE FUSE_RSA_HASH read will not be performed. Default = FALSE TRUE will read 128 bit USER key from UltraScale efuse and updates in XilSKey_EPl instance parameter User128BitReadBack. FALSE 128 bit USER key read will not be performed. XSK_EFUSEPL_AES_KEY Default = The value mentioned in this will be converted to hex buffer and written into the PL efuse array when write API used. This value should be the PPK(Primary Public Key) hash given in string format. It should be 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn AES Key. that for writing the AES Key, XSK_EFUSEPL_PROGRAM_AES_KEY_ULTRA should have TRUE value. 354

355 Parameter Name Description XSK_EFUSEPL_USER_KEY Default = The value mentioned in this will be converted to hex buffer and written into the PL efuse array when write API used. This value should be the User Key given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn User Key. that, for writing the User Key, XSK_EFUSEPL_PROGRAM_USER_KEY_ULTRA should have TRUE value. XSK_EFUSEPL_RSA_KEY_HASH_VALUE Default = he value mentioned in this will be converted to hex buffer and written into the PL efuse array when write API used. This value should be the RSA Key hash given in string format. It should be 96 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn RSA hash value. that, for writing the RSA hash, XSK_EFUSEPL_PROGRAM_RSA_HASH_ULTRA should have TRUE value. XSK_EFUSEPL_CRC_OF_EXPECTED_AES_KEY Default = 0x621C42AA 0x621C42AA is hexadecimal CRC value of FUSE_AES with all Zeros. Expected FUSE_AES key's CRC value has to be updated in place of 0x621C42AA. For Checking CRC of FUSE_AES XSK_EFUSEPL _CHECK_AES_KEY_ULTRA macro should be TRUE otherwise CRC check will not be performed. For calculation of AES key's CRC one can use u32 XilSKey_CrcCalculation(u8 Key) API or reverse polynomial 0x82F63B

356 Zynq UltraScale+ MPSoC User-Configurable PS efuse Overview The table below lists the user-configurable PS efuse parameters for Zynq UltraScale+ MPSoC devices. Macro Name XSK_EFUSEPS_AES_RD_LOCK XSK_EFUSEPS_AES_WR_LOCK XSK_EFUSEPS_ENC_ONLY XSK_EFUSEPS_BBRAM_DISABLE XSK_EFUSEPS_ERR_DISABLE XSK_EFUSEPS_JTAG_DISABLE XSK_EFUSEPS_DFT_DISABLE XSK_EFUSEPS_PROG_GATE_DISABLE XSK_EFUSEPS_SECURE_LOCK Description Default = FALSE TRUE will permanently disable the CRC check of FUSE_AES. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable the writing to FUSE_AES block. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently enable encrypted booting only using the Fuse key. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable the BBRAM key. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disables the error messages in JTAG status register. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable JTAG controller. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable DFT boot mode. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable PROG_GATE feature in PPD. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable reboot into JTAG mode when doing a secure lockdown. FALSE will not modify thi s control bit of efuse. 356

357 Macro Name XSK_EFUSEPS_RSA_ENABLE XSK_EFUSEPS_PPK0_WR_LOCK XSK_EFUSEPS_PPK0_INVLD XSK_EFUSEPS_PPK1_WR_LOCK XSK_EFUSEPS_PPK1_INVLD XSK_EFUSEPS_USER_WRLK_0 XSK_EFUSEPS_USER_WRLK_1 XSK_EFUSEPS_USER_WRLK_2 XSK_EFUSEPS_USER_WRLK_3 XSK_EFUSEPS_USER_WRLK_4 Description Default = FALSE TRUE will permanently enable RSA authentication during boot. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to PPK0 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently revoke PPK0. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing PPK1 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently revoke PPK1. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_0 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_1 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_2 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_3 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_4 efuses. FALSE will not modify this control bit of efuse. 357

358 Macro Name XSK_EFUSEPS_USER_WRLK_5 XSK_EFUSEPS_USER_WRLK_6 XSK_EFUSEPS_USER_WRLK_7 XSK_EFUSEPS_LBIST_EN XSK_EFUSEPS_LPD_SC_EN XSK_EFUSEPS_FPD_SC_EN XSK_EFUSEPS_PBR_BOOT_ERR Description Default = FALSE TRUE will permanently disable writing to USER_5 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_6 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently disable writing to USER_7 efuses. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently enables logic BIST to be run during boot. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently enables zeroization of registers in Low Power Domain(LPD) during boot. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently enables zeroization of registers in Full Power Domain(FPD) during boot. FALSE will not modify this control bit of efuse. Default = FALSE TRUE will permanently enables the boot halt when there is any PMU error. FALSE will not modify this control bit of efuse. Modules AES Keys and Related User Keys and Related PPK0 Keys and Related PPK1 Keys and Related SPK ID and Related AES Keys and Related The following table shows AES key related parameters. 358

359 Parameter Name XSK_EFUSEPS_WRITE_AES_KEY Description Default = TRUE TRUE will burn the AES key provided in XSK_EFUSEPS_AES_KEY. FALSE will ignore the key provide XSK_EFUSEPS_AES_KEY. XSK_EFUSEPS_AES_KEY Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn AES Key. For writing the AES Key, XSK_EFUSEPS_WRITE_AES_KEY should have TRUE value. User Keys and Related Single bit programming is allowed for all the USER fuses. If user requests to revert already programmed bit. Library throws an error. If user fuses is non-zero also library will not throw an error for valid requests The following table shows the user keys and related parameters. Parameter Name XSK_EFUSEPS_WRITE_USER0_FUSE XSK_EFUSEPS_WRITE_USER1_FUSE XSK_EFUSEPS_WRITE_USER2_FUSE Description Default = TRUE TRUE will burn User0 Fuse provided in XSK_EFUSEPS_USER0_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER0_FUSES Default = TRUE TRUE will burn User1 Fuse provided in XSK_EFUSEPS_USER1_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER1_FUSES Default = TRUE TRUE will burn User2 Fuse provided in XSK_EFUSEPS_USER2_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER2_FUSES 359

360 Parameter Name XSK_EFUSEPS_WRITE_USER3_FUSE XSK_EFUSEPS_WRITE_USER4_FUSE XSK_EFUSEPS_WRITE_USER5_FUSE XSK_EFUSEPS_WRITE_USER6_FUSE XSK_EFUSEPS_WRITE_USER7_FUSE Description Default = TRUE TRUE will burn User3 Fuse provided in XSK_EFUSEPS_USER3_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER3_FUSES Default = TRUE TRUE will burn User4 Fuse provided in XSK_EFUSEPS_USER4_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER4_FUSES Default = TRUE TRUE will burn User5 Fuse provided in XSK_EFUSEPS_USER5_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER5_FUSES Default = TRUE TRUE will burn User6 Fuse provided in XSK_EFUSEPS_USER6_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER6_FUSES Default = TRUE TRUE will burn User7 Fuse provided in XSK_EFUSEPS_USER7_FUSES. FALSE will ignore the value provided in XSK_EFUSEPS_USER7_FUSES XSK_EFUSEPS_USER0_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User0 Fuse, XSK_EFUSEPS_WRITE_USER0_FUSE should have TRUE value 360

361 Parameter Name Description XSK_EFUSEPS_USER1_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User1 Fuse, XSK_EFUSEPS_WRITE_USER1_FUSE should have TRUE value XSK_EFUSEPS_USER2_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User2 Fuse, XSK_EFUSEPS_WRITE_USER2_FUSE should have TRUE value XSK_EFUSEPS_USER3_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User3 Fuse, XSK_EFUSEPS_WRITE_USER3_FUSE should have TRUE value 361

362 Parameter Name Description XSK_EFUSEPS_USER4_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User4 Fuse, XSK_EFUSEPS_WRITE_USER4_FUSE should have TRUE value XSK_EFUSEPS_USER5_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User5 Fuse, XSK_EFUSEPS_WRITE_USER5_FUSE should have TRUE value XSK_EFUSEPS_USER6_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User6 Fuse, XSK_EFUSEPS_WRITE_USER6_FUSE should have TRUE value 362

363 Parameter Name Description XSK_EFUSEPS_USER7_FUSES Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the User7 Fuse, XSK_EFUSEPS_WRITE_USER7_FUSE should have TRUE value PPK0 Keys and Related The following table shows the PPK0 keys and related parameters. Parameter Name XSK_EFUSEPS_WRITE_PPK0_SHA3_HASH XSK_EFUSEPS_PPK0_IS_SHA3 Description Default = TRUE TRUE will burn PPK0 sha3 hash provided in XSK_EFUSEPS_PPK0_SHA3_HASH. FALSE will ignore the hash provided in XSK_EFUSEPS_PPK0_SHA3_HASH. Default = TRUE TRUE XSK_EFUSEPS_PPK0_SHA3_HASH should be of string length 96 it specifies that PPK0 is used to program SHA3 hash. FALSE XSK_EFUSEPS_PPK0_SHA3_HASH should be of string length 64 it specifies that PPK0 is used to program SHA2 hash. 363

364 Parameter Name Description XSK_EFUSEPS_PPK0_HASH Default = The value mentioned in this will be converted to hex buffer and into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 96 or 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn PPK0 hash. that,for writing the PPK0 hash, XSK_EFUSEPS_WRITE_PPK0_SHA3_HASH should have TRUE value. While writing SHA2 hash, length should be 64 characters long XSK_EFUSEPS_PPK0_IS_SHA3 macro has to be made FALSE. While writing SHA3 hash, length should be 96 characters long and XSK_EFUSEPS_PPK0_IS_SHA3 macro should be made TRUE PPK1 Keys and Related The following table shows the PPK1 keys and related parameters. Parameter Name XSK_EFUSEPS_WRITE_PPK1_SHA3_HASH XSK_EFUSEPS_PPK1_IS_SHA3 Description Default = TRUE TRUE will burn PPK1 sha3 hash provided in XSK_EFUSEPS_PPK1_SHA3_HASH. FALSE will ignore the hash provided in XSK_EFUSEPS_PPK1_SHA3_HASH. Default = FALSE TRUE XSK_EFUSEPS_PPK1_SHA3_HASH should be of string length 96 it specifies that PPK1 is used to program SHA3 hash. FALSE XSK_EFUSEPS_PPK1_SHA3_HASH should be of string length 64 it specifies that PPK1 is used to program SHA2 hash. 364

365 Parameter Name Description XSK_EFUSEPS_PPK1_HASH Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 64 or 96 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn PPK1 hash. that,for writing the PPK11 hash, XSK_EFUSEPS_WRITE_PPK1_SHA3_HASH should have TRUE value. By default, PPK1 hash will be provided with 64 character length to program PPK1 hash with sha2 hash so XSK_EFUSEPS_PPK1_IS_SHA3 also will be in FALSE state. But to program PPK1 hash with SHA3 hash make XSK_EFUSEPS_PPK1_IS_SHA3 to TRUE and provide sha3 hash of length 96 characters XSK_EFUSEPS_PPK1_HASH so that one can program sha3 hash. SPK ID and Related The following table shows the SPK ID and related parameters. Parameter Name XSK_EFUSEPS_WRITE_SPKID Description Default = TRUE TRUE will burn SPKID provided in XSK_EFUSEPS_SPK_ID. FALSE will ignore the hash provided in XSK_EFUSEPS_SPK_ID. 365

366 Parameter Name Description XSK_EFUSEPS_SPK_ID Default = The value mentioned in this will be converted to hex buffer and written into the Zynq UltraScale+ MPSoC PS efuse array when write API used. This value should be given in string format. It should be 8 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn SPK ID. For writing the SPK ID, XSK_EFUSEPS_WRITE_SPKID should have TRUE value. PPK hash should be unmodified hash generated by bootgen. Single bit programming is allowed for User FUSEs (0 to 7), if you specify a value that tries to set a bit that was previously programmed to 1 back to 0, you will get an error. you have to provide already programmed bits also along with new requests. 366

367 Zynq UltraScale+ MPSoC User-Configurable PS BBRAM The table below lists the AES and user key parameters. Parameter Name Description XSK_ZYNQMP_BBRAMPS_AES_KEY Default = AES key (in HEX) that must be programmed into BBRAM. XSK_ZYNQMP_BBRAMPS_AES_KEY_LEN_IN_BYTESDefault = 32. Length of AES key in bytes. XSK_ZYNQMP_BBRAMPS_AES_KEY_LEN_IN_BITS Default = 256. Length of AES key in bits. XSK_ZYNQMP_BBRAMPS_AES_KEY_STR_LEN Default = 64. String length of the AES key. Zynq UltraScale+ MPSoC User-Configurable PS PUF The table below lists the user-configurable PS PUF parameters for Zynq UltraScale+ MPSoC devices. Macro Name XSK_PUF_INFO_ON_UART XSK_PUF_PROGRAM_EFUSE XSK_PUF_IF_CONTRACT_MANUFATURER XSK_PUF_REG_MODE Description Default = FALSE TRUE will display syndrome data on UART com port FALSE will display any data on UART com port. Default = FALSE TRUE will program the generated syndrome data, CHash and Auxilary values, Black key. FALSE will not program data into efuse. Default = FALSE This should be enabled when application is hand over to contract manufacturer. TRUE will allow only authenticated application. FALSE authentication is not mandatory. Default = XSK_PUF_MODE4K PUF registration is performed in 4K mode. For only understanding it is provided in this file, but user is not supposed to modify this. 367

368 Macro Name XSK_PUF_READ_SECUREBITS XSK_PUF_PROGRAM_SECUREBITS XSK_PUF_SYN_INVALID XSK_PUF_SYN_WRLK XSK_PUF_REGISTER_DISABLE XSK_PUF_RESERVED Description Default = FALSE TRUE will read status of the puf secure bits from efuse and will be displayed on UART. FALSE will not read secure bits. Default = FALSE TRUE will program PUF secure bits based on the user input provided at XSK_PUF_SYN_INVALID, XSK_PUF_SYN_WRLK and XSK_PUF_REGISTER_DISABLE. FALSE will not program any PUF secure bits. Default = FALSE TRUE will permanently invalidate the already programmed syndrome data. FALSE will not modify anything Default = FALSE TRUE will permanently disable programming syndrome data into efuse. FALSE will not modify anything. Default = FALSE TRUE permanently does not allow PUF syndrome data registration. FALSE will not modify anything. Default = FALSE TRUE programs this reserved efuse bit. FALSE will not modify anything. XSK_PUF_AES_KEY Default = The value mentioned in this will be converted to hex buffer and encrypts this with PUF helper data and generates a black key and written into the Zynq UltraScale+ MPSoC PS efuse array when XSK_PUF_PROGRAM_EFUSE macro is TRUE. This value should be given in string format. It should be 64 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string and will not burn AES Key. Provided here should be red key and application calculates the black key and programs into efuse if XSK_PUF_PROGRAM_EFUSE macro is TRUE. To avoid programming efuse results can be displayed on UART com port by making XSK_PUF_INFO_ON_UART to TRUE. 368

369 Macro Name Description XSK_PUF_IV Default = The value mentioned here will be converted to hex buffer. This is Initialization vector(iv) which is used to generated black key with provided AES key and generated PUF key. This value should be given in string format. It should be 24 characters long, valid characters are 0-9,a-f,A-F. Any other character is considered as invalid string. 369

370 Error Codes Overview The application error code is 32 bits long. For example, if the error code for PS is 0x8A05: 0x8A indicates that a write error has occurred while writing RSA Authentication bit. 0x05 indicates that write error is due to the write temperature out of range. Applications have the following options on how to show error status. Both of these methods of conveying the status are implemented by default. However, UART is required to be present and initialized for status to be displayed through UART. Send the error code through UART pins Write the error code in the reboot status register Modules PL efuse Error Codes PS efuse Error Codes Zynq UltraScale+ MPSoC BBRAM PS Error Codes PL efuse Error Codes XSK_EFUSEPL_ERROR_NONE 0 No error. XSK_EFUSEPL_ERROR_ROW_NOT_ZERO Row is not zero. 0x10 XSK_EFUSEPL_ERROR_READ_ROW_OUT_OF_RANGE Read Row is out of range. XSK_EFUSEPL_ERROR_READ_MARGIN_OUT_OF_RANGE Read Margin is out of range. XSK_EFUSEPL_ERROR_READ_BUFFER_NULL No buffer for read. 0x13 0x11 0x12 370

371 XSK_EFUSEPL_ERROR_READ_BIT_VALUE_NOT_SET 0x14 Read bit not set. XSK_EFUSEPL_ERROR_READ_BIT_OUT_OF_RANGE <0x15 br>read bit is out of range. XSK_EFUSEPL_ERROR_READ_TMEPERATURE_OUT_OF_RANGE 0x16 Temperature obtained from XADC is out of range to read. XSK_EFUSEPL_ERROR_READ_VCCAUX_VOLTAGE_OUT_OF_RANGE 0x17 VCCAUX obtained from XADC is out of range to read. XSK_EFUSEPL_ERROR_READ_VCCINT_VOLTAGE_OUT_OF_RANGE PL VCCINT obtained from XADC is out of range to read. XSK_EFUSEPL_ERROR_WRITE_ROW_OUT_OF_RANGE 0x19 To write row is out of range. XSK_EFUSEPL_ERROR_WRITE_BIT_OUT_OF_RANGE 0x1A To read bit is out of range. XSK_EFUSEPL_ERROR_WRITE_TMEPERATURE_OUT_OF_RANGE 0x1B To efuse write Temperature obtained from XADC is outof range. XSK_EFUSEPL_ERROR_WRITE_VCCAUX_VOLTAGE_OUT_OF_RANGE 0x1C To write efuse VCCAUX obtained from XADC is out of range. XSK_EFUSEPL_ERROR_WRITE_VCCINT_VOLTAGE_OUT_OF_RANGE 0x1D To write into efuse VCCINT obtained from XADC is out of range. XSK_EFUSEPL_ERROR_FUSE_CNTRL_WRITE_DISABLED 0x1E Fuse control write is disabled. XSK_EFUSEPL_ERROR_CNTRL_WRITE_BUFFER_NULL 0x1F Buffer pointer that is supposed to contain control data is null. XSK_EFUSEPL_ERROR_NOT_VALID_KEY_LENGTH 0x20 Key length invalid. XSK_EFUSEPL_ERROR_ZERO_KEY_LENGTH 0x21 Key length zero. XSK_EFUSEPL_ERROR_NOT_VALID_KEY_CHAR 0x22 Invalid key characters. XSK_EFUSEPL_ERROR_NULL_KEY 0x23 Null key. XSK_EFUSEPL_ERROR_FUSE_SEC_WRITE_DISABLED 0x24 Secure bits write is disabled. XSK_EFUSEPL_ERROR_FUSE_SEC_READ_DISABLED 0x25 Secure bits reading is disabled. XSK_EFUSEPL_ERROR_SEC_WRITE_BUFFER_NULL 0x26 Buffer to write into secure block is NULL. XSK_EFUSEPL_ERROR_READ_PAGE_OUT_OF_RANGE 0x27 Page is out of range. XSK_EFUSEPL_ERROR_FUSE_ROW_RANGE 0x28 Row is out of range. 371

372 XSK_EFUSEPL_ERROR_IN_PROGRAMMING_ROW 0x29 Error programming fuse row. XSK_EFUSEPL_ERROR_PRGRMG_ROWS_NOT_EMPTY 0x2A Error when tried to program non Zero rows of efuse. XSK_EFUSEPL_ERROR_HWM_TIMEOUT 0x80 Error when hardware module is exceeded the time for programming efuse. XSK_EFUSEPL_ERROR_USER_FUSE_REVERT 0x90 Error occurs when user requests to revert already programmed user efuse bit. XSK_EFUSEPL_ERROR_KEY_VALIDATION 0xF000 Invalid key. XSK_EFUSEPL_ERROR_PL_STRUCT_NULL 0x1000 Null PL structure. XSK_EFUSEPL_ERROR_JTAG_SERVER_INIT 0x1100 JTAG server initialization error. XSK_EFUSEPL_ERROR_READING_FUSE_CNTRL 0x1200 Error reading fuse control. XSK_EFUSEPL_ERROR_DATA_PROGRAMMING_NOT_ALLOWED 0x1300 Data programming not allowed. XSK_EFUSEPL_ERROR_FUSE_CTRL_WRITE_NOT_ALLOWED 0x1400 Fuse control write is disabled. XSK_EFUSEPL_ERROR_READING_FUSE_AES_ROW 0x1500 Error reading fuse AES row. XSK_EFUSEPL_ERROR_AES_ROW_NOT_EMPTY 0x1600 AES row is not empty. XSK_EFUSEPL_ERROR_PROGRAMMING_FUSE_AES_ROW 0x1700 Error programming fuse AES row. XSK_EFUSEPL_ERROR_READING_FUSE_USER_DATA_ROW 0x1800 Error reading fuse user row. XSK_EFUSEPL_ERROR_USER_DATA_ROW_NOT_EMPTY 0x1900 User row is not empty. XSK_EFUSEPL_ERROR_PROGRAMMING_FUSE_DATA_ROW 0x1A00 Error programming fuse user row. XSK_EFUSEPL_ERROR_PROGRAMMING_FUSE_CNTRL_ROW 0x1B00 Error programming fuse control row. XSK_EFUSEPL_ERROR_XADC 0x1C00 XADC error. XSK_EFUSEPL_ERROR_INVALID_REF_CLK 0x3000 Invalid reference clock. XSK_EFUSEPL_ERROR_FUSE_SEC_WRITE_NOT_ALLOWED 0x1D00 Error in programming secure block. XSK_EFUSEPL_ERROR_READING_FUSE_STATUS 0x1E00 Error in reading FUSE status. 372

373 XSK_EFUSEPL_ERROR_FUSE_BUSY Fuse busy. 0x1F00 XSK_EFUSEPL_ERROR_READING_FUSE_RSA_ROW Error in reading FUSE RSA block. XSK_EFUSEPL_ERROR_TIMER_INTIALISE_ULTRA Error in initiating Timer. XSK_EFUSEPL_ERROR_READING_FUSE_SEC Error in reading FUSE secure bits. 0x2300 XSK_EFUSEPL_ERROR_PRGRMG_FUSE_SEC_ROW Error in programming Secure bits of efuse. XSK_EFUSEPL_ERROR_PRGRMG_USER_KEY Error in programming 32 bit user key. 0x4000 XSK_EFUSEPL_ERROR_PRGRMG_128BIT_USER_KEY Error in programming 128 bit User key. XSK_EFUSEPL_ERROR_PRGRMG_RSA_HASH Error in programming RSA hash. PS efuse Error Codes XSK_EFUSEPS_ERROR_NONE 0 No error. 0x8000 XSK_EFUSEPS_ERROR_ADDRESS_XIL_RESTRICTED Address is restricted. 0x2000 0x2200 0x2500 0x5000 0x01 XSK_EFUSEPS_ERROR_READ_TMEPERATURE_OUT_OF_RANGE Temperature obtained from XADC is out of range. XSK_EFUSEPS_ERROR_READ_VCCPAUX_VOLTAGE_OUT_OF_RANGE VCCAUX obtained from XADC is out of range. XSK_EFUSEPS_ERROR_READ_VCCPINT_VOLTAGE_OUT_OF_RANGE VCCINT obtained from XADC is out of range. XSK_EFUSEPS_ERROR_WRITE_TEMPERATURE_OUT_OF_RANGE Temperature obtained from XADC is out of range. 0x02 XSK_EFUSEPS_ERROR_WRITE_VCCPAUX_VOLTAGE_OUT_OF_RANGE VCCAUX obtained from XADC is out of range. XSK_EFUSEPS_ERROR_WRITE_VCCPINT_VOLTAGE_OUT_OF_RANGE VCCINT obtained from XADC is out of range. XSK_EFUSEPS_ERROR_VERIFICATION Verification error. 0x08 XSK_EFUSEPS_ERROR_RSA_HASH_ALREADY_PROGRAMMED RSA hash was already programmed. XSK_EFUSEPS_ERROR_CONTROLLER_MODE Controller mode error 0x0A 0x09 0x05 0x03 0x04 0x06 0x07 373

374 XSK_EFUSEPS_ERROR_REF_CLOCK 0x0B Reference clock not between 20 to 60 MHz XSK_EFUSEPS_ERROR_READ_MODE 0x0C Not supported read mode XSK_EFUSEPS_ERROR_XADC_CONFIG 0x0D XADC configuration error. XSK_EFUSEPS_ERROR_XADC_INITIALIZE 0x0E XADC initialization error. XSK_EFUSEPS_ERROR_XADC_SELF_TEST 0x0F XADC self-test failed. XSK_EFUSEPS_ERROR_PARAMETER_NULL Utils Error Codes. 0x10 Passed parameter null. XSK_EFUSEPS_ERROR_STRING_INVALID 0x20 Passed string is invalid. XSK_EFUSEPS_ERROR_AES_ALREADY_PROGRAMMED 0x12 AES key is already programmed. XSK_EFUSEPS_ERROR_SPKID_ALREADY_PROGRAMMED 0x13 SPK ID is already programmed. XSK_EFUSEPS_ERROR_PPK0_HASH_ALREADY_PROGRAMMED 0x14 PPK0 hash is already programmed. XSK_EFUSEPS_ERROR_PPK1_HASH_ALREADY_PROGRAMMED 0x15 PPK1 hash is already programmed. XSK_EFUSEPS_ERROR_PROGRAMMING_TBIT_PATTERN 0x16 Error in programming TBITS. XSK_EFUSEPS_ERROR_BEFORE_PROGRAMMING 0x0080 Error occurred before programming. XSK_EFUSEPS_ERROR_PROGRAMMING 0x00A0 Error in programming efuse. XSK_EFUSEPS_ERROR_READ 0x00B0 Error in reading. XSK_EFUSEPS_ERROR_PS_STRUCT_NULL XSKEfuse_Write/Read()common error codes. 0x8100 PS structure pointer is null. XSK_EFUSEPS_ERROR_XADC_INIT 0x8200 XADC initialization error. XSK_EFUSEPS_ERROR_CONTROLLER_LOCK 0x8300 PS efuse controller is locked. XSK_EFUSEPS_ERROR_EFUSE_WRITE_PROTECTED 0x8400 PS efuse is write protected. XSK_EFUSEPS_ERROR_CONTROLLER_CONFIG 0x8500 Controller configuration error. XSK_EFUSEPS_ERROR_PS_PARAMETER_WRONG 0x8600 PS efuse parameter is not TRUE/FALSE. 374

375 XSK_EFUSEPS_ERROR_WRITE_128K_CRC_BIT 0x9100 Error in enabling 128K CRC. XSK_EFUSEPS_ERROR_WRITE_NONSECURE_INITB_BIT 0x9200 Error in programming NON secure bit. XSK_EFUSEPS_ERROR_WRITE_UART_STATUS_BIT 0x9300 Error in writing UART status bit. XSK_EFUSEPS_ERROR_WRITE_RSA_HASH 0x9400 Error in writing RSA key. XSK_EFUSEPS_ERROR_WRITE_RSA_AUTH_BIT 0x9500 Error in enabling RSA authentication bit. XSK_EFUSEPS_ERROR_WRITE_WRITE_PROTECT_BIT 0x9600 Error in writing write-protect bit. XSK_EFUSEPS_ERROR_READ_HASH_BEFORE_PROGRAMMING Check RSA key before trying to program. XSK_EFUSEPS_ERROR_WRTIE_DFT_JTAG_DIS_BIT 0x9800 Error in programming DFT JTAG disable bit. XSK_EFUSEPS_ERROR_WRTIE_DFT_MODE_DIS_BIT 0x9900 Error in programming DFT MODE disable bit. XSK_EFUSEPS_ERROR_WRTIE_AES_CRC_LK_BIT 0x9A00 Error in enabling AES's CRC check lock. XSK_EFUSEPS_ERROR_WRTIE_AES_WR_LK_BIT 0x9B00 Error in programming AES write lock bit. XSK_EFUSEPS_ERROR_WRTIE_USE_AESONLY_EN_BIT 0x9C00 Error in programming use AES only bit. XSK_EFUSEPS_ERROR_WRTIE_BBRAM_DIS_BIT 0x9D00 Error in programming BBRAM disable bit. XSK_EFUSEPS_ERROR_WRTIE_PMU_ERR_DIS_BIT 0x9E00 Error in programming PMU error disable bit. XSK_EFUSEPS_ERROR_WRTIE_JTAG_DIS_BIT 0x9F00 Error in programming JTAG disable bit. XSK_EFUSEPS_ERROR_READ_RSA_HASH 0xA100 Error in reading RSA key. XSK_EFUSEPS_ERROR_WRONG_TBIT_PATTERN 0xA200 Error in programming TBIT pattern. XSK_EFUSEPS_ERROR_WRITE_AES_KEY 0xA300 Error in programming AES key. XSK_EFUSEPS_ERROR_WRITE_SPK_ID 0xA400 Error in programming SPK ID. XSK_EFUSEPS_ERROR_WRITE_USER_KEY 0xA500 Error in programming USER key. XSK_EFUSEPS_ERROR_WRITE_PPK0_HASH 0xA600 Error in programming PPK0 hash. 0x

376 XSK_EFUSEPS_ERROR_WRITE_PPK1_HASH 0xA700 Error in programming PPK1 hash. XSK_EFUSEPS_ERROR_CACHE_LOAD 0xB000 Error in re-loading CACHE. XSK_EFUSEPS_ERROR_WRITE_USER0_FUSE 0xC000 Error in programming USER 0 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER1_FUSE 0xC100 Error in programming USER 1 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER2_FUSE 0xC200 Error in programming USER 2 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER3_FUSE 0xC300 Error in programming USER 3 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER4_FUSE 0xC400 Error in programming USER 4 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER5_FUSE 0xC500 Error in programming USER 5 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER6_FUSE 0xC600 Error in programming USER 6 Fuses. XSK_EFUSEPS_ERROR_WRITE_USER7_FUSE 0xC700 Error in programming USER 7 Fuses. XSK_EFUSEPS_ERROR_WRTIE_USER0_LK_BIT 0xC800 Error in programming USER 0 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER1_LK_BIT 0xC900 Error in programming USER 1 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER2_LK_BIT 0xCA00 Error in programming USER 2 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER3_LK_BIT 0xCB00 Error in programming USER 3 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER4_LK_BIT 0xCC00 Error in programming USER 4 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER5_LK_BIT 0xCD00 Error in programming USER 5 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER6_LK_BIT 0xCE00 Error in programming USER 6 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_USER7_LK_BIT 0xCF00 Error in programming USER 7 fuses lock bit. XSK_EFUSEPS_ERROR_WRTIE_PROG_GATE0_DIS_BIT 0xD000 Error in programming PROG_GATE0 disabling bit. XSK_EFUSEPS_ERROR_WRTIE_PROG_GATE1_DIS_BIT 0xD100 Error in programming PROG_GATE1 disabling bit. XSK_EFUSEPS_ERROR_WRTIE_PROG_GATE2_DIS_BIT 0xD200 Error in programming PROG_GATE2 disabling bit. 376

377 XSK_EFUSEPS_ERROR_WRTIE_SEC_LOCK_BIT 0xD300 Error in programming SEC_LOCK bit. XSK_EFUSEPS_ERROR_WRTIE_PPK0_WR_LK_BIT 0xD400 Error in programming PPK0 write lock bit. XSK_EFUSEPS_ERROR_WRTIE_PPK0_RVK_BIT 0xD500 Error in programming PPK0 revoke bit. XSK_EFUSEPS_ERROR_WRTIE_PPK1_WR_LK_BIT 0xD600 Error in programming PPK1 write lock bit. XSK_EFUSEPS_ERROR_WRTIE_PPK1_RVK_BIT 0xD700 Error in programming PPK0 revoke bit. XSK_EFUSEPS_ERROR_WRITE_PUF_SYN_INVLD 0xD800 Error while programming the PUF syndrome invalidate bit. XSK_EFUSEPS_ERROR_WRITE_PUF_SYN_WRLK 0xD900 Error while programming Syndrome write lock bit. XSK_EFUSEPS_ERROR_WRITE_PUF_SYN_REG_DIS 0xDA00 Error while programming PUF syndrome register disable bit. XSK_EFUSEPS_ERROR_PUF_INVALID_REG_MODE 0xE000 Error when PUF registration is requested with invalid registration mode. XSK_EFUSEPS_ERROR_PUF_REG_WO_AUTH 0xE100 Error when write not allowed without authentication enabled. XSK_EFUSEPS_ERROR_PUF_REG_DISABLED 0xE200 Error when trying to do PUF registration and when PUF registration is disabled. XSK_EFUSEPS_ERROR_PUF_INVALID_REQUEST 0xE300 Error when an invalid mode is requested. XSK_EFUSEPS_ERROR_PUF_DATA_ALREADY_PROGRAMMED 0xE400 Error when PUF is already programmed in efuse. XSK_EFUSEPS_ERROR_PUF_DATA_OVERFLOW 0xE500 Error when an over flow occurs. XSK_EFUSEPS_ERROR_CMPLTD_EFUSE_PRGRM_WITH_ERR 0x10000 efuse programming is completed with temp and vol read errors. XSK_EFUSEPS_ERROR_FUSE_PROTECTED 0x Requested efuse is write protected. XSK_EFUSEPS_ERROR_USER_BIT_CANT_REVERT 0x Already programmed user FUSE bit cannot be reverted. Zynq UltraScale+ MPSoC BBRAM PS Error Codes XSK_ZYNQMP_BBRAMPS_ERROR_NONE 0 No error. XSK_ZYNQMP_BBRAMPS_ERROR_IN_PRGRMG_ENABLE If this error is occurred programming is not possible. 0x01 377

378 XSK_ZYNQMP_BBRAMPS_ERROR_IN_CRC_CHECK 0xB000 If this error is occurred programming is done but CRC check is failed. XSK_ZYNQMP_BBRAMPS_ERROR_IN_PRGRMG 0xC000 programming of key is failed. 378

379 Status Codes For Zynq and UltraScale, the status in the xilskey_efuse_example.c file is conveyed through a UART or reboot status register in the following format: 0xYYYYZZZZ, where: YYYY represents the PS efuse Status. ZZZZ represents the PL efuse Status. The table below lists the status codes. Status Code Values 0x0000ZZZZ 0xYYYY0000 0xFFFF0000 0x0000FFFF 0xFFFFZZZZ 0xYYYYFFFF Description Represents PS efuse is successful and PL efuse process returned with error. Represents PL efuse is successful and PS efuse process returned with error. Represents PS efuse is not initiated and PL efuse is successful. Represents PL efuse is not initiated and PS efuse is successful. Represents PS efuse is not initiated and PL efuse is process returned with error. Represents PL efuse is not initiated and PS efuse is process returned with error. For Zynq UltraScale+ MPSoC, the status in the xilskey_bbramps_zynqmp_example.c, xilskey_puf_registration.c and xilskey_efuseps_zynqmp_example.c files is conveyed as 32 bit error code. Where Zero represents that no error has occurred and if the value is other than Zero, a 32 bit error code is returned. 379

380 Procedures This chapter provides detailed descriptions of the various procedures. Zynq efuse Writing Procedure Running from DDR as an Application This sequence is same as the existing flow described below. 1. Provide the required inputs in xilskey_input.h, then compile the SDK project. 2. Take the latest FSBL (ELF), stitch the <output>.elf generated to it (using the bootgen utility), and generate a bootable image. 3. Write the generated binary image into the flash device (for example: QSPI, NAND). 4. To burn the efuse key bits, execute the image. Zynq efuse Driver Compilation Procedure for OCM The procedure is as follows: 1. Open the linker script (lscript.ld) in the SDK project. 2. Map all the chapters to point to ps7_ram_0_s_axi_baseaddr instead of ps7_ddr_0_s_axi_baseaddr. For example, Click the Memory Region tab for the.text chapter and select ps7_ram_0_s_axi_baseaddr from the drop-down list. 3. Copy the ps7_init.c and ps7_init.h files from the hw_platform folder into the example folder. 4. In xilskey_efuse_example.c, un-comment the code that calls the ps7_init() routine. 5. Compile the project. The <Project name>.elf file is generated and is executed out of OCM. When executed, this example displays the success/failure of the efuse application in a display message via UART (if UART is present and initialized) or the reboot status register. 380

381 UltraScale efuse Access Procedure The procedure is as follows: 1. After providing the required inputs in xilskey_input.h, compile the project. 2. Generate a memory mapped interface file using TCL command write_mem_info $Outfilename 3. Update memory has to be done using the tcl command updatemem. updatemem -meminfo $file.mmi -data $Outfilename.elf -bit $design.bit -proc design_1_i/microblaze_0 -out $Final.bit 4. Program the board using $Final.bit bitstream. 5. Output can be seen in UART terminal. UltraScale BBRAM Access Procedure The procedure is as follows: 1. After providing the required inputs in the xilskey_bbram_ultrascale_input.h file, compile the project. 2. Generate a memory mapped interface file using TCL command write_mem_info $Outfilename 3. Update memory has to be done using the tcl command updatemem: updatemem -meminfo $file.mmi -data $Outfilename.elf -bit $design.bit -proc design_1_i/microblaze_0 -out $Final.bit 4. Program the board using $Final.bit bitstream. 5. Output can be seen in UART terminal. 381

382 Appendix I: XilPM Library v

383 XilPM APIs Overview Xilinx Power Management(XilPM) provides Embedded Energy Management Interface (EEMI) APIs for power management on Zynq UltraScale+ MPSoC. For more details about power management on Zynq Ultrascale+ MPSoC, see the Zynq UltraScale+ MPSoC Power Management User Guide (UG1199). For more details about EEMI, see the Embedded Energy Management Interface (EEMI) API User Guide(UG1200). Modules Error Status Data Structures struct XPm_Notifier struct XPm_NodeStatus Functions XStatus XPm_InitXilpm (XIpiPsu IpiInst) void XPm_SuspendFinalize () enum XPmBootStatus XPm_GetBootStatus () XStatus XPm_RequestSuspend (const enum XPmNodeId node, const enum XPmRequestAck ack, const u32 latency, const u8 state) XStatus XPm_SelfSuspend (const enum XPmNodeId node, const u32 latency, const u8 state, const u64 address) XStatus XPm_ForcePowerDown (const enum XPmNodeId node, const enum XPmRequestAck ack) XStatus XPm_AbortSuspend (const enum XPmAbortReason reason) XStatus XPm_RequestWakeUp (const enum XPmNodeId node, const bool setaddress, const u64 address, const enum XPmRequestAck ack) XStatus XPm_SetWakeUpSource (const enum XPmNodeId target, const enum XPmNodeId wkup_node, const u8 enable) XStatus XPm_SystemShutdown (u32 type, u32 subtype) 383

384 XStatus XPm_SetConfiguration (const u32 address) void XPm_InitSuspendCb (const enum XPmSuspendReason reason, const u32 latency, const u32 state, const u32 timeout) void XPm_AcknowledgeCb (const enum XPmNodeId node, const XStatus status, const u32 oppoint) void XPm_NotifyCb (const enum XPmNodeId node, const u32 event, const u32 oppoint) XStatus XPm_RequestNode (const enum XPmNodeId node, const u32 capabilities, const u32 qos, const enum XPmRequestAck ack) XStatus XPm_ReleaseNode (const enum XPmNodeId node) XStatus XPm_SetRequirement (const enum XPmNodeId node, const u32 capabilities, const u32 qos, const enum XPmRequestAck ack) XStatus XPm_SetMaxLatency (const enum XPmNodeId node, const u32 latency) XStatus XPm_GetApiVersion (u32 version) XStatus XPm_GetNodeStatus (const enum XPmNodeId node, XPm_NodeStatus const nodestatus) XStatus XPm_RegisterNotifier (XPm_Notifier const notifier) XStatus XPm_UnregisterNotifier (XPm_Notifier const notifier) XStatus XPm_GetOpCharacteristic (const enum XPmNodeId node, const enum XPmOpCharType type, u32 const result) XStatus XPm_ResetAssert (const enum XPmReset reset, const enum XPmResetAction assert) XStatus XPm_ResetGetStatus (const enum XPmReset reset, u32 status) XStatus XPm_MmioWrite (const u32 address, const u32 mask, const u32 value) XStatus XPm_MmioRead (const u32 address, u32 const value) Data Structure Documentation struct XPm_Notifier Notifier structure registered with a callback by application. Data Fields void( const callback )(XPm_Notifier const notifier) enum XPmNodeId node enum XPmNotifyEvent event u32 flags volatile u32 oppoint volatile u32 received XPm_Notifier next 384

385 Field Documentation void( const callback) (XPm_Notifier const notifier) Custom callback handler to be called when the notification is received. The custom handler would execute from interrupt context, it shall return quickly and must not block! (enables event-driven notifications) enum XPmNodeId node Node argument (the node to receive notifications about) enum XPmNotifyEvent event Event argument (the event type to receive notifications about) u32 flags Flags volatile u32 oppoint Operating point of node in question. Contains the value updated when the last event notification is received. User shall not modify this value while the notifier is registered. volatile u32 received How many times the notification has been received - to be used by application (enables polling). User shall not modify this value while the notifier is registered. XPm_Notifier next Pointer to next notifier in linked list. Must not be modified while the notifier is registered. User shall not ever modify this value. struct XPm_NodeStatus Data structure containing node status information. Data Fields u32 status u32 requirements u32 usage Field Documentation u32 status Node power state u32 requirements Current requirements asserted on the node (slaves only) u32 usage Usage information (which master is currently using the slave) Function Documentation XStatus XPm_InitXilpm ( XIpiPsu IpiInst ) Initialize xilpm library. 385

386 IpiInst Pointer to IPI driver instance XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None void XPm_SuspendFinalize ( void ) This Function waits for PMU to finish all previous API requests sent by the PU and performs client specific actions to finish suspend procedure (e.g. execution of wfi instruction on A53 and R5 processors). This function should not return if the suspend procedure is successful. enum XPmBootStatus XPm_GetBootStatus ( void ) This Function returns information about the boot reason. If the boot is not a system startup but a resume, power down request bitfield for this processor will be cleared. processor boot status PM_RESUME : If the boot reason is because of system resume. PM_INITIAL_BOOT : If this boot is the initial system startup. None XStatus XPm_RequestSuspend ( const enum XPmNodeId target, const enum XPmRequestAck ack, const u32 latency, const u8 state ) This function is used by a PU to request suspend of another PU. This call triggers the power management controller to notify the PU identified by 'nodeid' that a suspend has been requested. This will allow said PU to gracefully suspend itself by calling XPm_SelfSuspend for each of its CPU nodes, or else call XPm_AbortSuspend with its PU node as argument and specify the reason. 386

387 target ack latency state Node ID of the PU node to be suspended Requested acknowledge type Maximum wake-up latency requirement in us(micro sec) Instead of specifying a maximum latency, a PU can also explicitly request a certain power state. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code If 'ack' is set to PM_ACK_CB_STANDARD, the requesting PU will be notified upon completion of suspend or if an error occurred, such as an abort or a timeout. XStatus XPm_SelfSuspend ( const enum XPmNodeId nid, const u32 latency, const u8 state, const u64 address ) This function is used by a CPU to declare that it is about to suspend itself. After the PMU processes this call it will wait for the requesting CPU to complete the suspend procedure and become ready to be put into a sleep state. nid latency state address Node ID of the CPU node to be suspended. Maximum wake-up latency requirement in us(microsecs) Instead of specifying a maximum latency, a CPU can also explicitly request a certain power state. Address from which to resume when woken up. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code This is a blocking call, it will return only once PMU has responded XStatus XPm_ForcePowerDown ( const enum XPmNodeId target, const enum XPmRequestAck ack ) One PU can request a forced poweroff of another PU or its power island or power domain. This can be used for killing an unresponsive PU, in which case all resources of that PU will be automatically released. 387

388 target ack Node ID of the PU node or power island/domain to be powered down. Requested acknowledge type XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code Force power down may not be requested by a PU for itself. XStatus XPm_AbortSuspend ( const enum XPmAbortReason reason ) This function is called by a CPU after a XPm_SelfSuspend call to notify the power management controller that CPU has aborted suspend or in response to an init suspend request when the PU refuses to suspend. reason Reason code why the suspend can not be performed or completed ABORT_REASON_WKUP_EVENT : local wakeup-event received ABORT_REASON_PU_BUSY : PU is busy ABORT_REASON_NO_PWRDN : no external powerdown supported ABORT_REASON_UNKNOWN : unknown error during suspend procedure XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code Calling PU expects the PMU to abort the initiated suspend procedure. This is a non-blocking call without any acknowledge. XStatus XPm_RequestWakeUp ( const enum XPmNodeId target, const bool setaddress, const u64 address, const enum XPmRequestAck ack ) This function can be used to request power up of a CPU node within the same PU, or to power up another PU. 388

389 target setaddress Node ID of the CPU or PU to be powered/woken up. Specifies whether the start address argument is being passed. 0 : do not set start address 1 : set start address address ack Address from which to resume when woken up. Will only be used if set_address is 1. Requested acknowledge type XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code If acknowledge is requested, the calling PU will be notified by the power management controller once the wake-up is completed. XStatus XPm_SetWakeUpSource ( const enum XPmNodeId target, const enum XPmNodeId wkup_node, const u8 enable ) This function is called by a PU to add or remove a wake-up source prior to going to suspend. The list of wake sources for a PU is automatically cleared whenever the PU is woken up or when one of its CPUs aborts the suspend procedure. target wkup_node enable Node ID of the target to be woken up. Node ID of the wakeup device. Enable flag: 1 : the wakeup source is added to the list 0 : the wakeup source is removed from the list XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code 389

390 Declaring a node as a wakeup source will ensure that the node will not be powered off. It also will cause the PMU to configure the GIC Proxy accordingly if the FPD is powered off. XStatus XPm_SystemShutdown ( u32 type, u32 subtype ) This function can be used by a privileged PU to shut down or restart the complete device. restart Should the system be restarted automatically? PM_SHUTDOWN : no restart requested, system will be powered off permanently PM_RESTART : restart is requested, system will go through a full reset XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code In either case the PMU will call XPm_InitSuspendCb for each of the other PUs, allowing them to gracefully shut down. If a PU is asleep it will be woken up by the PMU. The PU making the XPm_SystemShutdown should perform its own suspend procedure after calling this API. It will not receive an init suspend callback. XStatus XPm_SetConfiguration ( const u32 address ) This function is called to configure the power management framework. The call triggers power management controller to load the configuration object and configure itself according to the content of the object. address Start address of the configuration object XST_SUCCESS if successful, otherwise an error code The provided address must be in 32-bit address space which is accessible by the PMU. 390

391 void XPm_InitSuspendCb ( const enum XPmSuspendReason reason, const u32 latency, const u32 state, const u32 timeout ) Callback function to be implemented in each PU, allowing the power management controller to request that the PU suspend itself. reason Suspend reason: SUSPEND_REASON_PU_REQ : Request by another PU SUSPEND_REASON_ALERT : Unrecoverable SysMon alert SUSPEND_REASON_SHUTDOWN : System shutdown SUSPEND_REASON_RESTART : System restart latency state timeout Maximum wake-up latency in us(micro secs). This information can be used by the PU to decide what level of context saving may be required. Targeted sleep/suspend state. Timeout in ms, specifying how much time a PU has to initiate its suspend procedure before it's being considered unresponsive. None If the PU fails to act on this request the power management controller or the requesting PU may choose to employ the forceful power down option. void XPm_AcknowledgeCb ( const enum XPmNodeId node, const XStatus status, const u32 oppoint ) This function is called by the power management controller in response to any request where an acknowledge callback was requested, i.e. where the 'ack' argument passed by the PU was REQUEST_ACK_CB_STANDARD. 391

392 node status ID of the component or sub-system in question. Status of the operation: OK: the operation completed successfully ERR: the requested operation failed oppoint Operating point of the node in question None None void XPm_NotifyCb ( const enum XPmNodeId node, const u32 event, const u32 oppoint ) This function is called by the power management controller if an event the PU was registered for has occurred. It will populate the notifier data structure passed when calling XPm_RegisterNotifier. node event oppoint ID of the node the event notification is related to. ID of the event Current operating state of the node. None None XStatus XPm_RequestNode ( const enum XPmNodeId node, const u32 capabilities, const u32 qos, const enum XPmRequestAck ack ) Used to request the usage of a PM-slave. Using this API call a PU requests access to a slave device and asserts its requirements on that device. Provided the PU is sufficiently privileged, the PMU will enable access 392

393 to the memory mapped region containing the control registers of that device. For devices that can only be serving a single PU, any other privileged PU will now be blocked from accessing this device until the node is released. node capabilities Node ID of the PM slave requested Slave-specific capabilities required, can be combined PM_CAP_ACCESS : full access / functionality PM_CAP_CONTEXT : preserve context PM_CAP_WAKEUP : emit wake interrupts qos ack Quality of Service (0-100) required Requested acknowledge type XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None XStatus XPm_ReleaseNode ( const enum XPmNodeId node ) This function is used by a PU to release the usage of a PM slave. This will tell the power management controller that the node is no longer needed by that PU, potentially allowing the node to be placed into an inactive state. node Node ID of the PM slave. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code 393

394 None XStatus XPm_SetRequirement ( const enum XPmNodeId nid, const u32 capabilities, const u32 qos, const enum XPmRequestAck ack ) This function is used by a PU to announce a change in requirements for a specific slave node which is currently in use. nid capabilities qos ack Node ID of the PM slave. Slave-specific capabilities required. Quality of Service (0-100) required. Requested acknowledge type XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code If this function is called after the last awake CPU within the PU calls SelfSuspend, the requirement change shall be performed after the CPU signals the end of suspend to the power management controller, (e.g. WFI interrupt). XStatus XPm_SetMaxLatency ( const enum XPmNodeId node, const u32 latency ) This function is used by a PU to announce a change in the maximum wake-up latency requirements for a specific slave node currently used by that PU. node latency Node ID of the PM slave. Maximum wake-up latency required. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code 394

395 Setting maximum wake-up latency can constrain the set of possible power states a resource can be put into. XStatus XPm_GetApiVersion ( u32 version ) This function is used to request the version number of the API running on the power management controller. version the API 32-bit version number. 0 if no PM firmware present. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None XStatus XPm_GetNodeStatus ( const enum XPmNodeId node, XPm_NodeStatus const nodestatus ) This function is used to obtain information about the current state of a component. The caller must pass a pointer to an XPm_NodeStatus structure, which must be pre-allocated by the caller. 395

396 node nodestatus ID of the component or sub-system in question. Used to return the complete status of the node. status - The current power state of the requested node. For CPU nodes: 0 : if CPU is powered down, 1 : if CPU is active (powered up), 2 : if CPU is suspending (powered up) For power islands and power domains: 0 : if island is powered down, 1 : if island is powered up For PM slaves: 0 : if slave is powered down, 1 : if slave is powered up, 2 : if slave is in retention requirement - Slave nodes only: current requirements the requesting PU has requested of the node. usage - Slave nodes only: current usage status of the node: 0 : node is not used by any PU, 1 : node is used by caller exclusively, 2 : node is used by other PU(s) only, 3 : node is used by caller and by other PU(s) XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None XStatus XPm_RegisterNotifier ( XPm_Notifier const notifier ) A PU can call this function to request that the power management controller call its notify callback whenever a qualifying event occurs. One can request to be notified for a specific or any event related to a specific node. 396

397 notifier Pointer to the notifier object to be associated with the requested notification. The notifier object contains the following data related to the notification: nodeid : ID of the node to be notified about, eventid : ID of the event in question, '-1' denotes all events ( - EVENT_STATE_CHANGE, EVENT_ZERO_USERS, EVENT_ERROR_CONDITION), wake : true: wake up on event, false: do not wake up (only notify if awake), no buffering/queueing callback : Pointer to the custom callback function to be called when the notification is available. The callback executes from interrupt context, so the user must take special care when implementing the callback. Callback is optional, may be set to NULL. received : Variable indicating how many times the notification has been received since the notifier is registered. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code The caller shall initialize the notifier object before invoking the XPm_RegisteredNotifier function. While notifier is registered, the notifier object shall not be modified by the caller. XStatus XPm_UnregisterNotifier ( XPm_Notifier const notifier ) A PU calls this function to unregister for the previously requested notifications. notifier Pointer to the notifier object associated with the previously requested notification XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None 397

398 XStatus XPm_GetOpCharacteristic ( const enum XPmNodeId node, const enum XPmOpCharType type, u32 const result ) Call this function to request the power management controller to return information about an operating characteristic of a component. node type ID of the component or sub-system in question. Type of operating characteristic requested: power (current power consumption), latency (current latency in us to return to active state), temperature (current temperature), result Used to return the requested operating characteristic. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None XStatus XPm_ResetAssert ( const enum XPmReset reset, const enum XPmResetAction assert ) This function is used to assert or release reset for a particular reset line. Alternatively a reset pulse can be requested as well. reset assert ID of the reset line Identifies action: PM_RESET_ACTION_RELEASE : release reset, PM_RESET_ACTION_ASSERT : assert reset, PM_RESET_ACTION_PULSE : pulse reset, 398

399 XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code None XStatus XPm_ResetGetStatus ( const enum XPmReset reset, u32 status ) Call this function to get the current status of the selected reset line. reset status Reset line Status of specified reset (true - asserted, false - released) 1/XST_FAILURE for 'asserted' or 0/XST_SUCCESS for 'released'. None XStatus XPm_MmioWrite ( const u32 address, const u32 mask, const u32 value ) Call this function to write a value directly into a register that isn't accessible directly, such as registers in the clock control unit. This call is bypassing the power management logic. The permitted addresses are subject to restrictions as defined in the PCW configuration. address mask value Physical 32-bit address of memory mapped register to write to. 32-bit value used to limit write to specific bits in the register. Value to write to the register bits specified by the mask. XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code If the access isn't permitted this function returns an error code. 399

400 XStatus XPm_MmioRead ( const u32 address, u32 const value ) Call this function to read a value from a register that isn't accessible directly. The permitted addresses are subject to restrictions as defined in the PCW configuration. address value Physical 32-bit address of memory mapped register to read from. the 32-bit value read from the register XST_SUCCESS if successful else XST_FAILURE or an error code or a reason code If the access isn't permitted this function returns an error code. Error Status Overview This section lists the Power management specific return error statuses. Macros #define XST_PM_INTERNAL 2000L #define XST_PM_CONFLICT 2001L #define XST_PM_NO_ACCESS 2002L #define XST_PM_INVALID_NODE 2003L #define XST_PM_DOUBLE_REQ 2004L #define XST_PM_ABORT_SUSPEND 2005L #define XST_PM_TIMEOUT 2006L #define XST_PM_NODE_USED 2007L 400

401 Macro Definition Documentation #define XST_PM_INTERNAL 2000L An internal error occurred while performing the requested operation. #define XST_PM_CONFLICT 2001L Conflicting requirements have been asserted when more than one processing cluster is using the same PM slave. #define XST_PM_NO_ACCESS 2002L The processing cluster does not have access to the requested node or operation. #define XST_PM_INVALID_NODE 2003L The API function does not apply to the node passed as argument. #define XST_PM_DOUBLE_REQ 2004L A processing cluster has already been assigned access to a PM slave and has issued a duplicate request for that PM slave. #define XST_PM_ABORT_SUSPEND 2005L The target processing cluster has aborted suspend. #define XST_PM_TIMEOUT 2006L A timeout occurred while performing the requested operation. #define XST_PM_NODE_USED 2007L Slave request cannot be granted since node is non-shareable and used. 401

402 Appendix J: XilFPGA Library v

403 Overview The XilFPGA library provides an interface to the Linux or bare-metal users for configuring the programmable logic (PL) over PCAP from PS. The library is designed for Zynq UltraScale+ MPSoC to run on top of Xilinx standalone BSPs. It is tested for A53, R5 and MicroBlaze. In the most common use case, we expect users to run this library on PMU MicroBlaze with PMUFW to serve requests from Linux for bitstream programming. In this release, the XilFPGA library supports full, encrypted, authenticated bitstream download. In subsequent releases, the library may support partial bitstream loading. Xilfpga library Interface modules Xilfpga library uses the below major components to configure the PL through PS. Processor Configuration Access Port (PCAP) The processor configuration access port (PCAP) is used to configure the programmable logic (PL) through the PS. CSU DMA driver The CSU DMA driver is used to transfer the actual Bit stream file for the PS to PL after PCAP initialization. Xilsecure_library The LibXilSecure library provides APIs to access secure hardware on the Zynq UltraScale+ MPSoC devices. This library includes: SHA-256 hash function AES for symmetric key encryption RSA for authentication 403

404 The current version of library supports only Zynq UltraScale+ MPSoC devices. The XilFPGA library is capable of loading only.bin format files into PL. The library will not support the other file formats. Xilsecure_library is required only for the below use cases: Encrypted bit-stream loading. Authenticated bit-stream loading For Zynq UltraScale+ MPSoC devices, the required OCM memory for authentication bit-stream loading is 68Kb. Design Summary Xilfpga library acts as a bridge between the user application and the PL device. It provides the required functionality to the user application for configuring the PL Device with the required bit-stream. The figure below illustrates an implementation where the Xilfpga library needs the CSU DMA driver APIs to transfer the bit-stream from the DDR to the PL region. The Xilfpga library also needs the XilSecure library APIs to support while programming the authenticated and the encrypted bitstream files. Figure 31.1: XilFPGA Design Summary 404