i2c/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      0x4000
  46 /**
  47  * \brief TWIデバイス制御関数へ指定した送受信データ長が長すぎる。
  48  */
  49 #define I2C_ERR_TOOLONGBUFFER   0x2000
  50 /**
  51  * \brief TWIデバイスがタイムアウトした。
  52  */
  53 #define I2C_ERR_TIMEOUT     0x1000
  54
  55 /**
  56  * \brief i2cマスターモードの割り込みサービスルーチン
  57  * \details
  58  * この間数は、i2cをマスターモードとして使う際の割り込みサービスルーチン本体である。 i2c_master_read()等の関数と強調しながら
  59  * 動作する。データ転送が終わると、あらかじめ設定されたコールバックを呼び出してタスクに通知する。
  60  *
  61  * exinfには、コンフィギュレーションファイルのDEF_INHから値を与える
  62  */
  63 void i2c0_master_handler(void);
  64
  65
  66 /**
  67  * \brief i2cマスターモード動作用の初期化を行う
  68  * \param exinf ペリフェラル番号を渡す. TWI0なら0。
  69  * \details
  70  * この関数は i2c0_master_handler() が i2c_master_read() 等の関数と同期するためのセマフォの設定を行う。
  71  * 呼び出しは明示的に行わず、コンフィギュレーションファイルからATT_INIを使ってシステムに登録する。
  72  *
  73  */
  74 void i2c_master_initialize(VP_INT exinf);
  75
  76
  77 /**
  78  * \brief I2C マスター書き込み関数
  79  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
  80  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
  81  * \param write_data ペリフェラルに書き込むデータ・バイト列
  82  * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
  83  * \return エラーがなければ0
  84  * \details
  85  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
  86
  87  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
  88  * 帰ってくる。
  89  *
  90  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
  91  * 待ち状態になる。
  92  *
  93  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
  94  * 正常終了ならオール0である。
  95  *
  96  */
  97 int i2c_master_write( int peripheral, int slave, unsigned char write_data[], int write_count );
  98
  99 /**
 100  * \brief I2C マスター読み込み関数
 101  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0
 102  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
 103  * \param read_data ペリフェラルから読み込むデータ・バッファ
 104  * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
 105  * \return エラーがなければ0。処理がタイムアウトならば処理ステータス
 106  * \details
 107  * 引数 peripheral を使って、アドレス slave のI2Cデバイスからの読み込みを行う関数。
 108
 109  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
 110  * 帰ってくる。
 111  *
 112  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
 113  * 待ち状態になる。
 114  *
 115  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
 116  * 正常終了ならオール0である。
 117  *
 118  */
 119 int i2c_master_read( int peripheral, int slave, unsigned char read_data[], int read_count);
 120
 121 /**
 122  * \brief I2C マスター書き込み読み込み関数
 123  * \param peripheral マイコンのI2Cペリフェラルの番号。TWI0なら0。
 124  * \param slave 7bitで表すI2Cペリフェラルの番号。bit0:6のみ使い、bit7以上は0にすること。
 125  * \param write_data ペリフェラルに書き込むデータ・バイト列
 126  * \param write_count ペリフェラルに書き込むデータの長さ。単位はバイト。最大254。
 127  * \param read_data ペリフェラルから読み込むデータ・バッファ
 128  * \param read_count ペリフェラルから読み込むデータの長さ。単位はバイト。最大254。
 129  * \return エラーがなければ0。
 130  * \details
 131  * 引数 peripheral を使って、アドレス slave のI2Cデバイスに対する書き込みを行う関数。
 132  *
 133  * この間数は、まず slave に対して write_data バッファから write_count 個のデータを
 134  * 書き込む。続いて I2C の repeated start を使って同じ slave に対する read_count個の
 135  * 読み出しを行う。
 136  *
 137  * この関数はブロッキング関数である。つまり、読み込みを開始すると、その終了まで待って
 138  * 帰ってくる。
 139  *
 140  * また、複数のタスクが同時にこの関数を呼んだ場合には、うち一つだけが関数を実行し、他のタスクは
 141  * 待ち状態になる。
 142  *
 143  * 返り値はTWI_ERROR_XXXXと、TWIペリフェラルの割り込みステータスのビット論理和である。
 144  * 正常終了ならオール0である。
 145  *
 146  */
 147 int i2c_master_write_read( int peripheral, int slave, unsigned char write_data[], int write_count, unsigned char read_data[], int read_count );
 148
 149 /*@}*/
 150
 151 #endif /* I2C_SUBSYSTEM_H_ */