From db50ab6e144762352e703f055b25f9a749c71508 Mon Sep 17 00:00:00 2001
From: suikan <suikan@users.sourceforge.jp>
Date: Sun, 4 Oct 2015 16:48:59 +0900
Subject: [PATCH] =?utf8?q?doxygen=E3=82=B3=E3=83=A1=E3=83=B3=E3=83=88?=
 =?utf8?q?=E8=BF=BD=E5=8A=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 hirado/demodulator.h | 113 +++++++++++++++++++++++++++++++++++++++++++--------
 hirado/framework.h   |  62 +++++++++++-----------------
 2 files changed, 120 insertions(+), 55 deletions(-)

diff --git a/hirado/demodulator.h b/hirado/demodulator.h
index 165c469..5d18571 100644
--- a/hirado/demodulator.h
+++ b/hirado/demodulator.h
@@ -68,6 +68,7 @@
 
     // These APIs are published for the demodulator programmer
     /**
+     * \def radio_api_getARM_mode
      * \brief 受信モードの取得
      * \details
      * このAPIは現在の受信モード（復調モード）を返す。シリアルコマンドARMに対応する。
@@ -172,9 +173,8 @@
      * \details
      * シリアルコマンドABN命令に対応する。
      * 16bitの符号無し整数でノイズブランカ制御値値を返す。
-     * 0 : オン
-     *
-     * 1 : オフ
+     * \li 0 : オン
+     * \li 1 : オフ
      */
 #define radio_api_getABN_noise_blanker_on() ((~radio.comdata[0]>>11)&0x1)
 
@@ -185,9 +185,8 @@
      * シリアルコマンドARG命令に対応する。
      * 16bitの符号無し整数でAGC制御情報値を返す。
      *
-     * 0 : オン
-     *
-     * 1 : オフ
+     * \li 0 : オン
+     * \li 1 : オフ
      */
 #define radio_api_getARG_agc_on() (~(radio.comdata[0]>>13)&0x1)
 
@@ -197,9 +196,8 @@
      * SSB復調時に必要に応じて参照する。。
      * 16bitの符号無し整数でSSBのモードを返す。
      *
-     * 0 : LSB
-     *
-     * 非0 : USB
+     * \li 0 : LSB
+     * \li 非0 : USB
      */
 #define radio_api_is_USB()  ((radio.comdata[0]>>6)&0x1)     // 1 if USB
 
@@ -210,9 +208,8 @@
      * シリアルコマンドNE命令に対応する。
      * 16bitの符号無し整数でスケルチ制御情報値を返す。
      *
-     * 1 : オン
-     *
-     * 0 : オフ
+     * \li 1 : オン
+     * \li 0 : オフ
      *
      * なお、以上の設定はトランジスタ技術誌の2014年11月号の表に基づくが、
      * この表には混乱があり、反転している可能性もある。
@@ -260,9 +257,8 @@
      * シリアルコマンドAVS命令に対応する。
      * 16bitの符号無し整数でボイススケルチ制御情報値を返す。
      *
-     * 0 : オン
-     *
-     * 1 : オフ
+     * \li 0 : オン
+     * \li 1 : オフ
      */
 
 #define radio_api_getAVS_voice_squelch_on() ((~radio.comdata[12]>>7)&0x1)
@@ -283,15 +279,100 @@
 /*@}*/
 /*  end of defgroup radioAPI */
 
+/**
+ * \defgroup callbacks 復調用コールバック関数
+ * \details
+ * 復調器のためにフレームワークから呼び出すコールバック関数。復調アルゴリズムは全てこの中に記述する。
+ *
+ * 関数は大きく分けて2種類に分けられる。ひとつは初期化関数で \ref init_demodulator() がこれである。
+ * その他の関数は実際の復調を行う関数である。
+ */
+ */
+/*@{*/
 
 /**
  * \brief 復調アルゴリズム初期化関数
- *
+ * \detail
  */
+
+     /**
+      * \brief 復調器の初期化
+      * \details
+      * 復調アルゴリズムの初期化を行う。アルゴリズムが変数を初期化しなければならないようなときには、
+      * この関数の中に初期化プログラムを書く。
+      *
+      * この関数は、\ref radio_demodulate_wide_FM() や \ref radio_demodulate_non_wide_FM() が
+      * 呼ばれる前に一度だけ呼ばれる。
+      *
+      */
 void init_demodulator(void);
