RASCSI/doc/rascsi_en.txt

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

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

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

-------------------------------------------------- ----------------------------
□ What is RaSCSI
  RaSCSI is a SCSI device (hard disk, MO, CD-ROM) that operates on the Raspberry Pi.
  It is a virtual emulator. Use with SHARP X68000 that adopts SCSI
  It was developed for that purpose. Raspberry Pi with RaSCSI installed on the X68000 SCSI
  Simply connect it to the connector and it will be recognized as a physical SCSI device.

  In addition to the X68000, it may be possible to use it with a retro PC such as FM TOWNS or PC 98 that adopted SCSI.
  May. The author has confirmed that it works with FM TOWNS and PC9821Ce.
  
  RaSCSI is a software that emulates SCSI devices plus Raspberry Pi
  Refers to the general term for the mechanism that converts a GPIO connector into a SCSI connector.

□ Operating environment
  (1) Raspberry Pi
    Raspberry Pi Zero
    Raspberry Pi Zero W
    Raspberry Pi Zero WH
    Raspberry Pi 2 Model B
    Raspberry Pi 3 Model B (recommended)
    Raspberry Pi 3 Model A+
    Raspberry Pi 3 Model B+
    Raspberry Pi 4 Model B

    Performance may be a little unstable with Zero/Zero W/Zero WH.

    3 Model A+/3 Model B+/4 Model B has high performance, but CPU clock is affected by heat.
    It may fluctuate, so it will be necessary to take measures.

  (2) OS
    Developed and tested by RASPBIAN BUSTER.
    RaSCSI uses GPIO to control SCSI signals, so latency is as low as possible.
    Must be used in the state of. Therefore, it is recommended to use it in CUI mode.
    To do.

□ Connection method with SCSI connector
  Since the situation has become complicated, we provide information on the RaSCSI home page.
  Please refer to the official website at the end of this document.

□ Handout
  The executable file, the document, and the source code are stored in the distributed archive.
  It is divided and included in the directory.

  bin/ ･･･ Executable file
    raspberrypi/ ･･･ RPI program
       rascsi.tar.gz ･･･ The tar+gzip of the executable file.

    x68k/ ･･･ Dedicated driver for X68000
       RASDRIVER.XDF... A floppy image containing two drivers
       RASDRIVER.HDS... A SCSI HD image containing two drivers
       RASDRIVER.HDF... SASI HD image containing two drivers

  doc/ ･･･Documents
    rascsi.txt ･･･ This document
    x68k.txt ･･･ Description of X68000 specific functions
    converter.txt ･･･ Description of converter board
    pinassign.png ･･･ Pin assignment diagram
    target.png ･･･ Conversion board circuit pattern (target mode)
    fullspec.png ･･･Conversion board circuit pattern (full spec)

  src/ ･･･ Source code
    raspberrypi/ ･･･ Set of program source for RPI
    x68k/ ･･･ Set of programs for X68000


  The program used in RPI is rascsi.tar.gz, so transfer it to RPI and decompress it.
  Please. It is recommended to unzip on RPI to maintain permissions etc.

  rascsi.tar.gz contains standard, fullspec, aibom and gamernium directories.
  I am.

  Executable file in the standard directory when using a direct connection cable or direct connection board
  Please use.

  Similarly, in the case of the conversion board described as the full spec version, in the fullspec directory
  I will use one (I think that it works even if it is directly connected).

  For the aibom and gamernium directories, use the conversion boards of "Aibomu version" and "GAMERnium version".
  It is when using.

  The driver for X68000 includes the following two in RASDRIVER.XDF or RASDRIVER.HDS
  It is
    RASDRV.SYS ･･･ Host drive driver
    RASETHER.SYS ･･･ Ethernet driver

