uzume_prototype/kernel/uzume/i2c_subsystem.h

   1 /**
   2  * \file i2c_subsystem.h
   3  *
   4  * \date 2012/09/01
   5  * \author: takemasa
   6  * \brief twiペリフェラルをマスターモードで使用する
   7  *
   8  */
   9 #include <kernel.h>
  10
  11 #ifndef I2C_SUBSYSTEM_H_
  12 #define I2C_SUBSYSTEM_H_
  13
  14 /**
  15  * \defgroup I2C_SUBSYSTEM  I2Cを使用するためのサブシステム
  16  * \details
  17  * i2c_subsystemは、LPC1768の内蔵I2Cペリフェラルを使用するための関数群である。この関数群はTOPPERS/ASP用に開発されており、CMSISの下位
  18  * ライブラリを使用して、割り込みを使ったポーリングなしの制御を実現している。タスクから呼び出された関数は割り込みハンドラとセマフォを使って
  19  * 通信しながら指定されたI2Cスレーブ・デバイスの制御を行う。また、関数群は排他制御されており、一つのi2Cペリフェラルを複数のタスクが同時に使用
  20  * しないよう保護されている。
  21  *
  22  * アプリケーションが使用するのは i2c_master_write(), i2c_master_read(), i2c_master_write_read() の三つの関数だけである。
  23  * この他にI2Cの初期化関数と割り込みISRがあるが、これらは TOPPERS/ASP のコンフィギュレーション・ファイルに記述されており、アプリケーション・
  24  * プログラマが直接呼び出してはならない。
  25  *
  26  * I2Cx ペリフェラルを使用する場合には、アプリケーションのコンフィギュレーションファイルから、i2cx_m.cfgファイルを読み込んでおく。
  27  * 例えば、I2C1を使いたいのであれば、i2c1_m.cfg ファイルを読み込む。i2c0_m.cfg から i2c2_m.cfg までのファイルがあり、
  28  * どのファイルをどの組み合わせでどの順番で読み込んでもかまわない。
  29  *
  30  * I2Cxペリフェラルの初期化は、cfgファイルによって記述されたイニシャライザが行う。また、割り込みISRもcfgファイルによって登録
  31  * される。このほか、ペリフェラル電源のオン、クロックの設定もイニシャライザ内部で完結している。
  32  *
  33  * I2Cxペリフェラルへのピンの割り当てが必要な場合は、アプリケーションで行う。
  34  *
  35  * なお、I2Cサブシステムは、イニシャライザ内部でCMSISの   SystemCoreClockUpdate() 関数を使用してCPUのクロック周波数を
  36  * 測定している。この関数が常に正しく動作するのはCPUが内部RCオシレータを使用する場合と、RTCの32768Hzクロックを使用する場合のみである。
  37  * 外部クリスタルを使ったメインオシレータを使用する場合は、クリスタルの共振周波数とCMSIS内部のクロック設定値をあわせてCMSISを再ビルド
  38  * しなければならない。
  39  */
  40 /*@{*/
  41
  42 /**
  43  * \brief TWIデバイス制御関数への引き数値が間違っている。
  44  */
  45 #define I2C_ERR_WRONGPARAM      0x40000
  46 /**
  47  * \brief TWIデバイス制御関数へ指定した送受信データ長が長すぎる。
  48  */
  49 #define I2C_ERR_TOOLONGBUFFER   0x20000
  50 /**
  51  * \brief TWIデバイスがタイムアウトした。
  52  */
  53 #define I2C_ERR_TIMEOUT     0x10000
  54
  55 extern void i2c_perror(UINT prio, const char *file, int line,
  56                     const char *expr, ER ercd) throw();
  57
  58 Inline ER
  59 _i2c_perror(const char *file, int line, const char *expr, ER ercd)
  60 {
  61     if (ercd < 0) {
  62         i2c_perror(LOG_ERROR, file, line, expr, ercd);
  63     }
  64     return(ercd);
  65 }
  66
  67 #define i2ccall(s)  _t_perror(__FILE__, __LINE__, #s, (s))
  68
  69
  70 /**
  71  * \brief i2cマスターモードの割り込みサービスルーチン
  72  * \param exinf i2cペリフェラルの番号。TWI0なら、0
  73  * \details
  74  * この間数は、i2cをマスターモードとして使う際の割り込みサービスルーチン本体である。 i2c_master_read()等の関数と強調しながら
  75  * 動作する。データ転送が終わると、あらかじめ設定されたコールバックを呼び出してタスクに通知する。
  76  *
  77  * exinfには、コンフィギュレーションファイルのDEF_INHから値を与える
  78  */
  79 void i2c0_master_handler(void);
  80
  81
  82 /**
  83  * \brief i2cマスターモード動作用の初期化を行う
  84  * \param exinf ペリフェラル番号を渡す. TWI0なら0。
  85  * \details
  86  * この関数は i2c0_master_handler() が i2c_master_read() 等の関数と同期するためのセマフォの設定を行う。
  87  * 呼び出しは明示的に行わず、コンフィギュレーションファイルからATT_INIを使ってシステムに登録する。
  88  *
  89  */
  90 void i2c_master_initialize(VP_INT exinf);
  91
  92
  93 /**
  94  * \brief I2C マスター書き込み関数
  95  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
  96  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
  97  * \param write_data ペリフェラルに書き込むデータ・バイト列
  98  * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
  99  * \return エラーがなければ0
 100  * \details
 101  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
 102
 103  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
 104  * 帰ってくる。
 105  *
 106  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
 107  * 待ち状態になる。
 108  *
 109  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
 110  * 正常終了ならオール0である。
 111  *
 112  */
 113 int i2c_master_write( int peripheral, int slave, unsigned char write_data[], int write_count );
 114
 115 /**
 116  * \brief I2C マスター読み込み関数
 117  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
 118  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
 119  * \param read_data ペリフェラルから読み込むデータ・バッファ
 120  * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
 121  * \return エラーがなければ0。処理がタイムアウトならば処理ステータス
 122  * \details
 123  * 引数 peripheral を使って、アドレス slave のI2Cデバイスからの読み込みを行う関数。
 124
 125  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
 126  * 帰ってくる。
 127  *
 128  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
 129  * 待ち状態になる。
 130  *
 131  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
 132  * 正常終了ならオール0である。
 133  *
 134  */
 135 int i2c_master_read( int peripheral, int slave, unsigned char read_data[], int read_count);
 136
 137 /**
 138  * \brief I2C マスター書き込み読み込み関数
 139  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0。
 140  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
 141  * \param write_data ペリフェラルに書き込むデータ・バイト列
 142  * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
 143  * \param read_data ペリフェラルから読み込むデータ・バッファ
 144  * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
 145  * \return エラーがなければ0。
 146  * \details
 147  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
 148  *
 149  * この間数は、まず slave に対して write_data バッファから write_count 個のデータを
 150  * 書き込む。続いて I2C の repeated start を使って同じ slave に対する read_count個の
 151  * 読み出しを行う。
 152  *
 153  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
 154  * 帰ってくる。
 155  *
 156  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
 157  * 待ち状態になる。
 158  *
 159  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
 160  * 正常終了ならオール0である。
 161  *
 162  */
 163 int i2c_master_write_read( int peripheral, int slave, unsigned char write_data[], int write_count, unsigned char read_data[], int read_count );
 164
 165 /*@}*/
 166
 167 #endif /* I2C_SUBSYSTEM_H_ */