+
+
+     /**
+      * \brief ワイドFMの復調コールバック関数
+      * \param idata 受信IFのI(in phase)データ配列。32bit符号付き固定小数点数。フォーマットはQ1.31
+      * \param qdata 受信IFのQ(Quadratural phase)データ配列。32bit符号付き固定小数点数。フォーマットはQ1.31
+      * \param left 復調オーディオ信号の左チャンネルデータ。16bit符号付き固定小数点数。フォーマットはQ1.15
+      * \param right 復調オーディオ信号の右チャンネルデータ。16bit符号付き固定小数点数。フォーマットはQ1.15
+      * \details
+     * ワイドFM以外の信号を復調するために呼ばれるコールバック関数。この関数と \ref radio_demodulate_non_wide_FM() の
+     * 切り替えはフレームワークが自動的に行うため、ユーザー側は気にしなくていい。
+     *
+     *
+     * IF入力(idata[], qdata[])、AF出力(*left, *right)ともFsは31.7kHzである(トランジスタ技術誌2015年5月号pp183)。
+     * 1サンプル毎に呼び出されるので、このコールバックは1秒間に31,700回呼び出される。
+     *
+     * IF入力はワイドFMではオーバーサンプルされた値が入力する。そのため、1サンプルあたりのデータ数は1ではない。
+     * 具体的なオーバーサンプル値は、マクロ WIDE_FM_OVERSAMPE で知ることができる。まとめると、この関数の中では
+     * idata/qdataそれぞれ WIDE_FM_OVERSAMPE 個のデータを復調処理して、1個のleft/right データを生成する。
+     *
+     * IF入力データとAF出力データの語長が違うことに注意。データのパック形式は固定小数点型であるため、いずれも
+     * データの値の範囲は[-1,1)となる。しかし、C言語としての取り扱いは整数なので、それぞれの最大値は異なる（IFデータの
+     * 最大値はAFデータの65536倍）。
+     *
+      */
+
 void radio_demodulate_wide_FM( short idata[], short qdata[], short* left, short* right );
+
+/**
+ * \brief ワイドFM以外の復調コールバック関数
+ * \param idata 受信IFのI(in phase)データ。32bit符号付き固定小数点数。フォーマットはQ1.31
+ * \param qdata 受信IFのQ(Quadratural phase)データ。32bit符号付き固定小数点数。フォーマットはQ1.31
+ * \param left 復調オーディオ信号の左チャンネルデータ。16bit符号付き固定小数点数。フォーマットはQ1.15
+ * \param right 復調オーディオ信号の右チャンネルデータ。16bit符号付き固定小数点数。フォーマットはQ1.15
+ * \details
+ * ワイドFM以外の信号を復調するために呼ばれるコールバック関数。この関数と \ref radio_demodulate_wide_FM() の
+ * 切り替えはフレームワークが自動的に行うため、ユーザー側は気にしなくていい。
+ *
+ * 非ワイドFM以外のモードにはAM, SAM, LSB, USB, Narrow FM, CW の受信モードがある。これらの受信モードの
+ * 検出は、コールバック関数内部のスケルトンが自動的に切り分けているので、それぞれの場合ごとに復調アルゴリズムを
+ * 書けばよい。
+ *
+ * LSBとUSBの復調コードの大半を共有したい場合には、一部でLSB/USBの判断を行われなければならない。この場合は
+ * \ref radio_api_is_USB() APIを使うことで判別を行う。
+ *
+ * なお、ワイドFMモードから非ワイドFMモードへの切り替えがSHマイコンから出された場合、実際のFMモードからの
+ * 復調器の切り替えは二段階になりうる。最初の段階では radio_demodulate_wide_FM() の呼び出しが終了し、
+ * radio_demodulate_non_wide_FM() の呼び出しへと切り替わる。次の段階では、\ref radio_demodulate_non_wide_FM()
+ * の中で正しい復調モードが検出され、スケルトンの動作が切り替わる。
+ *
+ * この二段階切り替えは必ず起こるというわけではなく、FPGAの実装形態に依存する。単にフレームワークは二段階切り替えにも
+ * 対応できるということである。
+ *
+ * IF入力(idata, qdata)、AF出力(*left, *right)ともFsは31.7kHzである(トランジスタ技術誌2015年5月号pp183)。
+ * 1サンプル毎に呼び出されるので、このコールバックは1秒間に31,700回呼び出される。
+ *
+ * IF入力データとAF出力データの語長が違うことに注意。データのパック形式は固定小数点型であるため、いずれも
+ * データの値の範囲は[-1,1)となる。しかし、C言語としての取り扱いは整数なので、それぞれの最大値は異なる（IFデータの
+ * 最大値はAFデータの65536倍）。
+ *
+ */
+
 void radio_demodulate_non_wide_FM( int idata, int qdata, short* left, short* right );
 
+/*@}*/
+/*  end of defgroupt callbacks */
+
 #endif /* _MACRO_ONLY */
 
 #endif /* DEMODULATOR_H_ */
