From: takemasa <suikan@users.sourceforge.jp>
Date: Sat, 1 Sep 2012 14:19:13 +0000 (+0900)
Subject: Doxygenコメントを整備
X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=9ae15f1ecb7afc87466c6413a777f60fcf1a2e3f;p=toppersjsp4bf%2Fsample-i2c.git

Doxygenコメントを整備
---

diff --git a/i2c-test/Doxyfile b/i2c-test/Doxyfile
index da072f4..fbcc21e 100644
--- a/i2c-test/Doxyfile
+++ b/i2c-test/Doxyfile
@@ -26,7 +26,7 @@ DOXYFILE_ENCODING      = UTF-8
 # identify the project. Note that if you do not use Doxywizard you need 
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "My Project"
+PROJECT_NAME           = "I2C Test"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
@@ -38,7 +38,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer 
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = 
+PROJECT_BRIEF          = "Test the I2C control task for Blackfin"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is 
 # included in the documentation. The maximum height of the logo should not 
@@ -194,7 +194,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # The TAB_SIZE tag can be used to set the number of spaces in a tab. 
 # Doxygen uses this value to replace tabs by spaces in code fragments.
 
-TAB_SIZE               = 8
+TAB_SIZE               = 4
 
 # This tag can be used to specify a number of aliases that acts 
 # as commands in the documentation. An alias has the form "name=value". 
@@ -217,7 +217,7 @@ TCL_SUBST              =
 # For instance, some of the names that are used will be different. The list 
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java 
 # sources only. Doxygen will then generate output that is more tailored for 
@@ -356,7 +356,7 @@ LOOKUP_CACHE_SIZE      = 0
 # Private class members and static file members will be hidden unless 
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
 # will be included in the documentation.
@@ -366,7 +366,7 @@ EXTRACT_PRIVATE        = NO
 # If the EXTRACT_STATIC tag is set to YES all static members of a file 
 # will be included in the documentation.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) 
 # defined locally in source files will be included in the documentation. 
@@ -437,7 +437,7 @@ CASE_SENSE_NAMES       = NO
 # will show members with their full class and namespace scopes in the 
 # documentation. If set to YES the scope will be hidden.
 
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 
 # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen 
 # will put a list of the files that are included by a file in the documentation 
@@ -657,7 +657,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = 
+INPUT                  = .
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -812,12 +812,12 @@ FILTER_SOURCE_PATTERNS =
 # Note: To get rid of all source code in the generated output, make sure also 
 # VERBATIM_HEADERS is set to NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body 
 # of functions and classes directly in the documentation.
 
-INLINE_SOURCES         = NO
+INLINE_SOURCES         = YES
 
 # Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct 
 # doxygen to hide any special comment blocks from generated source code 
