vmeslib

• 概要
• 関数リファレンス
• KEK vmelib との相違
• 更新履歴

概要

• 読み書き (データブロックの転送)
• メモリマッピング (モジュール上の領域へのポインタ経由のアクセス)
• 割り込み処理 (トリガハンドリングとか)

読み書き

VME バスのモジュール上のメモリからのデータブロックの読み出しまたは書き込みを行います．データの転送には、通常の方法（Programmed I/O）に加えて，DMA および Non-Blocking DMA を指定できます．VME 読み書き関連の関数は以下のとおりです．

• VMEIO* vme_open(int access_mode, int transfer_mode);
• int vme_close(VMEIO* handle);
• int vme_read(VMEIO* handle, off_t vme_address, void* buffer, size_t size);
• int vme_write(VMEIO* handle, off_t vme_address, const void* buffer, size_t size);

まず vme_open() でモードを指定してオープンし，ハンドルを取得します． これ以降，VME の読み書きに関する処理はこのハンドルを指定して行います．終了時には，vme_close() を呼んでリソースを開放します．

VME からのデータ読み出しは vme_read() で，データの書き込みは vme_write() で行います．VME のアクセスモード(アドレス幅とデータ幅)は，vme_open() の第1引数(access_mode)に以下のいずれかの値を渡して指定します．

  VME_A16D16  VME_A16D32
  VME_A24D16  VME_A24D32
  VME_A32D16  VME_A32D32

データ転送モードは，vme_open() の第2引数(transfer_mode)に以下のいずれかの値を渡して指定します．

  VME_NORMAL  (標準モード：Programmed I/O)
  VME_DMA     (DMA モード)
  VME_NBDMA   (Non-Blocking DMA モード)

DMA が利用できないデバイスで VME_DMA を指定した場合，または Non-Blocking DMA が利用できないデバイスで VME_NBDMA を指定した場合には，標準モード(VME_NORMAL の指定)となります．

関数の実行に失敗した場合，vme_open() は NULL を返し，それ以外の関数は -1 を返します．いずれの場合も，大域変数 errno が設定されます．

プログラム例: dma-test.c

メモリマッピング

VME バスのモジュール上のアドレス領域を，プロセスのアドレス空間にマッピングします．これにより，モジュール上のメモリやレジスタに，通常のポインタを使ってアクセスできるようになります．メモリマッピング関連の関数は以下のとおりです．

• VMEMAP* vme_mapopen(int access_mode, off_t vme_address, size_t size);
• int vme_mapclose(VMEMAP* handle);
• void* vme_mapbase(VMEMAP* handle);
• short* vme_word16(VMEMAP* handle, off_t offset);
• int* vme_word32(VMEMAP* handle, off_t offset);

まず vme_mapopen() によりメモリマッピングを行い，ハンドルを取得します．これ以降，マッピングに関する処理はこのハンドルを指定して行います． 終了時には，vme_mapclose() を呼んでリソースを開放します．

マッピングされた領域の先頭をアクセスするポインタは，vme_mapbase() で取得できます．また，マッピングされた領域中の任意の 16 bit または 32 bit ワードは，vme_word16() または vme_word32() によりアクセスできます．もちろん，vme_mapbase() が返すアドレスに自分でオフセットを加算してポインタアクセスをしても構いません．VME のアクセスモード(アドレス幅とデータ幅)は，vme_open() の第1引数(access_mode)に以下のいずれかの値を渡して指定します．

  VME_A16D16  VME_A16D32
  VME_A24D16  VME_A24D32
  VME_A32D16  VME_A32D32

関数の実行に失敗した場合，vme_mapopen() は NULL を返し，それ以外の関数は -1 を返します．いずれの場合も，大域変数 errno が設定されます．

プログラム例: map-test.c

割り込み処理

VME バスのモジュールが出す割り込み要求を処理します．割り込みの許可・不許可，割り込み待ち，割り込み要求状態の取得などが行えます．割り込み処理関連の関数は以下のとおりです．

• VMEINT* vme_intopen(int interrupt_number, int vector);
• int vme_intclose(VMEINT* handle);
• int vme_intsetvectormask(VMEINT* handle, int vector_mask);
• int vme_intsetautodisable(VMEINT* handle);
• int vme_intenable(VMEINT* int_handle);
• int vme_intdisable(VMEINT* int_handle);
• int vme_intwait(VMEINT* int_handle, int timeout_sec);
• int vme_intnowait(VMEINT* int_handle);
• int vme_intcheck(VMEINT* int_handle);
• int vme_intclear(VMEINT* int_handle);