diff --git a/hirado/framework.h b/hirado/framework.h
index 5db2cb7..57a0f56 100644
--- a/hirado/framework.h
+++ b/hirado/framework.h
@@ -1,41 +1,20 @@
-/*
- *  TOPPERS/JSP Kernel
- *      Toyohashi Open Platform for Embedded Real-Time Systems/
- *      Just Standard Profile Kernel
- *
- *  Copyright (C) 2000-2003 by Embedded and Real-Time Systems Laboratory
- *                              Toyohashi Univ. of Technology, JAPAN
- *  Copyright (C) 2005 by Embedded and Real-Time Systems Laboratory
- *              Graduate School of Information Science, Nagoya Univ., JAPAN
- *
- *  上記著作権者は，以下の (1)〜(4) の条件か，Free Software Foundation
- *  によって公表されている GNU General Public License の Version 2 に記
- *  述されている条件を満たす場合に限り，本ソフトウェア（本ソフトウェア
- *  を改変したものを含む．以下同じ）を使用・複製・改変・再配布（以下，
- *  利用と呼ぶ）することを無償で許諾する．
- *  (1) 本ソフトウェアをソースコードの形で利用する場合には，上記の著作
- *      権表示，この利用条件および下記の無保証規定が，そのままの形でソー
- *      スコード中に含まれていること．
- *  (2) 本ソフトウェアを，ライブラリ形式など，他のソフトウェア開発に使
- *      用できる形で再配布する場合には，再配布に伴うドキュメント（利用
- *      者マニュアルなど）に，上記の著作権表示，この利用条件および下記
- *      の無保証規定を掲載すること．
- *  (3) 本ソフトウェアを，機器に組み込むなど，他のソフトウェア開発に使
- *      用できない形で再配布する場合には，次のいずれかの条件を満たすこ
- *      と．
- *    (a) 再配布に伴うドキュメント（利用者マニュアルなど）に，上記の著
- *        作権表示，この利用条件および下記の無保証規定を掲載すること．
- *    (b) 再配布の形態を，別に定める方法によって，TOPPERSプロジェクトに
- *        報告すること．
- *  (4) 本ソフトウェアの利用により直接的または間接的に生じるいかなる損
- *      害からも，上記著作権者およびTOPPERSプロジェクトを免責すること．
- *
- *  本ソフトウェアは，無保証で提供されているものである．上記著作権者お
- *  よびTOPPERSプロジェクトは，本ソフトウェアに関して，その適用可能性も
- *  含めて，いかなる保証も行わない．また，本ソフトウェアの利用により直
- *  接的または間接的に生じたいかなる損害に関しても，その責任を負わない．
- *
- *  @(#) $Id: sample1.h,v 1.3 2009/05/13 13:10:13 suikan Exp $
+/**
+ * \file framework.h
+ * \brief フレームワーク・インクルードファイル
+ * \details
+ * 原則としてこのファイルの中の宣言をユーザーが変更する必要はない。例外はデバッグマクロのコメントアウト制御である。
+ *
+ * このファイルの中には複数のデバッグマクロが用意されており、これらのコメントアウトを説いて宣言状態にすると、DSP UARTのシリアルポートから
+ * 内部状態を見ることができる。以下にマクロを列挙する。これらはフレームワークの開発中に使用したものをそのまま残している。
+ *
+ * ユーザーが使うとすれば、DEBUG_DSPLOADか、DEBUG_COMMANDだろう。
+ *
+ * \li DEBUG_QUEUEDEPTH シリアルポートから、タスク間Queueの深さを表示させる
+ * \li DEBUG_DSPLOAD シリアルポートからDSP負荷率を表示させる
+ * \li DEBUG_COMMAND DSPに送られてくるコマンドの表示
+ * \li DEBUG_COMMAND_API 復調器から使えるAPIのデバッグ用
+ * \li DEBUG_BLOCK_FLOAT WFMモードでブロック浮動小数点の整数化がうまく出来ているかダンプする。
+ *
  */
 
 #ifndef _FRAMEWORK_H_
@@ -116,7 +95,7 @@
  * 領域が必要である。
  *
  * なお、このソフトウェアは1サンプルあたり2[エントリ]をキューに格納するため、
- * キューの長さ[エントリ]は、割り込み周期[サンプル]の四倍になる。
+ * これを勘案すると、最低でもキューの長さ[エントリ]は、割り込み周期[サンプル]の四倍になる。
  *
  *
  */
@@ -155,6 +134,11 @@
  */
 #ifndef _MACRO_ONLY
 
+/**
+ * \brief フレームワークがラジオとのやりとりに使う変数。
+ * \details
+ * フレームワークはFPGAから送られてきたデータをこの変数の中に格納する。復調アルゴリズムは \ref getInfo を通してこれらの値にアクセスする。
+ */
 
     // ラジオアルゴリズムとのやりとりに使う変数
 extern struct RADIO {
-- 
2.11.0