﻿<<<< HWLib Example Program >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

-- 情報 ----------------------------------------------------------------
ファイル名：		sample_cache_manage.c
作成日：			2013/12/17
更新日：			2014/01/29	"体裁修正" 
更新日：			2014/04/21	"u-boot-spl.axf を v13.1 で生成したファイルに変更"
更新日：			2014/07/29	"SoC EDS 14.0 用に Makefile を修正"
更新日：			2014/08/18	"誤植訂正、操作説明の表示を追加"
更新日：			2015/06/25	"SoC EDS 15.0 用の HWLib に対応。文字コードを UTF-8 に変更 (Linux の日本語表示)。
						 		割込みログの実装を改善 (割込み利用の場合のみ)"
更新日：			2016/03/14	"デバッグコンフィギュレーション設定変更（レジスタ定義読み込み）"
更新日：			2016/03/29	"デバッグコンフィギュレーション設定変更（レジスタ定義読み込み） ファイルの修正"
更新日：			2016/07/08	"マルチボード対応（Helio/Atlas/Sodia/C5SoCDevKit）"
更新日：			2017/05/22	"Arria 10 Soc DevKit 対応, DS-5 レジスタビュー表示にも対応"
更新日：			2018/07/02	"All in One ベアメタル・アプリケーション v17.1 への対応を実施"
更新日：			2019/02/25	"All in One ベアメタル・アプリケーション v18.1 への対応を実施"
更新日：			2021/04/23	"SoC EDS v20.1 / Arm DS 2020.1 への対応を実施、Helio は更新対象外(v18.1 用を使用)"
更新日：			2025/07/29	"SoC EDS v20.1 / Arm DS 2024.1 への対応を実施"