@@ -1246,7 +1246,7 @@ SERVER_BASED_SEARCH    = NO
 # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will 
 # generate Latex output.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. 
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be 
diff --git a/i2c-test/i2c_subsystem.c b/i2c-test/i2c_subsystem.c
index ab9b144..d88b3d1 100644
--- a/i2c-test/i2c_subsystem.c
+++ b/i2c-test/i2c_subsystem.c
@@ -50,19 +50,19 @@ enum I2C_STATE {
 struct I2C_MASTER_CONTROL_TYPE {
     ID signal;                /**< データの送受信が全部終わったときに割り込みハンドラからタスクに知らせるためのセマフォ */
     ID blocking;            /**< I2Cペリフェラルへの排他アクセスのためのセマフォ */
-    unsigned short intr_state;    /**< TWIペリフェラルの割り込みステータスのコピー **/
-    volatile uint16_t *    clkdiv    ;
-    volatile uint16_t *    control    ;
-    volatile uint16_t *    master_ctl    ;
-    volatile uint16_t *    master_stat    ;
-    volatile uint16_t *    master_addr    ;
-    volatile uint16_t *    int_stat    ;
-    volatile uint16_t *    int_mask    ;
-    volatile uint16_t *    fifo_ctl    ;
-    volatile uint16_t *    fifo_stat    ;
-    volatile uint16_t *    xmt_data8    ;
-    volatile uint16_t *    rcv_data8    ;
-    volatile uint16_t *    slave_ctl    ;
+    unsigned short intr_state;         /**< TWIペリフェラルの割り込みステータスのコピー **/
+    volatile uint16_t *    clkdiv;      /**< TWI_CLCKDIVレジスタのアドレス **/
+    volatile uint16_t *    control;     /**< TWI_CONTROLレジスタのアドレス **/
+    volatile uint16_t *    master_ctl;  /**< TWI_MASTER_CTLレジスタのアドレス **/
+    volatile uint16_t *    master_stat; /**< TWI_MASTER_STATレジスタのアドレス **/
+    volatile uint16_t *    master_addr; /**< TWI_MASTER_ADDRレジスタのアドレス **/
+    volatile uint16_t *    int_stat;    /**< TWI_MASTER_STATレジスタのアドレス **/
+    volatile uint16_t *    int_mask;    /**< TWI_INT_MASKレジスタのアドレス **/
+    volatile uint16_t *    fifo_ctl;    /**< TWI_FIFO_CTLレジスタのアドレス **/
+    volatile uint16_t *    fifo_stat;   /**< TWI_FIFO_STATレジスタのアドレス **/
+    volatile uint16_t *    xmt_data8;   /**< TWI_XMT_DATA8レジスタのアドレス **/
+    volatile uint16_t *    rcv_data8;   /**< TWI_RCV_DATA8レジスタのアドレス **/
+    volatile uint16_t *    slave_ctl;   /**< TWI_MASTER_CTLレジスタのアドレス **/
 
 };
 
@@ -230,7 +230,11 @@ int i2c_master_write_read( int peripheral, int slave, unsigned char write_data[]
  * \brief i2c 割り込みサービスルーチン本体
  * \param peripheral I2Cペリフェラル番号。0から始まる。
  * \details
- * 割り込みサービスルーチンから呼び出す
+ * 割り込みサービスルーチンから呼び出す。この関数が割り込みハンドラの実体である。
+ * チップに複数のTWIペリフェラルがある場合には、引数に当該TWIペリフェラル番号を与えて呼び出す。
+ *
+ * 関数内部では、タスクに割り込みが入ったことを知らせ、ペリフェラルの割り込みステータスを
+ * 変数に退避してから戻る。
  */
 static void i2c_master_handler( int peripheral )
 {
@@ -255,9 +259,9 @@ static void i2c_master_handler( int peripheral )
 
 
 /**
- * \brief i2c 割り込みサービスルーチン
  * \details
- * ATT_ISRを使って静的コンフィギュレータで宣言する。
+ * TOPPERS/JSPでは、DEF_INHから割り込みハンドラに引数を渡せない。そのため、この関数内で
+ * i2c_master_handler() を引数0決め打ちで呼ぶ。
  */
 void i2c0_master_handler(void)
 {
@@ -267,6 +271,7 @@ void i2c0_master_handler(void)
 
 /**
  * \brief i2c イニシャライザ
+ * \param exinf ペリフェラル番号。TWI0ならば、0を渡す。
  * \details
  * I2C用のコントロールブロックのI2C相当部分を初期化する。
  */
diff --git a/i2c-test/i2c_subsystem.h b/i2c-test/i2c_subsystem.h
index aca9e86..f929ef0 100644
--- a/i2c-test/i2c_subsystem.h
+++ b/i2c-test/i2c_subsystem.h
@@ -1,7 +1,7 @@
 /**
  * \file i2c_subsystem.h
  *
- * \date 2012/07/16
+ * \date 2012/09/01
  * \author: takemasa
  * \brief twiペリフェラルをマスターモードで使用する
  *
@@ -30,7 +30,7 @@
  * I2Cxペリフェラルの初期化は、cfgファイルによって記述されたイニシャライザが行う。また、割り込みISRもcfgファイルによって登録
  * される。このほか、ペリフェラル電源のオン、クロックの設定もイニシャライザ内部で完結している。
  *
- * I2Cxペリフェラルへのピンの割り当ては、アプリケーションで行う。これに関しては例題、例えば 801_i2c_pcf8570プロジェクトを参照のこと。
+ * I2Cxペリフェラルへのピンの割り当てが必要な場合は、アプリケーションで行う。
  *
  * なお、I2Cサブシステムは、イニシャライザ内部でCMSISの   SystemCoreClockUpdate() 関数を使用してCPUのクロック周波数を
  * 測定している。この関数が常に正しく動作するのはCPUが内部RCオシレータを使用する場合と、RTCの32768Hzクロックを使用する場合のみである。
@@ -39,18 +39,27 @@
  */
 /*@{*/
 
+/**
+ * \brief TWIデバイス制御関数への引き数値が間違っている。
+ */
 #define I2C_ERR_WRONGPARAM      0x4000
+/**
+ * \brief TWIデバイス制御関数へ指定した送受信データ長が長すぎる。
+ */
 #define I2C_ERR_TOOLONGBUFFER   0x2000
+/**
+ * \brief TWIデバイスがタイムアウトした。
+ */
 #define I2C_ERR_TIMEOUT     0x1000
 
 /**
  * \brief i2cマスターモードの割り込みサービスルーチン
- * \param exinf i2cペリフェラルの番号。i2c0なら、0
+ * \param exinf i2cペリフェラルの番号。TWI0なら、0
  * \details
  * この間数は、i2cをマスターモードとして使う際の割り込みサービスルーチン本体である。 i2c_master_read()等の関数と強調しながら
  * 動作する。データ転送が終わると、あらかじめ設定されたコールバックを呼び出してタスクに通知する。
  *
- * exinfには、コンフィギュレーションファイルのATT_ISRから値を与える
+ * exinfには、コンフィギュレーションファイルのDEF_INHから値を与える
  */
 void i2c0_master_handler(void);
 
@@ -68,10 +77,10 @@ void i2c_master_initialize(VP_INT exinf);
 
 /**
  * \brief I2C マスター書き込み関数
- * \param peripheral マイコンのI2Cペリフェラルの番号。0,1,2のいずれか
+ * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
  * \param write_data ペリフェラルに書き込むデータ・バイト列
- * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。
+ * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
  * \return エラーがなければ0
  * \details
  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
@@ -82,9 +91,7 @@ void i2c_master_initialize(VP_INT exinf);
  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
  * 待ち状態になる。
  *
- * 返り値はプロトコルの処理ステータスである I2C_SETUP_STATUS_XXX と、I2C ステータス
- * レジスタの最後の値である I2C_I2STAT_M_XXXX がビット論理和された状態になっている。
- * それぞれの詳細は lpc17xx_i2c.h を参照。
+ * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
  * 正常終了ならオール0である。
  *
  */
@@ -92,10 +99,10 @@ int i2c_master_write( int peripheral, int slave, unsigned char write_data[], int
 
 /**
  * \brief I2C マスター読み込み関数
- * \param peripheral マイコンのI2Cペリフェラルの番号。0,1,2のいずれか
+ * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
  * \param read_data ペリフェラルから読み込むデータ・バッファ
- * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。
+ * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
  * \return エラーがなければ0。処理がタイムアウトならば処理ステータス
  * \details
  * 引数 peripheral を使って、アドレス slave のI2Cデバイスからの読み込みを行う関数。
@@ -106,9 +113,7 @@ int i2c_master_write( int peripheral, int slave, unsigned char write_data[], int
  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
  * 待ち状態になる。
  *
- * 返り値はプロトコルの処理ステータスである I2C_SETUP_STATUS_XXX と、I2C ステータス
- * レジスタの最後の値である I2C_I2STAT_M_XXXX がビット論理和された状態になっている。
- * それぞれの詳細は lpc17xx_i2c.h を参照。
+ * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
  * 正常終了ならオール0である。
  *
  */
@@ -116,12 +121,12 @@ int i2c_master_read( int peripheral, int slave, unsigned char read_data[], int r
 
 /**
  * \brief I2C マスター書き込み読み込み関数
- * \param peripheral マイコンのI2Cペリフェラルの番号。0,1,2のいずれか
+ * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0。
  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
  * \param write_data ペリフェラルに書き込むデータ・バイト列
- * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。
+ * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
  * \param read_data ペリフェラルから読み込むデータ・バッファ
- * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。
+ * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
  * \return エラーがなければ0。
  * \details
  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
@@ -135,9 +140,8 @@ int i2c_master_read( int peripheral, int slave, unsigned char read_data[], int r
  *
  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
  * 待ち状態になる。
- * 返り値はプロトコルの処理ステータスである I2C_SETUP_STATUS_XXX と、I2C ステータス
- * レジスタの最後の値である I2C_I2STAT_M_XXXX がビット論理和された状態になっている。
- * それぞれの詳細は lpc17xx_i2c.h を参照。
+ *
+ * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
  * 正常終了ならオール0である。
  *
  */