RASCSI/doc/rascsi.txt

------------------------------------------------------------------------------

 SCSI Target Emulator RaSCSI (*^..^*)
 version 1.34 for Raspberry Pi

 Powered by XM6 TypeG Technology.
 Copyright (C) 2016-2018 GIMONS

------------------------------------------------------------------------------
□RaSCSIとは
  RaSCSIはRaspberry Piで動作するSCSIデバイス(ハードディスク，MO，CD-ROM)を
  仮想的に再現するエミュレータです。SCSIを採用したSHARPのX68000で使用する
  ことを目的として開発しました。RaSCSIを導入したRaspberry PiをX68000のSCSI
  コネクタに接続するだけで物理的なSCSIデバイスとして認識されます。

  X68000以外にもSCSIを採用したFM TOWNSやPC98等のレトロPCでも使用できるかも
  しれません。作者はFM TOWNSとPC9821Ceで動作するところまでは確認しています。
  
  RaSCSIはSCSIデバイスをエミュレートするソフトウェアに加えてRaspberry Piの
  GPIOコネクタをSCSIコネクタに変換する機構の総称を指します。

□動作環境
  (1)Raspberry Pi
    Raspberry Pi 3 Model B を推奨します。

    Raspberry Pi 2 Model BやZeroでも動作すると考えられます。
    ピンアサインを独自に変更しRaspberry Pi 1で動作させたという報告もあります。

  (2)OS
    RASPBIAN STRETCHで開発およびテストしています。
    sudo apt-get update及びsudo apt-get upgradeで最新にしています。
    このドキュメントを記述している時点で"Linux raspberrypi 4.14.34-v7+"です。

    RaSCSIはSCSI信号をGPIOを利用して制御しているので可能な限り低レイテンシー
    の状態で使用する必要があります。したがってCUIモードで利用することを推奨
    します。更に不要なサービスは極力停止して下さい。

□SCSIコネクタとの接続方法
  状況が複雑になってきましたのでRaSCSIのホームページ上で情報提供しています。
  このドキュメントの最後にある公式ホームページを参考にして下さい。

□配布物
  配布するアーカイブには実行ファイル、ドキュメント、ソースコードのそれぞれが
  ディレクトリで分かれて含まれています。

  bin/ ･･･ 実行ファイル
    raspberrypi/ ･･･ RPI用のプログラム
       rascsi.tar.gz ･･･ 実行ファイルとカーネルモジュールをtar+gzipしたもの。

    x68k/ ･･･ X68000用のプログラム
       RASDRV.SYS ･･･ ホストドライブドライバ
       RASETHER.SYS ･･･ イーサネットドライバ

  doc/ ･･･ ドキュメント
    rascsi.txt ･･･ 当ドキュメント
    x68k.txt ･･･ X68000固有機能の説明
    converter.txt ･･･ 変換基板の説明
    pinassign.png ･･･ ピンアサイン図
    target.png ･･･ 変換基板回路図案(ターゲットモード)
    initiator.png ･･･ 変換基板回路図案(イニシエータサポート)
    fullspec.png ･･･ 変換基板回路図案(フルスペック)

  src/ ･･･ ソースコード
    raspberrypi/ ･･･ RPI用のプログラムソース一式
    x68k/ ･･･ X68000用のプログラム一式


  RPIで使用するプログラムはrascsi.tar.gzですのでRPI上に転送してから解凍して
  下さい。パーミッション等を維持するためにRPI上で解凍することを推奨します。

  rascsi.tar.gzにはstandard,fullspec,aibom,gamerniumのディレクトリが含まれ
  ています。通常はstandardディレクトリにある実行ファイルを使用して下さい。
  
  aibom,gamerniumディレクトリのものは"あいぼむ版","GAMERnium版"の変換基板を
  使用する時のものです。

  fullspecディレクトリのものは公開したフルスペック版変換基板の回路図案で
  変換基板を作成した時に使用する時のものです。

□RASCI本体の使用方法(rascsi)

  sudo rascsi [-ID{01234567} FILE] ...

  ルート権限が必要ですのでsudo等で起動する必要があります。
  オプションに-hを付けると簡単なHELPが表示されます

    Usage: ./rascsi [-ID{0|1|2|3|4|5|6|7} FILE] ...

     ID is SCSI identification number.
     FILE is disk image file.

     Detected images type based on file extension.
      hdf : SASI HD image(XM6 SASI HD image)
      hds : SCSI HD image(XM6 SCSI HD image)
      hdn : SCSI HD image(NEC GENUINE)
      hdi : SCSI HD image(Anex86 HD image)
      nhd : SCSI HD image(T98Next HD image)
      hda : SCSI HD image(APPLE GENUINE)
      mos : SCSI MO image(XM6 SCSI MO image)
      iso : SCSI CD image(ISO 9660 image)

  引数では-ID{01234567}とFILEの一組で一つのSCSIデバイスを指定できます。

  -IDの後ろの番号はSCSI IDです。SCSI IDは0-7を指定できますが通常レトロPC本体
  がイニシエータとしてID7等を使用していると思います。その場合は0-6を指定する
  ことになります。

  FILEは仮想ディスクイメージのファイルパスです。イメージファイル名には拡張子
  が必要です。拡張子によってHD,MO,CDの種別を判定しています。

  例)SCSI ID0にHDIMAGE0.HDS,ID1にHDIMAGE1.HDSを指定して起動する場合、
    sudo rascsi -ID0 HDIMAGE0.HDS -ID1 HDIMAGE1.HDS

  終了する場合はCTRL+Cで停止します。
  バックグラウンドで起動した場合にはkillコマンド該当プロセスにINTシグナルか
  HUPシグナルを送ることで終了します。

  rascsiは起動後にソケット(6868ポート)を開いて外部からの管理コマンドを受け
  付ける状態になります。したがって既に別プロセスとしてrascsiが起動している
  場合はエラーメッセージとともに起動を中断します。

