# PiSCSI Interface/Device driver for Amiga
-Intended to be used as a high performance replacement for scsi.device, can currently be used for mounting raw RDB disk images (RDSK) for use in Workbench.
-
-This driver and interface is work in progress, do not use it in conjunction with any critical data that you need to survive.
+A high performance replacement for scsi.device, allowing automatic booting and mounting of raw hard disk (RDB/RDSK) images.
+
+While this driver is considered mostly stable, it's still work in progress. Do not use it in conjunction with any critical one of a kind data that you need to survive.
+
+# Compatibility
+
+* PiSCSI **requires** some Fast RAM to be mapped on your PiStorm to work.
+ * This may change at some point, but for now make sure that you configure at the very least a few megabytes of Fast RAM so that the boot ROM can load and initialize properly.
+* ~~PiSCSI **only** supports **512 byte** block size for virtual SCSI devices.~~
+ * ~~The block size is hard coded, this will probably be addressed relatively soon (TM). If you need very large partitions, please use PFS3AIO or a similar file system instead of FFS.~~
+ * ~~Selecting a different block size may appear to work in some cases, but in reality it does not. Do not change the block size from the default 512 bytes.~~
+* `[WIP]` Theoretically, PiSCSI should now be compatible with any block size up to 64KB, but this is not very thoroughly tested when you are reading this particular piece of text.
+* Autobooting, Kickstart 2.0 and up
+ * PiSCSI does NOT work with Kickstart 1.3 yet, as it is missing some code needed to properly add boot nodes with old Kickstarts.
+* Mounting RDSK/RDB disk images, physical devices with a file system the Amiga can use
+ * PiSCSI **does NOT** work with **specifically UAE single partition** disk images prepared and formatted using WinUAE yet. You can check what type the disk image is using a hex editor, if it starts with `RDSK`, it is a full drive RDSK/RDB image, if it starts with `DOS` it is most likely a UAE single partition disk image.
+ * It **does** however work with any UAE disk image prepared using the **Full drive/RDB mode** selected in the Hardfile settings. Using **Full drive/RDB mode** in for instance WinUAE requires you to click the button labeled with this exact piece of text.
+ * When mounting a physical drive for use with PiSCSI, please read the `A big word of caution` at the bottom of this page
+* TrackDisk, TrackDisk64 and Direct SCSI
# Instructions
-In a perfect world, the PiSCSI boot ROM would automatically detect drives/partitions and add them as boot nodes to be available during early startup, but this is not yet possible.
+To use the PiSCSI interface, simply enable it by uncommenting the `setvar piscsi` line in default.cfg, or add it to the config file you're currently using.
+
+Add disk images to the PiSCSI interface by uncommenting the `piscsi0` and `piscsi1` lines and editing them to point at the disk image(s) you want to use.
+
+Physical drives can also be mounted using their mount point files on Linux, such as `/dev/sda` for a USB stick, but keep in mind that this is dangerous as it can destroy the contents of the disk if you're unluck or you repartition it.
+
+You can mount up to 7 disk images using setvar `piscsi0` through `piscsi6`.
+
+For preparing a disk image **on your Amiga with a PiStorm connected**, you can for instance make a copy of the Workbench tool `HDToolBox`, and then edit the tooltypes (`Icon -> Information` menu) to use `pi-scsi.device` instead of `scsi.device`.
+
+**No copying of the pi-scsi.device driver to `DEVS:` or anything like that is necessary, as the driver is loaded from ROM on boot/config time.**
+
+If you want EVEN MORE speed, either adjust the size of your hard drive image so that it gets properly detected with 16 heads in HDToolBox or manually edit the Cylinders/Heads settings when setting up your drive. Creating a disk image that is a multiple of **504 megabytes** seems suitable for this purpose.
+
+(The trackdisk device on the Amiga seems to enable transfers bigger than 512 bytes (one sector) only if the drive is identified as having more than one drive head/surface.)
+
+# Making changes to the driver
+
+If you make changes to the driver, you can always test these on the Amiga as a regular file in `DEVS:`, but the Z2 device has to be disabled for this to work properly. Disabling the Z2 device requires you to comment out the line `ac_z2_type[ac_z2_pic_count] = ACTYPE_PISCSI;` in `amiga-platform.c`.
+
+Steps to create an updated boot ROM, all of these are done in the `device_driver_amiga` directory:
-To enable the PiSCSI interface, uncomment the `setvar piscsi` line in default.cfg, or add it to the config file you're currently using.
+* (Optional) If you've made changes to bootrom.s, first run `./build.sh`.
+* (Optional) If you've had build.sh create a new `bootrom` file, you need to chop off the first few bytes of it, since VASM adds a single hunk to the beginning of it. Simply delete all bytes up until you bump into the value `0x90`, this is the first value in the boot ROM identifier.
+* Compile the new `pi-scsi.device` using `./build2.sh`.
+* (Optional) If you haven't previously compiled the `makerom` binary, or the code for it has been updated since last time, simply run `gcc makerom.c -o makerom`
+* Run `./makerom` to assemble the boot ROM file, it's automatically in the correct place for the emulator to find it.
-Add disk images to the PiSCSI interface by uncommenting the `piscsi0` and `piscsi1` lines and editing them to point at the disk image(s) you want to use. `piscsi0` through `piscsi6` are available for a total of seven mapped drives.
+# Some quick instructions for mounting a FAT32 disk image or disk using PiSCSI
-To get a hard drive image mounted when WB starts, you need a few things:
-* Copy pi-scsi.device from the `device_driver_amiga` folder to `SYS:Devs` on your Amiga.
- If you're super savvy, the driver is also available in "RAM" at the address `$80004400` because that's where the PiSCSI interface keeps the boot ROM, so you can technically just write it to a file on the Amiga from there.
* Download giggledisk from http://www.geit.de/eng_giggledisk.html or https://aminet.net/package/disk/misc/giggledisk to make MountLists for attached devices.
Place the giggledisk binary in `C:` or something so that it's available in the search path.
* It might be a good idea to have fat95 installed on your Amiga, in case you want to use FAT32 images or other file systems that fat95 can handle: https://aminet.net/package/disk/misc/fat95
If the MountList has several partitions listed in it, it must be split up into separate files for all partitions to be mounted.
-Once you've edited a MountList file, simply copy/move it to `SYS:Devs:DOSDrivers`, and the drive will be mounted automatically the next time you boot into Workbench.
+Once you've edited a MountList file, simply copy/move it to `SYS:Devs/DOSDrivers`, and the drive will be mounted automatically the next time you boot into Workbench.
If you don't want it to be mounted automatically, simply use the `Mount` command from CLI.
projects / pistorm / blobdiff