// These APIs are published for the demodulator programmer
/**
+ * \def radio_api_getARM_mode
* \brief 受信モードの取得
* \details
* このAPIは現在の受信モード（復調モード）を返す。シリアルコマンドARMに対応する。
* \details
* シリアルコマンドABN命令に対応する。
* 16bitの符号無し整数でノイズブランカ制御値値を返す。
- * 0 : オン
- *
- * 1 : オフ
+ * \li 0 : オン
+ * \li 1 : オフ
*/
#define radio_api_getABN_noise_blanker_on() ((~radio.comdata[0]>>11)&0x1)
* シリアルコマンドARG命令に対応する。
* 16bitの符号無し整数でAGC制御情報値を返す。
*
- * 0 : オン
- *
- * 1 : オフ
+ * \li 0 : オン
+ * \li 1 : オフ
*/
#define radio_api_getARG_agc_on() (~(radio.comdata[0]>>13)&0x1)
* 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
* シリアルコマンドNE命令に対応する。
* 16bitの符号無し整数でスケルチ制御情報値を返す。
*
- * 1 : オン
- *
- * 0 : オフ
+ * \li 1 : オン
+ * \li 0 : オフ
*
* なお、以上の設定はトランジスタ技術誌の2014年11月号の表に基づくが、
* この表には混乱があり、反転している可能性もある。
* シリアルコマンドAVS命令に対応する。
* 16bitの符号無し整数でボイススケルチ制御情報値を返す。
*
- * 0 : オン
- *
- * 1 : オフ
+ * \li 0 : オン
+ * \li 1 : オフ
*/
#define radio_api_getAVS_voice_squelch_on() ((~radio.comdata[12]>>7)&0x1)
/*@}*/
/* 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_ */
OSDN Git Service
