-/*
- * demodulator.h
- *
- * Created on: 2015/03/10
- * Author: takemasa
+/**
+ * \file demodulator.h
+ * \date 2015/03/10
+ * \brief 復調器関連インクルードファイル
*/
#ifndef DEMODULATOR_H_
#define DEMODULATOR_H_
+
+#ifndef _MACRO_ONLY
+/**
+ * \defgroup radioAPI ラジオAPI
+ * \brief 復調器がTRX-305の制御部と情報の授受を行うためのAPI群
+ * \details
+ * このモジュールに含まれるAPIは、復調器の中でユーザー復調アルゴリズムが使うために
+ * 公開されている。制御情報取得用APIはTRX-305からの制御情報を受け取るためのものである。
+ *
+ * 制御情報は周期的に送られてくるため、必ずしも即座に反応する必要はない。具体的には
+ * TRX-305からは16種類の情報が16周期で送られてくる。これらは情報の中身に変更がない場合も
+ * かわらない。
+ */
+/*@{*/
+
+/**
+ * \defgroup getInfo 制御情報取得API
+ * \brief 復調器がTRX-305から受け取る制御情報取得用のAPI
+ * \details
+ * ここに列挙されるAPIは、いずれも復調器内のユーザーアルゴリズムから自由に使ってよい。
+ *
+ * TRX-305から送られてくる制御情報は、ほとんどの場合TRX-305A基板にシリアルポートから
+ * 送られてくるコマンドに対応している。コマンドの一覧に関しては、トランジスタ技術誌
+ * 2014年11月号208ページの表を参照。なお、同記事のコマンドはTRX-305AのSHマイコンで
+ * 解釈後にDSPに送られるため、ここで使える命令とは必ずしも一対一対応していない。
+ *
+ * TRX-305Aが受け取るシリアル命令は、SHマイコンにより解釈されたあとにFPGA内部に
+ * 貯めこまれ、繰り返し送り出される。DSPはこの命令を受信し、制御情報として内部に
+ * さらに蓄える。
+ *
+ * なお、これらのAPIが返すのは、あくまで解釈のない「マイコンから送られてきた値」である。
+ * その値の物理的な解釈については、本プロジェクトは最小限に留める。言い換えると、
+ * ここに書いていない解釈は行わない。
+ *
+ * 命令に関してはすべて実際に解析したものであり、参考とした文献は存在しない。
+ * 命令の解析は framework.h の DEBUG_COMMAND のコメントアウトを外すことによって、
+ * DSPからのシリアル出力を監視しながらSHにシリアルコマンドを投入して行う。
+ *
+ *
+ */
+/*@{*/
+
// Following mode macro can be used only the demodulator
+
+ /** \brief 受信機はワイドFMモードである */
#define radio_mode_WFM 2
+ /** \brief 受信機はナローFMモードである */
#define radio_mode_NFM 4
+ /** \brief 受信機は振幅変調モードである */
#define radio_mode_AM 5
+ /** \brief 受信機は振幅変調モードの同期復調モードである */
#define radio_mode_SAM 6
+ /** \brief 受信機はLSB復調モードである */
#define radio_mode_LSB 7
+ /** \brief 受信機はUSB復調モードである */
#define radio_mode_USB 8
+ /** \brief 受信機はCW復調モードである */
#define radio_mode_CW 9
-#ifndef _MACRO_ONLY
// These APIs are published for the demodulator programmer
+ /**
+ * \brief 受信モードの取得
+ * \details
+ * このAPIは現在の受信モード(復調モード)を返す。シリアルコマンドARMに対応する。
+ * 復調モードは整数である。
+ * ユーザーに公開されているAPIであるが、2つの理由から使用を推奨しない。
+ *
+ * まず、復調器hののモード管理は radio_demodulate_wide_FM() および
+ * radio_demodulate_wide_FM() がフレームワークと強調する管理で行っており、
+ * プログラマは復調器がどのモードにあるかひと目でわかるようになっている。
+ * そのため、モード管理にこの関数を呼ぶ必要はない。
+ *
+ * また、USBとLSBの復調を概ね共用する場合も、radio_api_is_USB() を呼べば
+ * 事が足りる。したがって、この関数を呼ぶ必要はない。
+ *
+ * どうしてもこのAPIを呼び出すときには、 radio_mode_WFM() をはじめとする専用
+ * 定数と比較してモードを調べること。SHマイコンは外部のシリアルから与えられた
+ * パラメータと違う値を送ってくるため、この注意が必要となる。
+ */
#define radio_api_getARM_mode() (radio.comdata[1])
+
+ /**
+ * \brief IFシフト量の取得
+ * \details
+ * シリアルコマンドのAIS命令に対応する。
+ * 16bitの符号付き整数でシフト量を返す。
+ */
#define radio_api_getAIS_if_shift() (signed short)(radio.comdata[2])
+
+ /**
+ * \brief AGCアタック値の取得
+ * \details
+ * シリアルコマンドのAAT命令に対応する。
+ * 16bitの符号無し整数でアタック値を返す。
+ */
#define radio_api_getAAT_attack() (radio.comdata[3])
+
+ /**
+ * \brief AGCフェード値の取得
+ * \details
+ * シリアルコマンドのAAT命令に対応する。
+ * 16bitの符号無し整数でフェード値を返す。
+ */
#define radio_api_getAFA_fade() (radio.comdata[4])
+
+ /**
+ * \brief AGCフェード値の取得
+ * \details
+ * シリアルコマンドのAAT命令に対応する。
+ * 16bitの符号無し整数でフェード値を返す。
+ */
#define radio_api_getAST_noise_squelch_level() (radio.comdata[5])
-#define radio_api_getACP_cw_pitch() (radio.comdata[6])
+
+ /**
+ * \brief 再生トーンピッチの取得
+ * \details
+ * シリアルコマンドのACP命令に対応する。
+ *
+ * SHマイコンはシリアルコマンド ACP hhhh (hは16進数)に対して、
+ * hhhhを十進数xに変換し x*16916/4096 の値をDSPに送り込む。
+ * このAPIが返すのは送り込まれてきた変換後の値である。
+ *
+ * 16bitの符号付き整数でピッチ値を返す。
+ */
+#define radio_api_getACP_cw_pitch() (signed short)(radio.comdata[6])
+
+ /**
+ * \brief デノイザー値の取得
+ * \details
+ * シリアルコマンドADN命令に対応する。
+ * 16bitの符号無し整数でデノイザー値を返す。
+ */
#define radio_api_getADN_denoiser() (radio.comdata[7])
+
+/**
+ * \brief オートノッチ値の取得
+ * \details
+ * シリアルコマンドAAN命令に対応する。
+ * 16bitの符号無し整数でオートノッチ値を返す。
+ */
#define radio_api_getAAN_auto_notch() (radio.comdata[8])
+
+/**
+ * \brief ゲインレベル値の取得
+ * \details
+ * シリアルコマンドAGL命令に対応する。
+ * 16bitの符号無し整数でゲインレベル値を返す。
+ */
#define radio_api_getAGL_gain_level() (radio.comdata[11])
// Flag 0
+/**
+ * \brief IFフィルタ値の取得
+ * \details
+ * シリアルコマンドAIF命令に対応する。
+ * 16bitの符号無し整数でフィルタ情報を返す。値の範囲は0から6である。
+ *
+ * (この情報がDSPへの命令なのか通知情報なのかは、現時点では不明である)
+ */
#define radio_api_getAIF_filter() ((radio.comdata[0]>>1)&0x7)
+
+/**
+ * \brief ノイズブランカ制御命令の取得
+ * \details
+ * シリアルコマンドABN命令に対応する。
+ * 16bitの符号無し整数でノイズブランカ制御値値を返す。
+ * 0 : オン
+ *
+ * 1 : オフ
+ */
#define radio_api_getABN_noise_blanker_on() ((~radio.comdata[0]>>11)&0x1)
+
+
+/**
+ * \brief AGC制御情報の取得
+ * \details
+ * シリアルコマンドARG命令に対応する。
+ * 16bitの符号無し整数でAGC制御情報値を返す。
+ *
+ * 0 : オン
+ *
+ * 1 : オフ
+ */
#define radio_api_getARG_agc_on() (~(radio.comdata[0]>>13)&0x1)
+
+/**
+ * \brief 復調モード情報の取得
+ * \details
+ * SSB復調時に必要に応じて参照する。。
+ * 16bitの符号無し整数でSSBのモードを返す。
+ *
+ * 0 : LSB
+ *
+ * 非0 : USB
+ */
#define radio_api_is_USB() ((radio.comdata[0]>>6)&0x1) // 1 if USB
// Flag10
+/**
+ * \brief ノイズスケルチ制御情報の取得
+ * \details
+ * シリアルコマンドNE命令に対応する。
+ * 16bitの符号無し整数でスケルチ制御情報値を返す。
+ *
+ * 1 : オン
+ *
+ * 0 : オフ
+ *
+ * なお、以上の設定はトランジスタ技術誌の2014年11月号の表に基づくが、
+ * この表には混乱があり、反転している可能性もある。
+ */
#define radio_api_getANE_noise_squelch_on() ((radio.comdata[10]>>1)&0x1)
+
+
+/**
+ * \brief オーディオHPF情報の取得
+ * \details
+ * シリアルコマンドAAF nm命令のnに対応する。
+ * 16bitの符号無し整数でオーディオHPF制御情報値を返す。
+ *
+ * 値の範囲は0-2
+ */
#define radio_api_getAAF_hpf() ((radio.comdata[10]>>4)&0x3)
+
+/**
+ * \brief オーディオLPF情報の取得
+ * \details
+ * シリアルコマンドAAF nm命令のmに対応する。
+ * 16bitの符号無し整数でオーディオLPF制御情報値を返す。
+ *
+ * 値の範囲は0-2
+ */
#define radio_api_getAAF_lpf() ((radio.comdata[10]>>2)&0x3)
// Flag 12
+/**
+ * \brief ボイススケルチ値の取得
+ * \details
+ * シリアルコマンドAVP命令に対応する。
+ * 16bitの符号無し整数でボイススケルチ値を返す。
+ * 値の範囲は0-127
+ *
+ * シリアルコマンドAVPの引数は0000-FFFF (65556)までの値をとるが、
+ * DSPに渡される値はbit7がAVSによって破壊される。したがって、
+ * AVPコマンドに渡す値は 0000から 007Fに制限すべきである。
+ */
#define radio_api_getAVP_voice_squelch_level() ((radio.comdata[12])&0x3F)
+
+/**
+ * \brief ボイススケルチ情報の取得
+ * \details
+ * シリアルコマンドAVS命令に対応する。
+ * 16bitの符号無し整数でボイススケルチ制御情報値を返す。
+ *
+ * 0 : オン
+ *
+ * 1 : オフ
+ */
+
#define radio_api_getAVS_voice_squelch_on() ((~radio.comdata[12]>>7)&0x1)
+/*@}*/
+/* end of defgroup getInfo */
+
+/**
+ * \defgroup setStat 状態報告API
+ */
+/*@{*/
// Set S meter
#define radio_api_set_S_meter(s) radio.smeter = s
+/*@}*/
+/* end of defgroup setStat */
+/*@}*/
+/* end of defgroup radioAPI */
+
+
+/**
+ * \brief 復調アルゴリズム初期化関数
+ *
+ */
void init_demodulator(void);
void radio_demodulate_wide_FM( short idata[], short qdata[], short* left, short* right );
void radio_demodulate_non_wide_FM( int idata, int qdata, short* left, short* right );