-/*
- * 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モードでブロック浮動小数点の整数化がうまく出来ているかダンプする。
+ *
*/
+/**
+ * \mainpage
+ * \section section_overview 概要
+ * このドキュメントは、HiradoフレームワークのAPIについて解説する
+ *
+ * HiradoはSDR無線機TRX-305のDSP部の復調器フレームワークである。
+ *
+ * プログラマは \ref callbacks の関数群を埋める形で復調器を実装する。
+ *
+ * \section section_api API
+ * コールバックの中からは \ref radioAPI にある無線APIを使って
+ * 制御用のSHマイコン/FPGAと通信を行う。通信する内容は2種類ある。
+ * \li 制御用マイコンからの制御命令
+ * \li DSPからのステータス通知
+ * \section section_debug デバッグについて
+ * フレームワークにはデバッグ支援機能があり、デバッグマクロを宣言することで利用できる。
+ * これらの機能はすべてDSPのuartを利用している。通信速度は115200baud, 8bit, parityなし、
+ * 1stopbitである。
+ *
+ * フレームワークのデバッグ機能については \ref framework.h の解説を参照。
+ *
+ *
+ */
#ifndef _FRAMEWORK_H_
#define _FRAMEWORK_H_
#include <t_services.h>
#include "demodulator.h"
+/**
+ * \defgroup radioFramework フレームワーク内部宣言
+ * \brief フレームワークの内部で使うオブジェクトの内部宣言。基本的にユーザーは参照しなくていい
+ */
+/*@{*/
/*
* デバッグマクロ
* 領域が必要である。
*
* なお、このソフトウェアは1サンプルあたり2[エントリ]をキューに格納するため、
- * キューの長さ[エントリ]は、割り込み周期[サンプル]の四倍になる。
+ * ã\81\93ã\82\8cã\82\92å\8b\98æ¡\88ã\81\99ã\82\8bã\81¨ã\80\81æ\9c\80ä½\8eã\81§ã\82\82ã\82ã\83¥ã\83¼ã\81®é\95·ã\81\95[ã\82¨ã\83³ã\83\88ã\83ª]ã\81¯ã\80\81å\89²ã\82\8aè¾¼ã\81¿å\91¨æ\9c\9f[ã\82µã\83³ã\83\97ã\83«]ã\81®å\9b\9bå\80\8dã\81«ã\81ªã\82\8bã\80\82
*
*
*/
#define AF_QUESIZE 80 /* 送受信タスクの間のキューの長さ。8サンプルが最長割り込み周期と仮定してさらにマージンをもたせている */
-#define WIDE_FM_OVERSAMPE 8 /* AF1サンプルあたりのWide FM サンプル数 */
+ /** \brief AF1サンプルあたりのWide FM サンプル数 */
+#define WIDE_FM_OVERSAMPE 8
-#define WIDE_FM_FLAG 2 /* プライマリ・チャンネルのWIDE FM Modeを表すフラグのマスク */
+ /** \brief プライマリ・チャンネルのWIDE FM Modeを表すフラグのマスク */
+#define WIDE_FM_FLAG 2
+ /** \brief SHマイコン/FPGAから送られてくるコマンドの種類の数 */
#define PARAMDATA_NUM 16
* 各タスクの優先度の定義
*/
-#define TASK_PRIORITY_AF 5 /* AF DMAタスクの優先度。送信なので優先度高 */
-#define TASK_PRIORITY_RX_IF 10 /* RX-IF DMA処理タスクの優先度。復調も行う */
-#define LOGTASK_PRIORITY 12 /* デフォルトの初期優先度を上書きする */
-#define TASK_PRIORITY_MONITOR 15 /* モニター・タスクの優先度。優先度低 */
+ /** breif AF DMAタスクの優先度。送信なので優先度高 */
+#define TASK_PRIORITY_AF 5
+ /** breif RX-IF DMA処理タスクの優先度。復調も行う */
+#define TASK_PRIORITY_RX_IF 10
+ /** breif デフォルトの初期優先度を上書きする */
+#define LOGTASK_PRIORITY 12
+ /** breif モニター・タスクの優先度。優先度低 */
+#define TASK_PRIORITY_MONITOR 15
/*
* ターゲット依存の定義(CPU例外ハンドラの起動方法など)
*/
-
-#define STACK_SIZE_RX_IF 1024 /* タスクのスタックサイズ */
-#define STACK_SIZE_AF 1024 /* タスクのスタックサイズ */
-#define STACK_SIZE_MONITOR 1024 /* タスクのスタックサイズ */
-#define TASK_PORTID 1 /* 文字入力するシリアルポートID */
+ /** breif タスクのスタックサイズ */
+#define STACK_SIZE_RX_IF 1024
+ /** breif タスクのスタックサイズ */
+#define STACK_SIZE_AF 1024
+ /** breif タスクのスタックサイズ */
+#define STACK_SIZE_MONITOR 1024
+ /** breif 文字入力するシリアルポートID */
+#define TASK_PORTID 1
*/
#ifndef _MACRO_ONLY
+/**
+ * \brief フレームワークがラジオとのやりとりに使う変数の型。
+ * \details
+ * フレームワークはFPGAから送られてきたデータをこの変数の中に格納する。復調アルゴリズムは \ref getInfo を通してこれらの値にアクセスする。
+ */
// ラジオアルゴリズムとのやりとりに使う変数
extern struct RADIO {
- unsigned short flags;
- unsigned short smeter;
- unsigned short comdata[PARAMDATA_NUM];
+ unsigned short flags; /**< DSPからFPGA/SHマイコンへ送るステータスフラグ */
+ unsigned short smeter; /**< DSPからFPGA/SHマイコンへ送るSメータ値 */
+ unsigned short comdata[PARAMDATA_NUM]; /**< DSPへSHマイコン/FPGAから送るコマンド群 */
} radio;
+/**
+ * \brief フレームワークがラジオとのやりとりに使う変数。
+ */
extern struct RADIO radio;
-
-extern void rx_if_task(VP_INT exinf); /* SPORT0 RX DMAバッファの内容を復調するタスク */
-extern void af_task(VP_INT exinf); /* 復調済みAF信号をSPORT0 TX DMAバッファにコピーするタスク */
-extern void monitor_task(VP_INT exinf); /* SPORT0 TX DMAバッファにAFデータを書き込むタスク */
-extern void sport0_rx_int_handler( void ); /* SPORT0 RX DMA割り込みのハンドラ */
-extern void sport0_tx_int_handler( void ); /* SPORT0 TX DMA割り込みのハンドラ */
-void init_peripherals(VP_INT p); /* ペリフェラルの初期化関数 */
-
+ /**
+ * \brief SPORT0 RX DMAバッファの内容を復調するタスク
+ * \param exinf タスクに渡す拡張データ。このタスクには何も渡さなくていい
+ * \details
+ * このタスクは \ref sport0_rx_int_handler() 割り込みハンドラからの
+ * セマフォ・シグナルを受け取って受信処理を行う。
+ */
+
+extern void rx_if_task(VP_INT exinf);
+
+ /**
+ * \brief 復調済みAF信号をSPORT0 TX DMAバッファにコピーするタスク
+ * \param exinf タスクに渡す拡張データ。このタスクには何も渡さなくていい
+ * \details
+ * このタスクは \ref sport0_tx_int_handler() 割り込みハンドラからの
+ * セマフォ・シグナルを受け取り、タスク間キューからデータを取り出しSPORT処理を行う。
+ */
+extern void af_task(VP_INT exinf);
+
+ /**
+ * \brief デバッグ用のデータ収集を行うバックグラウン・タスク
+ * \param exinf タスクに渡す拡張データ。このタスクには何も渡さなくていい
+ */
+extern void monitor_task(VP_INT exinf);
+
+ /**
+ * \brief SPORT0 RX DMA割り込みのハンドラ
+ */
+extern void sport0_rx_int_handler( void );
+
+ /**
+ * \brief SPORT0 TX DMA割り込みのハンドラ
+ */
+extern void sport0_tx_int_handler( void );
+
+ /**
+ * \brief ペリフェラルの初期化関数
+ * \param p タスクに渡す拡張データ。このタスクには何も渡さなくていい
+ */
+void init_peripherals(VP_INT p);
+
+/*@}*/
#endif /* _MACRO_ONLY */