□管理ツールの使用方法(rasctl)
  バージョン1.10からrasctlという管理ツールを提供します。これはrascsiプロセス
  がバックグラウンドで起動(6868ポートで接続待ちの状態)している場合にディスク
  操作のコマンドを発行することが可能となります。コマンドラインは下記の通り。

    rasctl -i ID [-c CMD] [-t TYPE] [-f FILE]

      ID   : SCSI ID
      CMD  : 操作コマンド
             attach  : ディスクを取り付ける
             detatch : ディスクを取り外す
             insert  : メディアを挿入する(MOまたはCDのみ)
             eject   : メディアを取り出す(MOまたはCDのみ)
             protect : メディアを書き込み禁止にする(MOのみ)
      TYPE : ディスク種別
             hd      : ハードディスク(SASI/SCSI)
             mo      : MO(光磁気ディスク)
             cd      : CDROM(CDROMドライブ)
             bridge  : ブリッジデバイス
      FILE : ディスクイメージファイルのパス

  IDは必須です。CMDは省略時はattachと解釈します。TYPEはコマンドがattachの
  場合にはFILEの拡張子から自動判定します。FILEはTYPEを明示的に指定している
  場合は拡張子が異なっても構いません。基本的CMD,TYPEの解釈は大文字小文字を
  無視します。現在のところ最初の1文字でのみ判定しています。

  コマンド例
    rascsi -i 0 -f HDIMAGE0.HDS

  の場合はSCSI IDは0。CMDはデフォルトでattachでありTYPEは拡張子HDSから判断
  するのでhdと推測することになりrascsi起動時のオプション指定と同等です。

  現在の状態を確認するにために-lオプションのみを指定するとデバイス一覧が表示
  されます。コマンドラインは下記の通り。

    rasctl -l

  rasctl自体の起動にはルート権限は必要ありません。

□ディスクダンプツールの使用方法(rasdump)
  直結もしくは直結基板、またはイニシエータ対応とした変換基板向けのサンプル
  プログラムです。現在のところ変換基板では"あいぼむ版"のみ対応してます。

  名前の通りSCSI HDDやMOのイメージをダンプ(オプションでリストア)します。
  自身のIDはBIDで指定して下さい。省略時は7を使用します。

    rasdump -i ID [-b BID] -f FILE [-r]
     ID   : ターゲットデバイスのSCSI ID
     BID  : RaSCSI自身のSCSI ID
     FILE : ダンプファイル名
     -r  ： リストアモード

  サンプルなので必要最低限の処理しか実装していませんので改造するなりして
  ご使用下さい。

□カーネルモジュールの導入方法(rascsidrv.ko)
  version 1.24から安定化のためにGPIO制御の一部をカーネルモジュールで動作
  させる拡張を加えました。
  
  カーネルモジュールを導入しなくても動作できますが、X68000シリーズのSASI
  を使用する場合や純正SCSIボードを増設した場合はカーネルモジュールの導入
  を行っていないと動作が不安定になります。

  カーネルモジュールを有効にするには

    sudo insmod rascsidrv.ko

  を実行してください。

  カーネルモジュールの起動を確認するにはdmesgコマンドで出力されるログの
  最後に次のような表示がされている筈です。

  "RaSCSI GPIO Driver Loaded(STANDARD)"

  注意！
  カーネルモジュールは使用中のOSのバージョンに依存します。

  rascsiやrasctlと同じ階層にあるrascsidrv.koはRaspberry Pi 2/3用の
  "Linux raspberrypi 4.14.34-v7+"でコンパイルしたモジュールになります。

  同じ階層のrpi1orZero/rascsidrv.koはRaspberry Pi 1/Zero用です。
  "Linux raspberrypi 4.14.34+"でコンパイルしたモジュールになります。

  自身でカーネルモジュールをコンパイルする手順を簡単に記しておきます。

  ・OSの最新化
    sudo apt-get update
    sudo apt-get upgrade
    sudo reboot

  ・カーネルヘッダー取得
    sudo apt-get install raspberrypi-kernel-headers

  ・コンパイル
    cd kernelmodule
    make
 
