X-Git-Url: http://git.osdn.net/view?p=trx-305dsp%2Fdsp.git;a=blobdiff_plain;f=hirado%2Fdemodulator.h;fp=hirado%2Fdemodulator.h;h=5d1857198f920ab3f1fb7e1e360ee0ccc596eecd;hp=165c469f1f844b2cc41ba3b7a53f2db6ec551b1e;hb=db50ab6e144762352e703f055b25f9a749c71508;hpb=880306168b7f7587635b217b5e3259e87244e7a6

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_ */