﻿<<<< 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用を使用)"

確認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-opensource/u-boot-socfpga/releases/tag/rel_socfpga_v2020.10_21.03.01_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-2021 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 つと SLIDE スイッチ (DIPSW) 4 つを
　 操作することでソフトウェアの動作を切り替える仕組みを実装しております。
　
　但し、ターゲットボードに Atlas-SoC / DE0-Nano-SoC / DE10-Nano を選択した場合、
　HPS 側には前述のスイッチが不足する状態となるため、以下の対応でご利用頂く実装としています。
　 * PUSH SW #0 ... FPGA 側の PUSH BUTTON (KEY0, KEY1) を同時押し 
　 * PUSH SW #1 ... FPGA 側の PUSH BUTTON (KEY0) を単押し
　 * PUSH SW #2 ... FPGA 側の PUSH BUTTON (KEY1) を単押し
　 * PUSH SW #3 ... HPS 側の USER PUSH BUTTON (KEY2) を単押し
　 * SLIDE SW #0:3 ... FPGA 側の SLIDE スイッチ (SW0, SW1, SW2, SW3) 
　
　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○\examples の中に格納してある
		sample_gpio.c を ALT-HWLib-All-In-One_vXX.X_r○ の TOP ディレクトリにコピーして、
		sample_app.c の main() 関数内から sample_gpio.c の sample_gpio_test_cmd() 関数を
		呼び出すように記述します。

　　②．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() が起動します。
    　　　 - DIPSW#0:1 を利用して割り込みトリガーを選択します。
	　　　　　DIPSW#0:1 = 0 ... Rising-Edge
	　　　　　DIPSW#0:1 = 1 ... Falling-Edge
	　　　　　DIPSW#0:1 = 2 ... Rising-Edge
	　　　　　DIPSW#0:1 = 3 ... Falling-Edge
	　 - PUSHSW#3 を契機に GPIO 割り込みを発生させます。

sample_gpio_iopolling();
	→ 無限ループ内で GPIO の入力レジスタを監視し、値の変化を検出する毎に
	　 デバッガ・コンソールへ変化内容を出力します。

	　※ PUSHSW#0 が押されたことを検出したら無限ループを終了します（プログラムの終了）。

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

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

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