まず vme_intopen() により割り込みを登録して，ハンドルを取得します．これ以降，割り込みに関する処理はこのハンドルを指定して行います． 終了時には，vme_intclose() を呼んでリソースを開放します．

使用する割り込みベクタの幅がシステムのデフォルト(vmedrv では 16bit)と異なる場合，vme_intsetvectormask() によりベクタの有効ビットを指定してください．8 bit のベクタを使用する場合，vector_mask は 0x00ff となります．

割り込みの許可・不許可は vme_intenable() および vme_intdisable() で行います．割り込みは，vme_intwait() または vme_intnowait() により取得できます．vme_intwait() は割り込み発生またはタイムアウトまで実行をブロックしますが，vme_intnowait() はブロックしません．vme_intcheck() によりブロックせずに割り込み状態を取得できます．vme_intcheck() により割り込み要求が検出された場合は，vme_intwait() または vme_intnowait() を呼び出してその割り込みを処理するか，int vme_intclear() によりクリアするかのいずれかが必要です．

使用するモジュールが割り込みサイクル終了後に割り込み要求を自動で解除しない場合，繰り返し割り込み処理ルーチンが呼ばれるのを避けるために，vme_intsetautodisable() を使用して割り込みの自動不許可を設定してください．この場合，割り込みを取得するたびに割り込み不許可になるので，次の割り込み待ちをする前に毎回 vme_intenable() を呼び出してください．

関数の実行に失敗した場合，vme_intopen() は NULL を返し，それ以外の関数は -1 を返します．いずれの場合も，大域変数 errno が設定されます．

プログラム例 1: intwait-test.c
プログラム例 2: intnowait-test.c

• vmeslib を使用するには，ソースで vmeslib.h をインクルードし，libvmeslib.a をリンクする必要があります．
• 将来の変更の際のソースコードの互換性を保つため，ハンドル構造体(VMEIO, VMEMAP, VMEINT)の内部に直接アクセスすることは避けてください．

関数リファレンス

• 読み書き関連

  VMEIO* vme_open(int access_mode, int transfer_mode)

  read() および write() を行うためにドライバをオープンし，ハンドルを返します．

  引数 access_mode は，VME にアクセスする際のアドレス幅とデータ幅を指定するもので，以下のいずれかの値をとります．

  VME_A16D16	アドレス16bit, データ16bit
  VME_A16D32	アドレス16bit, データ32bit
  VME_A24D16	アドレス24bit, データ16bit
  VME_A24D32	アドレス24bit, データ32bit
  VME_A32D16	アドレス32bit, データ16bit
  VME_A32D32	アドレス32bit, データ32bit

  引数 transfer_mode は，read() または write() でデータを転送する際の転送方法を指定するもので，以下のいずれかの値をとります．

  VME_NORMAL	標準モード (Programmed I/O)
  VME_DMA	DMAモード
  VME_NBDMA	Non-Blocking DMAモード

  vme_open() は，成功するとハンドルのポインタを返します．失敗の場合は NULL を返して大域変数 errno を設定します．

  int vme_close(VMEIO* handle)

  ドライバをクローズして，リソースを開放します．

  vme_close() は，成功すると 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_read(VMEIO* handle, off_t vme_address, void* buffer, size_t count)

  vme_address に指定された VME 上のアドレスから，count バイトのデータを読み出して，buffer が指す領域に格納します．1ワードの読み出しごとに VME の読み出しアドレスをインクリメントしていくので，最後のワードが読み出される VME アドレスは vme_address+count-WORD_SIZE (WORD_SIZEは 2 (16bitモード) または 4(32bitモード)) です．

  vme_read() は，成功すると読み出したデータのサイズを返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_write(VMEIO* handle, off_t vme_address, const void* buffer, size_t count)

  buffer が指す領域に格納されているcount バイトのデータを vme_address に指定された VME 上のアドレスへ書き込みます． 1ワードの書き込みごとに VME の読み出しアドレスをインクリメントしていくので，最後のワードが書き込まれる VME アドレスは vme_address+count-WORD_SIZE (WORD_SIZEは 2 (16bitモード) または 4(32bitモード)) です．

  vme_write() は，成功すると書き込んだデータのサイズを返します．失敗の場合は -1 を返して大域変数 errno を設定します．