□ How to use RASCI main unit (rascsi)

  When ID is specified
   rascsi [-IDn FILE] ...
    n:0 ~ 7

  When specifying HD (compatible with HD specification of X68000 SASI machine)
   rascsi [-HDn FILE] ...
    n: 0 ~ 15

  Since root authority is required, it is necessary to start with sudo etc.
  If you add -h to the option, a simple HELP will be displayed

  Usage: rascsi [-IDn FILE] ...

   n is SCSI identification number(0-7).
   FILE is disk image file.

  Usage: rascsi [-HDn FILE] ...

   n is X68000 SASI HD number(0-15).
   FILE is disk image file.

   Image type is detected 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)

  In the argument, one SCSI (SASI) device can be specified by a pair of -IDn or -HDn and FILE.
  -The number after the ID is the SCSI (SASI) ID. You can specify 0-7 as the ID, but usually the retro PC body
  I think you are using ID7 etc. as the initiator. In that case, specify 0-6
  It will be.

  FILE is the file path of the virtual disk image. The image file name has an extension
  Is required. The type of HD, MO, CD is determined by the extension.

  Example) When you specify HDIMAGE0.HDS for SCSI ID0 and HDIMAGE1.HDS for ID1 and start up,
    sudo rascsi -ID0 HDIMAGE0.HDS -ID1 HDIMAGE1.HDS

  When you finish, press CTRL+C to stop.
  If it is started in the background, is the kill command an INT signal to the relevant process?
  It ends by sending a HUP signal.

  After starting, rascsi opens a socket (6868 port) and receives external management commands.
  It is ready to be attached. Therefore, rascsi has already started as another process.
  If so, the boot will abort with an error message.

□ How to use the management tool (rasctl)
  We provide a management tool called rasctl from version 1.10. This is the rascsi process
  Disk is running in the background (waiting for connection on port 6868)
  It is possible to issue operation commands. The command line is as follows.

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

      ID: SCSI ID (0 to 7)
      UNIT: Unit number (0 or 1)
      CMD: Operation command
             attach: attach disk
             detach: detach disk
             insert: insert media (MO or CD only)
             eject: Eject media (MO or CD only)
             protect: Write protect the media (MO only)
      TYPE: Disc type
             hd: Hard disk (SASI/SCSI)
             mo: MO (magneto-optical disk)
             cd: CDROM (CDROM drive)
             bridge: Bridge device
      FILE: Path of disk image file

  ID is required. UNIT defaults to 0 (default is 0 for SCSI).
  CMD is interpreted as attach when omitted. TYPE is the extension of FILE when the command is attach
  It will automatically judge from. FILE has a different extension if TYPE is explicitly specified.
  does not matter. Basic interpretation of CMD and TYPE is case insensitive. Only the first letter
  Judging.

  Command example
    rasctl -i 0 -f HDIMAGE0.HDS

  Is 0, the SCSI ID is 0. CMD is attach by default and TYPE is determined from the extension HDS
  Therefore, it is supposed to be hd and it is equivalent to the option specification when starting rascsi.

  If only -l option is specified to check the current status, the device list is displayed.
  Will be done. The command line is as follows.

    rasctl -l

  You do not need root privileges to start rasctl itself.

□ How to use Disk Dump Tool (rasdump)
  Sample program for direct connection or direct connection board, or full-spec board.

  As the name suggests, it dumps (optionally restores) the image of SCSI HDD or MO.
  Specify your own ID as BID. If omitted, 7 is used.

    rasdump -i ID [-b BID] -f FILE [-r]
     ID: SCSI ID of the target device
     BID: RaSCSI's own SCSI ID
     FILE: dump file name
     -r: Restore mode

  Since it is a sample, only the minimum necessary processing is implemented, so do not modify it
  Please use.

□ How to use SASI dedicated disk dump tool (sasidump)
  A dump tool created for SASI based on rasdump.
  Dump (optionally restore) the SASI HD image.

    sasidump -i ID [-u UT] [-b BSIZE] -c COUNT -f FILE [-r]
     ID: SASI ID of the target device
     UT: UNIT ID of the target device
     BSIZE: Block size (default 512)
     COUNT: Number of blocks
     FILE: dump file name
     -r: Restore mode

□ When compiling the executable file from the source
   Standard edition
     make CONNECT_TYPE=STANDARD

   Full spec version
     make CONNECT_TYPE=FULLSPEC

   Aibomu version
     make CONNECT_TYPE=AIBOM

   GAMERnium version
     make CONNECT_TYPE=GAMERNIUM
 
