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

-- 情報 ----------------------------------------------------------------
ファイル名：		sample_gpio.c
作成日：			2013/11/06
更新日：			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.0 Beta (SoC EDS 13.0sp1)
確認 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

※ 本サンプルは a10socdk には未対応です (GPIO 接続の HPS 用ユーザスイッチが用意されていないため) 。

※ 本サンプルでは、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) 
　
　FPGA 側のスイッチを利用するため当該スイッチ用の PIO を実装した .sof にて
　事前に FPGA のコンフィギュレーションを行って頂く必要があります。

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


-- 概要 ----------------------------------------------------------------
HWLib にて、下記のカテゴリに分類されている API を一通り動作させます。
	The General Purpose Input/Output Manager API
	 ＋　General-Purpose IO Configuration Functions
	 ＋　General-Purpose IO Interrupt Functions
	 ＋　General-Purpose IO via Bit Index
	 ＋　General-Purpose IO Utility Functions

ターゲット・ボードの HPS 用 DIPSW、PUSHSW を入力信号として利用可能となるように、
GPIO のコンフィグレートを行い、各スイッチの操作に連動する形でデバッガのコンソール上に 
GPIO 入力レジスタの値の変化を表示させます。


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

　　①．アーカイブを 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_GPIO の定義を "1" に設定してプロジェクトをビルドすると、
	　　ターゲットボードの DIP スイッチを 「Command モード」 に設定してコンソールから "gpio" コマンドを入力することにより、
	　　util/cmd.c 内から sample_gpio.c の sample_gpio_test_cmd() 関数が呼び出されます。

　# ENABLE_EXAMPLE_GPIO    : sample_gpio.c (Arria 10 is not supported)
　ENABLE_EXAMPLE_GPIO      := 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)」を実行します。
		↓
	３．＜HWLib のバージョン 14.0 以前のみ＞ HWLib を仮修正してリビルド
	　　ALT-HWLib-All-In-One_v18.1_r○\util\hwlib\src\hwmgr の下にある「alt_generalpurpose_io.c」について、
	　　alt_gpio_port_int_status_clear() 内の下記記述を変更。
	　　【before】 addr = ALT_GPIO2_INTSTAT_ADDR;
	　　【after】 addr = ALT_GPIO2_PORTA_EOI_ADDR;
	　　再度、「プロジェクトのビルド(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_gpio_test_cmd() 以降） ----------------------------------

◎ sample_gpio_test_cmd() 関数内の下記の記述にて、サンプルコードを呼び出しています。
    //// Sample Function Call!!! |---->
    sample_gpio_utility();
    sample_gpio_config();
    sample_gpio_iconfig();
    sample_gpio_iointerrupt();
    sample_gpio_iopolling();
    //// Sample Function Call!!! <----|


◎ 各サンプル関数の概要を示します。

sample_gpio_utility();
	→ カテゴリ：General-Purpose IO Utility Functions の API を試します（GPIO ユーティリティ API の試行）。

sample_gpio_config();
	→ カテゴリ：General-Purpose IO Configuration Functions および
	　 General-Purpose IO via Bit Index の API を試します（GPIO コンフィグレート用 API の試行）。

sample_gpio_iconfig();
	→ カテゴリ：General-Purpose IO Interrupt Functions の API を試します（GPIO 割り込みコンフィグレート用 API の試行）。

sample_gpio_iointerrupt();
	→ 動作確認用に割り込みコントローラー（GIC）の設定変更を行います。
	　・ 本関数で設定を行った後、下記の条件で割り込みが動作します。
	　　- GPIO 割り込み契機で sample_gpio_callback() が起動します。
	　　- HPS 用 DIPSW[1:0] を利用して割り込みトリガーを選択します。
	　　　　DIPSW[1:0] = 0 ... Rising-Edge
	　　　　DIPSW[1:0] = 1 ... Falling-Edge
	　　　　DIPSW[1:0] = 2 ... Rising-Edge
	　　　　DIPSW[1:0] = 3 ... Falling-Edge
	　　- HPS 用 PUSHSW3 を契機に GPIO 割り込みを発生させます。

sample_gpio_iopolling();
	→ 無限ループ内で GPIO の入力レジスタを監視し、値の変化を検出する毎に
	　 デバッガ・コンソールへ変化内容を出力します。
	　※ HPS 用 PUSHSW0 の押下契機で無限ループを終了します（テストプログラムを終了します）。

sample_gpio_callback();
	→ 割り込みの発生および割り込みステータスの値をログバッファへ記録し、割り込みステータスをクリアします。
	　ログバッファへ記録した情報を元に、通常ルーチンに復帰した後でコンソール出力します。

◎ 続行(F8) で無限ループ処理を動作させている最中に、HPS 用 PUSHSW3 を操作することで、
　 通常ルーチンの動作中に GPIO 割り込みが発生することを確認できます。

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