• メモリマッピング関連

  VMEMAP* vme_mapopen(int access_mode, off_t vme_address, size_t size)

  vme_address から始まる size バイトの VME 上の領域をプロセスのアドレス空間にマッピングし，その領域にアクセスするためのハンドルを返します.

  引数 access_mode は，VME にアクセスする際のアドレス幅とデータ幅を指定するもので，以下のいずれかの値をとります．

  VME_A16D16	アドレス16bit, データ16bit
  VME_A16D32	アドレス16bit, データ32bit
  VME_A24D16	アドレス24bit, データ16bit
  VME_A24D32	アドレス24bit, データ32bit
  VME_A32D16	アドレス32bit, データ16bit
  VME_A32D32	アドレス32bit, データ32bit

  vme_mapopen() は，成功するとハンドルのポインタを返します．失敗の場合は NULL を返して大域変数 errno を設定します．

  int vme_mapclose(VMEMAP* map_handle)

  vme_mapopen() により作成されたマッピングを消去し，リソースを開放します．

  vme_mapclose() は，成功すると 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  void* vme_mapbase(VMEMAP* map_handle)

  マッピングされた領域の先頭を指すポインタを返します．

  short* vme_word16(VMEMAP* map_handle, off_t offset)

  マッピングされた領域中の先頭から offset バイト目の 16bit ワードを指すポインタを返します．

  int* vme_word32(VMEMAP* map_handle, off_t offset)

  マッピングされた領域中の先頭から offset バイト目の 32bit ワードを指すポインタを返します．

  int vme_mapcheck(VMEMAP* map_handle, off_t offset)

• 割り込み処理関連

  VMEINT* vme_intopen(int intrrupt_number, int vector)

  引数に指定された割り込み番号とベクタの割り込みを登録し，ハンドルを返します．interrupt_number の意味はシステム(OSやデバイスドライバ)によって異なりますが，一般的には IRQ を直接指定します．一部のシステムでは，どこかの設定ファイルに記述されたテーブルのエントリ番号を記述するようになっているものもあるようです．ちなみに，vmedrv では IRQ を直接指定します．

  vector 引数の値も，下位のシステムに直接渡されます．vmedrv のように，VME の割り込みベクタ値をそのまま指定するシステムの場合，vme_intsetvectormask() 関数によりベクタの有効ビットを指定してください．

  vme_intopen() は，成功するとハンドラのポインタを返します．失敗の場合は NULL を返して大域変数 errno を設定します．

  int vme_intclose(VMEINT* int_handle)

  登録された割り込みを削除し，リソースを開放します．

  vme_intclose() は，成功すると0を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intsetvectormask(VMEINT* handle, int vector_mask)

  vme_intopen() 関数で指定した vector の有効ビットマスクを指定します．例えば，8bit のベクタを使用する場合，vector_mask に 0x00ff を指定します．

  vme_intsetvectormask() は，成功すると0を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intsetautodisable(VMEINT* handle)

  割り込みサイクル終了時に自動で割り込み不許可を設定するようにします．これは，割り込みサイクル終了時に割り込み要求を自動でクリアしないようなモジュールを使用する場合に，繰り返し割り込み処理ルーチンが呼ばれてシステムが制御不能になるのを避けるために使用します．

  vme_intsetautodisable() は，成功すると0を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intenable(VMEINT* int_handle)

  割り込みを許可し，割り込みの処理を開始します．ここでの許可はドライバ，OS，VME コントローラ に対しての許可で，モジュール自体に対する許可ではないことに注意してください．割り込みの許可には，通常，モジュール上のレジスタの操作が必要です．

  vme_intenable() は，成功すると0を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intdisable(VMEINT* int_handle)

  割り込みを禁止し，割り込みの処理を停止します．

  vme_intdisable() は，成功すると0を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intwait(VMEINT* int_handle, int timeout_sec)

  timeout_sec に指定された時間を上限として，割り込みを待ちます．vme_intwait() の呼び出し前に割り込みが発生していたら，vme_intwait() はただちにリターンします．割り込みを取得して vme_intwait() からリターンした場合はその割り込みは「処理済み」となり，次の vme_intwait() (と vme_intnowait())では処理されません．ただし，これはモジュールの割り込みのクリアとは異なるので注意してください．モジュールの割り込みのクリアにはモジュール上のレジスタ操作が必要なことがあります．

  引数 timeout_sec に 0 を渡すと，タイムアウトの設定値は無限となります．

  vme_intwait() は，割り込みを取得すると，正の整数を返します．これは割り込み要求の数に対応することもありますが，保証されていません．タイムアウトでは 0 を返します．失敗の場合(VME割り込み待ち中にシグナル割り込みを受けた等)は -1 を返して大域変数 errno を設定します．ちなみに，シグナル割り込みを受けた場合の errno の値は EINTR です．

  int vme_intnowait(VMEINT* int_handle)

  実行をブロックせずに割り込みを取得します．実行をブロックしないことを除いて vme_intwait() と同じです．vme_intnowait() の呼び出し前に割り込みが発生していたら，vme_intnowait() はただちにリターンします．割り込みが発生していなければ，茄にもせずにただちにリターンします．割り込みを取得して vme_intnowait() からリターンした場合はその割り込みは「処理済み」となり，次の vme_intnowait() (とvme_intwait())では処理されません．ただし，これはモジュールの割り込みのクリアとは異なるので注意してください．モジュールの割り込みのクリアにはモジュール上のレジスタ操作が必要なことがあります．

  vme_intnowait() は，割り込みを取得すると，正の整数を返します．これは割り込み要求の数に対応することもありますが，保証されていません．vme_intnowait()呼び出しまでに割り込みが発生していなければ 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intcheck(VMEINT* int_handle)

  実行をブロックせずに割り込み状態を取得します．割り込み要求があっても，それは処理されません．割り込みが処理されないことを除いて vme_intnowait() と同じです．

  vme_intcheck() は，未処理の割り込み要求があれば，正の整数を返します．これは割り込み要求の数に対応することもありますが，保証されていません．未処理の割り込み要求がなければ 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

  int vme_intclear(VMEINT* int_handle)

  割り込み要求を「処理済み」としてクリアします．処理済みの割り込み要求は，これ以降の vme_intwait()，vme_intnowait() および vme_intcheck() では処理されなくなります．ただし，これはモジュールの割り込みのクリアとは異なるので注意してください．モジュールの割り込みのクリアにはモジュール上のレジスタ操作が必要なことがあります．

  vme_intclear() は，成功の場合 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

