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

-- 情報 ----------------------------------------------------------------
ファイル名：		sample_dmac.c
更新日：			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 バージョン：	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 v15.0 以前のツールを利用する場合には、本サンプルに含まれるソースコードの差し替えが必要となります。
　 alt_dma_custom__old_hwlib_base.c を alt_dma_custom.c へリネームして差し替えを行ってください。

※ 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

※ 本サンプルでは、sample_app.c 内で DMA の初期化を行わせるために、
　 config.mk ファイル内の USED_DMA 定義を 1 に設定してビルドしてください。
　################################
　# USE DMA sample (0:No / 1:Yes)#
　################################
　USED_DMA := 1

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


-- 概要 ----------------------------------------------------------------
HPS 内臓 DMA（DMA-330）を使って、DMA 転送を行うサンプルです。

このプログラムを実行する際は、コンソールから以下のパラメーターを入力します。
<DMA 転送元アドレス> <DMA 転送先アドレス> <DMA 転送サイズ> <転送バイト幅>

例えば、
　転送元アドレス = 0x10000
　転送先アドレス = 0x12000
　転送サイズ = 0x100
　転送バイト幅 = 8
の場合は次のように 10000 12000 100 8 と入力します。

Command: dmatest 10000 12000 100 8
dmatest 10000 12000 100 8
dma_test
==== DMA Test Parameters ====
 - DMA CH Select ..... ALT_DMA_CHANNEL_0
 - Source Address ........... 0x00010000
 - Destination Address ...... 0x00012000
 - Transport size ........... 0x00000100
 - Transport via ACP Port ... False
 - Execute cache operation .. True
==== Time Mesurement Results (0 ~ 4) ====
[TIME# 0]
 - Elapsed Seconds (nsec): 0.000001 (1280)
[TIME# 1]
 - Elapsed Seconds (nsec): 0.000002 (2720)
[TIME# 2]
 - Elapsed Seconds (nsec): 0.000003 (3840)
[TIME# 3]
 - Elapsed Seconds (nsec): 0.000003 (3040)
[TIME# 4]
 - Elapsed Seconds (nsec): 0.000008 (8800)

DMA Result ... OK

[IRQ#136] DMA_IRQ0 (0x00000088,0x00000003) count=10


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

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

　ENABLE_EXAMPLE_DMA     : sample_dmac.c,sample_dma_mem.c (USED_DMA must be 1) 
　ENABLE_EXAMPLE_DMA       := 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_dmac_test_cmd() 以降） ---------------------------------

以下にサンプル関数の概要を示します。

①　sample_dma_m2m_setting(bytes);
　　引数 bytes の値に従って DMA（DMA-330）の設定を行います。 bytes には 1、2、4、8 のいずれかを設定します。

②　sample_dmac_test_main(ALT_DMA_CHANNEL_0, (void*)srcaddr, (void*)dstaddr, (size_t)size);
　　DMA 転送実行サンプル関数 sample_dmac_test_execute() を呼び出します。

③　sample_dmac_test_execute();
　　alt_dma_channel_exec () DMA 転送実行 API 関数を呼び出します。

------------------------------------------------------------------------

◎ 補足．DMA 用 HWLib のカスタマイズ (alt_dma_custom.c)
　　　　 本サンプルの DMA 転送用 API は、HWLib の alt_dma.c をベースにカスタマイズした
　　　　 ファイル alt_dma_custom.c を利用しています。

　○ ＜変更点１＞
　　　　　DMA 転送時間を計測する都合で、HWLib の メモリ to メモリ転送実行用の API：alt_dma_memory_to_memory の
　　　　　DMA-330 用マイクロコード生成部分のみを別関数化しています。
　　　　　また、ACP ポート経由で DMA 転送を行うためには、AXI 信号 (AWCACHE/ARCACHE) の C ビットを 1 に設定する
　　　　　必要があるため、引数指定にて DMA 転送実行時の AXI 信号 を指定可能としています。

ファイル名：alt_dma_custom.c
05983|ALT_STATUS_CODE alt_dma_channel_program_memory_to_memory(ALT_DMA_CHANNEL_t channel,
05984|                                            ALT_DMA_PROGRAM_t * program,
05985|                                            void * dst,       int dst_cache_ctrl,
05986|                                            const void * src, int src_cache_ctrl,
05987|                                            size_t size)
05988|{
...
06198|}

　　　　　ACP ポート利用時の AWCACHE/ARCACHE 設定については、ARM ドキュメント
　　　　　『Cortex(TM)-A9 MPCore テクニカルリファレンスマニュアル』
　　　　　「2.4.1 ACP 要求」を参照ください。


　○ ＜変更点２＞
　　　　　DMA-330 用マイクロコード格納バッファのサイズに最大値を指定しています。
　　　　　Makefile 上で ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE=65536 を指定する事で
　　　　　大きなサイズの DMA 転送が行えるように変更しています。
　　　　　(最大値 65535 を指定すると大量のメモリを占有するため、本来はマイクロコードの最大サイズに
　　　　　応じて最適なサイズを指定します)。
　　　　　
　　　　　標準の設定では、弊社で試した限りでは、転送サイズ 2 ～ 3 MByte 程度 (利用する API により異なる)で
　　　　　バッファが足りなくなるようです (バッファが足りない場合、API がエラー ALT_E_BUF_OVF を返します)。
　　　　　この件は、HWLib の alt_dma_program.h に下記のように記載されています。

/*!
 * This preprocessor definition determines the size of the program buffer
 * within the ALT_DMA_PROGRAM_t structure. This size should provide adequate
 * size for most DMA microcode programs. If calls within this API are
 * reporting out of memory response codes, consider increasing the provisioned
 * program buffersize.
 *
 * To specify another DMA microcode program buffer size, redefine the macro
 * below by defining ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE to another size in
 * your Makefile. It is recommended that the size be a multiple of the
 * microcode engine cache line size. See ALT_DMA_PROGRAM_CACHE_LINE_SIZE for
 * more information. The largest supported buffer size is 65536 bytes.
 */
#ifndef ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE
#define ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE   (ALT_DMA_PROGRAM_CACHE_LINE_SIZE * ALT_DMA_PROGRAM_CACHE_LINE_COUNT)
#endif
>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 以上 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