確認 HWLib バージョン：	13.1 (SoC EDS 13.1)
確認 HWLib バージョン：	14.0 (SoC EDS 14.0 patch0.02)
確認 HWLib バージョン：	15.0 (SoC EDS Version: 15.0.1, Build: 60)
確認 HWLib バージョン：	15.1 (SoC EDS Version: 15.1.1, Build: 60)
確認 HWLib バージョン：	16.0 (SoC EDS Version: 16.0, Build: 211)
確認 HWLib バージョン：	16.1 (SoC EDS Version: 16.1.0, Build: 196)
確認 HWLib バージョン：	17.0 (SoC EDS Version: 17.0, Build: 595)
確認 HWLib バージョン：	17.1 (SoC EDS Version: 17.1, Build: 585)
確認 HWLib バージョン：	18.1 (SoC EDS Version: 18.1, Build: 625)
確認 HWLib バージョン：	github.com/altera-opensource - tag: rel_socfpga_v2020.10_21.03.01_pr
　　　　　　　　　　　　　Download: [ https://github.com/altera-fpga/u-boot-socfpga/releases/tag/rel_socfpga_v2020.10_21.03.01_pr ]
確認 HWLib バージョン：	github.com/altera-opensource - tag: rel_socfpga_v2024.01_24.11.03_pr
　　　　　　　　　　　　　Download: [ https://github.com/altera-fpga/u-boot-socfpga/releases/tag/rel_socfpga_v2024.01_24.11.03_pr ]

※ 本 HWLib Example を利用する場合には、プロジェクト 「ALT-HWLib-All-In-One_vXX.X_r○」 をインポートし、
　 TOP ディレクトリーに本 HWLib Example ファイルをコピーしてコンパイル対象とすることで、
　 Makefile を修正すること無く各種評価ができるようになっています（FPGA のコンフィギュレーションデータ等を共有するため）。

※ SoC EDS v13.1 以前のツールを利用する場合には、本サンプルに含まれる Makefile に下記変更を加えて下さい。
　【変更前】 CROSS_COMPILE := arm-altera-eabi-　　... SoC EDS v14.0 以降を利用の場合
　【変更後】 CROSS_COMPILE := arm-none-eabi-　　..... SoC EDS v13.1 以前を利用の場合
　 リンカスクリプト（cycloneV-dk-ram-hosted.ld）内に記述されるラベル（2 カ所）にも変更が必要な場合があります。
　【変更前】 __cs3_reset_cycloneV_dk_ram
　【変更後】 __cs3_reset_generic
　 他、HWLib のバージョン違いにより一部の API でコンパイルエラーが発生する場合があります。
　 その場合は、適宜サンプルコードを変更してご利用下さい。

**************************************************************************************
* Copyright (C) 2013-2025 MACNICA,Inc. All Rights Reserved.                          *
*   This software is licensed "AS IS".                                               *
*   Please perform use of this software by a user's own responsibility and expense.  *
*   It cannot guarantee in the maker side about the damage which occurred by the ab- *
*   ility not to use or use this software, and all damage that occurred secondarily. *
**************************************************************************************

※ 本サンプルでは、DS Intel SoC FPGA Edition (Altera Edition) のレジスタ・ビューには
　 標準では表示されない下記ペリフェラルのレジスタ表示に対応しています。
　  * DMA Controller（DMA-330）
　  * L2Cache Controller（L2C-310）
　  * Cortex-A9 MPCore 内蔵 SCU（Snoop Control Unit）
　  * Cortex-A9 MPCore 内蔵 Interrupt Controller（GIC: PL-390）
　  * Cortex-A9 MPCore 内蔵 Timer（Global Timer, Private Timer, Watchdog Timer）
　
　レジスタ・ビューのカスタマイズ方法は、マクニカサイトの技術情報をご参照ください。
　『Arm DS 活用テクニック ～レジスタ・ビュー［2/3］レジスタ定義の自作』
　 https://www.macnica.co.jp/business/semiconductor/articles/intel/115085 

※ config.mk ファイル内のシンボル定義を変更することで、ターゲットボードの選択が可能です。
　 下記から 1 行だけを選択します（その他の行は # でコメントアウトします）。
　#######################
　# Select Target Board #
　#######################
　TARGET_BOARD := atlas		← Atlas-SoC / DE0-Nano-SoC
　#TARGET_BOARD := sodia		← Mpression Sodia Evaluation Board 
　#TARGET_BOARD := c5socdk		← Cyclone V SoC Development Kit 
　#TARGET_BOARD := a10socdk		← Arria 10 SoC Development Kit 
　#TARGET_BOARD := de10nano		← DE10-Nano

※ 本サンプルでは、HPS 側の PUSH スイッチ 4 つと DIPSW (SLIDE) 4 つを
　 操作することでソフトウェアの動作を切り替える仕組みを実装しております。
　
　但し、ターゲットボードに Atlas-SoC / DE0-Nano-SoC / DE10-Nano を選択した場合、
　HPS 側には前述のスイッチが不足する状態となるため、以下の対応でご利用頂く実装としています。
　 * PUSHSW0 ... FPGA 側の PUSH BUTTON (KEY0, KEY1) を同時押し 
　 * PUSHSW1 ... FPGA 側の PUSH BUTTON (KEY0) を単押し
　 * PUSHSW2 ... FPGA 側の PUSH BUTTON (KEY1) を単押し
　 * PUSHSW3 ... HPS 側の USER PUSH BUTTON (KEY2) を単押し
　 * DIPSW[3:0] ... FPGA 側の SLIDE スイッチ (SW3, SW2, SW1, SW0) 
　
　Arria 10 SoC Development Kit を選択した場合は、全てのスイッチ（PUSH × 4、
　DIPSW (SLIDE) × 4）を HPS 側ではなく FPGA 側をご利用頂く実装としています。
　
　FPGA 側のスイッチを利用するため当該スイッチ用の PIO を実装した .sof にて
　事前に FPGA のコンフィギュレーションを行って頂く必要があります。

※ FPGA のコンフィギュレーション用の .sof ファイルは、DS ワークスペース以下
　 ALT-HWLib-All-In-One_vXX.X_r○\target_board の中に格納してあります。
　（必要に応じて Quartus Programmer 等で書き込みしてください）


-- 概要 ----------------------------------------------------------------
HWLib にて、下記のカテゴリに分類されている API を一通り動作させます。
	Cache Management API
	 ＋　System Level Cache Management API
	 ＋　L1 Cache Management API
	 ＋　L2 Cache Management API

上記カテゴリの全ての API を試行します。
また、Cache の効果を検証するために、要素数 8194×N(1～8) の配列を引数として、
memset 関数および下記 2 つの関数の実行時間を計測・表示させることができます。

void mul_f32a(float * __restrict a, float * __restrict b, float * __restrict p, int size){
	int i;
	for( i = 0; i < size; i++ )
	{
		p[i] = (float)a[i] * b[i];
	}
}

int verify(float *a, float *b, int size,  int place){
	int i;
	for( i = 0; i < size; i++ )
	{
		if((*a++) != (*b++)){
			return(i);
		}
	}
	return(size);
}



-- 使い方 --------------------------------------------------------------

　　①．アーカイブを SoC EDS (DS) へインポートします。
　　~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	１．SoC EDS（DS）のメニューから「ファイル(F) -> インポート(I)...」を実行します。
	　　※ 注意：SoC EDS (DS) は Embedded_Command_Shell から起動してください。
		↓
	２．インポートダイアログ上のインポート・ソースの選択(S)： として
	　　「一般 -> 既存プロジェクトをワークスペースへ」を選択して［次へ(N)>］を実行します。
		↓
	３．アーカイブ・ファイルの選択(A) のチェックを有効にして、
	　　［参照(R)...］ボタンから起動されるファイル選択ダイアログにて
	　　「ALT-HWLib-All-In-One_vXX.X_r○.tar.gz」を選択します。
		↓
	４．「終了(F)」を実行してインポートを完了します。
		↓
	５．ALT-HWLib-All-In-One_vXX.X_r○ の中に格納してある
	　　config.mk ファイル内の ENABLE_EXAMPLE_CACHE の定義を "1" に設定してプロジェクトをビルドすると、
	　　ターゲットボードの DIP スイッチを 「Command モード」 に設定してコンソールから "cache" コマンドを入力することにより、
	　　util/cmd.c 内から sample_cache_manage.c の sample_cache_manage_test_cmd() 関数がが呼び出されます。

　# ENABLE_EXAMPLE_CACHE   : sample_cache_manage.c
　ENABLE_EXAMPLE_CACHE     := 1


　　②．ALT-HWLib-All-In-One_vXX.X_r○ プロジェクトをビルドします。
　　~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	１．ALT-HWLib-All-In-One_vXX.X_r○ プロジェクトの config.mk を必要に応じて修正します。
		↓
	２．プロジェクト・エクスプローラ上で ALT-HWLib-All-In-One_vXX.X_r○
	　　の右クリックメニューから「プロジェクトのビルド(B)」を実行します。

　　③．デバッグを実行します。
　　~~~~~~~~~~~~~~~~~~~~~~~~
	１．SoC EDS（DS）のメニューから「実行(R) -> デバッグの構成(B)...」を実行します。
		↓
	２．デバッグの構成ダイアログ上で、左側のツリー上で
	　　「DSデバッガ -> ALT-HWLib-All-In-One_vXX.X_r○」が選択された状態にします。
		↓
	３．接続タブの［参照...］ボタンからデバッグハードウェアの選択ダイアログを起動して、
	　　適切な Connection を選択します。
	　　（例えば、Atlas ボードと USB-Blaster II 接続なら「DE-SoC on localhost[USB-1]:DE-SoC USB-1」）
		↓
	４．［デバッグ(D)］を実行すると、プログラムがロードされた後に sample_app.c 内の main() でブレイクします。
	　　以降、デバッガで動作をご確認下さい。　


-- 詳細（sample_cache_manage_test_cmd() 以降） --------------------------

◎ sample_cache_manage_test_cmd() 関数内の下記の記述にて、サンプルコードを呼び出しています。
　　//// Sample Function Call!!! |---->
　　printf(">>>> Execute sample_cache_manage_init(); !!! <<<<\r\n");
　　sample_cache_manage_init();
　　
　　printf(">>>> sample_cache_manage_test(); !!! <<<<\r\n");
　　sample_cache_manage_test_main();
　　//// Sample Function Call!!! <----|

◎ 各サンプル関数の概要を示します。
sample_cache_manage_init();
	→ ターゲット・ボードの HPS 用 DIPSW, PUSHSW のための GPIO 設定を行います（テストプログラムの操作用）
	
	→ L1 および L2 Cache を全て有効にする HWLib API を実行します。
	
	→ 動作確認用に割り込みコントローラ (GIC) の設定変更を行います。
	　 L2 Cache Combined IRQ “ALT_INT_INTERRUPT_L2_COMBINED_IRQ” を有効に設定します。
	　 上記の割り込みは L2 Cache Controller からの異常通知 (3 種類) を全て束ねた (OR) 条件で発行されます。
	　 本サンプルでは、Cache 異常を引き起こす仕組みは実装していません。
	　 何かしらの方法で Cache 異常を再現した場合に割込みが発生し、下記のコンソールメッセージが出力されます（未検証）。
	　 "[INTERRUPT]L2 Cache Combined Interrupt is occurred!! status==0x0000****"
	
	→ L2 Cache Controller に対して割り込み通知機能を有効にする設定を行う（HWLib を使用して Enable）。

sample_cache_manage_test_main();
	→ テストプログラムを実行します。
	　 無限ループ内で以下の処理を行います。

	　 - HPS 用 PUSHSW0 の押下契機
	　　　　HPS 用 DIPSW0 が ON --> 無限ループを終了します（テストプログラムの終了）。
	　　　　HPS 用 DIPSW0 が OFF -> L1, L2 Cache 機能を全て Enable/Disable にする API を実行します（SW 押下毎に Enable と Disable を交互に実行します）。

	　 - HPS 用 PUSHSW1 の押下契機
	　　　　HPS 用 DIPSW1 が ON --> alt_cache_system_invalidate を実行します
	　　　　HPS 用 DIPSW2 が ON --> alt_cache_system_clean を実行します
	　　　　HPS 用 DIPSW3 が ON --> alt_cache_system_purge を実行します
	　　　　（Cache 情報クリア系 API の試行）

	　 - HPS 用 PUSHSW2 の押下契機
	　　　　HPS 用 DIPSW0 が OFF
	　　　　　　HPS 用 DIPSW1 が ON --> alt_cache_l1_data_invalidate_all を実行します
	　　　　　　HPS 用 DIPSW2 が ON --> alt_cache_l1_data_clean_all を実行します
	　　　　　　HPS 用 DIPSW3 が ON --> alt_cache_l1_data_purge_all を実行します
	　　　　　　（L1 Cache 情報の一括クリア用 API の試行）
	　　　　HPS 用 DIPSW0 が ON
	　　　　　　HPS 用 DIPSW1 が ON --> alt_cache_l2_data_invalidate_all を実行します
	　　　　　　HPS 用 DIPSW2 が ON --> alt_cache_l2_data_clean_all を実行します
	　　　　　　HPS 用 DIPSW3 が ON --> alt_cache_l2_data_purge_all を実行します
	　　　　　　（L2 Cache 情報の一括クリア用 API の試行）

	　 - HPS 用 PUSHSW3 の押下契機
	　　　　キャッシュ効果の検証用に関数 mul_f32_test_funciton を起動して
	　　　　処理時間の計測および表示を行います。


◎ プログラム起動（sample_app.c 内の main() 関数の先頭で break）の後、続行(F8) を行うと、
　 コンソール上にてクロックマネージャの動作情報（HPS の動作クロック他）が確認できます。
　 また、無限ループ開始後に HPS 用 PUSHSW、 DIPSW を操作することで特定の API の動作が
　 確認可能になっています。

------------------------------------------------------------------------
>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 以上 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