• その他

  int vme_tryget(int access_mode, off_t vme_address)

  引数 access_mode に指定されたアクセスモードで，引数 vme_address に指定されたアドレスからの1ワードの読み込みを行い，エラー状態をチェックします．他の VME 関数と違い，読み出しを行ったアドレスから正しく値が返されているか(すなわち，モジュールが正しく応答しているか)のチェックを行います．他の VME 関数では単に不定の値(普通は0xffffとか)を返してくるような場面でも，vme_tryget() はエラーを報告します．

  vme_tryget() は，この中でオープン，読み出し，クローズの全てを行うのでハンドルは必要ありません．ただし，この関数の中で行う処理が多いので，頻繁な呼び出しには向きません．最初のチェックに使うことを想定しています．

  vme_tryget() は，読み込みに成功すれば 0 を返します．失敗の場合は -1 を返して大域変数 errno を設定します．

KEK vmelib との相違

• vmeslib では，基本的に全てハンドル経由のアクセス．KEK vmelib では，ハンドル(に相当するもの)が内部で扱われているため，多重オープンに対応できない．
• vmeslib では，vme_XXXopen() 以外の関数の失敗時の戻り値が -1 に統一されている．KEK vmelib では，失敗時に errno を返すが，正常時に正の値を返す関数の場合エラーの判定が難しい．
• vmeslib では，vme_intwait() のタイムアウトはエラーとせず，戻り値に 0 を返すようにした．
• KEK vmelib にあった，アクセスエラー時にアボートする vme_mapprobe() 関数を廃止．かわりに，戻り値でエラーを伝える vme_tryget() 関数を提供．

更新履歴

2010年7月21日

0x80000000 以上のアドレスへアクセスした際にエラーになる不具合を修正

(細見さん(東北大)によるバグフィクスです．ありがとうございました)

2010年2月27日

vme_intsetvectormask() と vme_intsetautodisable() を追加

(細見さん(東北大)の提案・試験・バグフィクスによります．ありがとうございました)

2005年10月27日

Version 1.0