□サポートするディスクイメージ
  (1)SCSI ハードディスク
    HDSファイル形式    (拡張子HDS/HDN/HDI/NHD/HDA)
    ファイルサイズは10MB以上4095MB以下の範囲で任意のサイズ(但し512バイト単位)

    拡張子が"HDN"の場合はNEC純正55ボード(PC-9801-55)向けの純正ハードディスク
    エミュレーションを行います。INQUIRYで返却される情報やMODE SENSEのサイズに
    に違いがあります。

    拡張子が"HDI","NHD"の場合はそれぞれPC98エミュレータであるAnex86及びT98Next
    のSCSIハードディスクイメージを使用するものです。HDNの時と同様に一部の情報
    がNEC用に変換されます。

    拡張子が"HDA"の場合はAPPLE純正ハードディスクエミュレーションを行います。
    INQUIRY及びMODE SENSEで返却される情報に違いがあります。

  (2)SASI ハードディスク
    HDFファイル形式    (拡張子HDF)
    ファイルサイズは10441728バイト、20748288バイト、41496576バイトのいずれか
    (それぞれ10MBドライブ、20MBドライブ、40MBドライブに対応)

  (3)SCSI 光磁気(MO)ディスク
    MOSファイル形式    (拡張子MOS)
    ファイルサイズは次の4種類のいずれか：
      128MBタイプ (127398912バイト)
      230MBタイプ (228518400バイト)
      540MBタイプ (533248000バイト)
      640MBタイプ (635600896バイト)
    128MB,230MB,540MBは512バイト/セクタ、640MBは2048バイト/セクタになります。

  (4)SCSI CD-ROMディスク
     ISOファイル形式   (拡張子ISO、ISO9660ベタイメージ)
     モード1(2048バイト/セクタ)で、データのみ格納されたファイルとRAW形式で記録
     されたファイルの両方に対応しています。

□ディスクイメージの作成
  RaSCSI自体がX68000エミュレータであるXM6 TypeGの派生物です。従ってディスク
  イメージの作成はXM6 TypeGの「ツール」メニューから行うことを前提としています。
  もちろん先に説明した仕様に従えばdd等で空のイメージファイルを作成することも
  可能です。

  例）100MBのHDSイメージ(空ファイル)を作る場合

    dd if=/dev/zero of=HARDDISK.HDS bs=512 count=204800

□動作実績
  作者の開発環境であるX68000 PRO(内蔵SASI/純正SCSIボード)、X68030 内蔵SCSI、
  XVI Compact 内蔵SCSIで動作確認しています。Mach-2でも動作しました。

  他にも初代X68000,ACE,EXPERT,XVI,PRO2,SUPER等で動作報告がありましたので、
  X68000シリーズはほぼ問題ないでしょう。

  その他のレトロPCではFM TOWNSシリーズ、PC98シリーズ、Apple Macintosh、
  MSX(MEGA-SCSI利用)で動作報告があります。
  
  その他の機種でもちらほらと動作報告を頂いています。

□活用方法
　XM6等のX68000エミュレータを使用している場合はエミュレータで環境構築したHDD
  イメージをFTP等でRaspberry Piに転送することでX68000の実機に接続できます。
  またその逆も然りで実機上に存在するファイルを格納したHDDイメージをPCにFTP等
  で転送することでエミュレータで活用することができます。

□ライセンス
  RaSCSIはカーネルドライバを除きあるがまま"AS IS"で配布されるソフトウェアです。
  カーネルドライバのソースrascsidrv.cのみGPLです(御察っし下さい)。
  
  つまり使用者が受けたあらゆる損害に対して一切責任を持ちません。またソフト
  ウェアに不備もしくは不具合があったとしてもそれを修正する責任もありません。

  RaSCSIを利用することでRaspberry PiやレトロPCが故障するリスクがあります。
  あくまで自己責任でチャレンジしてください。

  XM6 TypeG同様に実験成果公開という性質上私のHP以外での配布を認めておりません。

  XM6のライセンス条項を継承していますので雑誌/書籍での紹介事前の許諾が必要です。
  そもそも2017年にもなってSCSIに反応するのは限られた人だけだと思います。

□変換基板の頒布について
  変換基板の頒布については作者に許諾を得る必要はありません。
  一応ご連絡いただければ何かとサポートできるかもしれません。
  
  但しレトロPCのSCSI環境改善を応援するという趣旨から、
  有料の場合は

  基板製作費 ＋ パーツ費用 ＋ 運送費 ＋（社会通念上一般的な）手数料
  
  を大きく越えるような頒布についてはお止め下さい。

□公開ホームページ
  http://www.geocities.jp/kugimoto0715/rascsi/index.html

□連絡先
  twitter        https://twitter.com/kugimoto0715
  e-mail         kugimoto0715@yahoo.co.jp

[EOF]