□ Supported disk images
  (1) SCSI hard disk
    HDS file format (extension HDS/HDN/HDI/NHD/HDA)
    The file size can be any size within the range of 10MB to 4095MB (in 512-byte units)

    If the extension is "HDN", a genuine hard disk for NEC genuine 55 board (PC-9801-55)
    Perform emulation. For information returned by INQUIRY and MODE SENSE size
    There is a difference.

    If the extension is "HDI" or "NHD", the PC98 emulator is Annex86 or T98Next.
    It is intended to use a SCSI hard disk image. Some information as in HDN
    Is converted for NEC.

    If the extension is "HDA", APPLE genuine hard disk emulation is performed.
    There is a difference in the information returned by INQUIRY and MODE SENSE.

  (2) SASI hard disk
    HDF file format (extension HDF)
    File size is either 10441728 bytes, 20748288 bytes, or 41496576 bytes
    We recommend 10MB drive, 20MB drive and 40MB drive respectively.
    Any file size from 10M to 512M can be mounted in 256-byte units.

    Images from version 1.46 to 22437888 bytes are for MZ-2500/MZ-2800 MZ-1F23
    Recognized as a 20MB image (special image with a block size of 1024).

  (3) SCSI magneto-optical (MO) disk
    MOS file format (extension MOS)
    File size is one of the following four types:
      128MB type (127398912 bytes)
      230MB type (228518400 bytes)
      540MB type (533248000 bytes)
      640MB type (635600896 bytes)
    128MB, 230MB, 540MB is 512 bytes/sector and 640MB is 2048 bytes/sector.

  (4) SCSI CD-ROM disk
     ISO file format (extension ISO, ISO9660 solid image)
     Record in a file containing only data and in RAW format in mode 1 (2048 bytes/sector)
     Both files are supported.

□ Disk image creation
  RaSCSI itself is a derivative of the XM6 TypeG, an X68000 emulator. Therefore the disc
  It is assumed that the image is created from the "Tools" menu of XM6 TypeG.
  Of course, you can also create an empty image file with dd etc. according to the specifications explained above.
  Is possible.

  Example) When creating a 100 MB HDS image (empty file)

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

□ Operation record
  The author's development environment X68000 PRO (built-in SASI/genuine SCSI board), X68030 built-in SCSI,
  We have confirmed the operation with the XVI Compact built-in SCSI. It also worked on Mach-2.

  Since there were other operation reports on the first generation X68000, ACE, EXPERT, XVI, PRO2, SUPER, etc.,
  The X68000 series should be fine.

  For other retro PCs, FM TOWNS series, Apple Macintosh, MSX (using MEGA-SCSI)
  There is an operation report in. There are many reports that the PC98 series worked, but
  Some SCSI boards do not even work at all.

□ How to use
　If you are using an X68000 emulator such as XM6, HDD that is built by the emulator
  You can connect to the actual X68000 machine by transferring the image to the Raspberry Pi by FTP etc.
  The reverse is also true, and the HDD image that stores the files that exist on the actual machine is FTPed to the PC, etc.
  You can use it in the emulator by transferring with.

□ License
  RaSCSI is software distributed as is "AS IS".
  
  That is, we do not take any responsibility for any damages that the user receives. Soft again
  We are not responsible for fixing any defects or defects in the software.

  There is a risk that the Raspberry Pi and retro PC will break down by using RaSCSI.
  Please challenge at your own risk.

  As with XM6 TypeG, we are not allowed to distribute it on other than my HP due to the nature of experimental results disclosure.

  As it inherits the license terms of XM6, introduction in magazines/books requires prior permission.
  In the first place, I think only a limited number of people will respond to SCSI in 2019.

□About distribution of conversion boards
  If you want to distribute the conversion board for a fee, it is not necessary to obtain permission from the author as long as you follow the conditions below.
  There is none. It is important to provide enough information to the user who purchased the board.
  Please understand.

  1.Distribution price
    Board production cost + parts cost + transportation cost + (general social convention) fee.

  2. Schematic
    Please provide the buyer with the schematic. Simultaneously with board distribution or separately from homepage
    There are no restrictions on the means of downloading.

  3. Operation verification
    Operation verification of the X68000 actual machine environment is mandatory. If you can not get the real machine X68000
    You may ask the user to cooperate with the verification. Operation verification is other than startup confirmation
    Please write and load test. Verification results are published together with the environment in which they were used
    please do it.

□ About conversion board (official version)
  It has been distributed on BOOTH since March 2019 (it is irregular because the number is limited).

□ Public homepage
  http://retropc.net/gimons/rascsi/

□ Contact information
  twitter https://twitter.com/kugimoto0715
  e-mail gimons.developer.works@gmail.com

[EOF]