Updated README

Added image

BlueSCSI/README.md

@@ -0,0 +1,4 @@
+This is the patched firmware for the BlueSCSI.
+
+The only difference is a few pin assignments. A `git diff` is
+included so you can tweak your own firmware should you wish to.

BlueSCSI/git-diff.txt

@@ -0,0 +1,21 @@
+index 39738ceb..3340ff93 100644
+--- a/lib/BlueSCSI_platform_RP2040/BlueSCSI_platform_gpio.h
++++ b/lib/BlueSCSI_platform_RP2040/BlueSCSI_platform_gpio.h
+@@ -39,7 +39,7 @@
+ #define SCSI_OUT_MSG  20
+ #define SCSI_IN_BSY  20
+
+-#define SCSI_IN_RST  21
++#define SCSI_IN_RST  17
+ #define SCSI_OUT_RST  22  // No RST pin, manual or expander only
+
+ #define SCSI_IN_ACK  26
+@@ -85,7 +85,7 @@
+
+ // IO expander I2C
+ #define GPIO_I2C_SDA 16
+-#define GPIO_I2C_SCL 17
++#define GPIO_I2C_SCL 16
+
+ // Other pins
+ #define SWO_PIN 16

Patches/README.md

@@ -0,0 +1,2 @@
+These are the original patch sets used to patch the OS and the
+boot ROMs.

Patches/ka420/README.txt

@@ -0,0 +1,105 @@
+wjm 12-feb-1999: KA420-ROM-PATCH V1.0
+	These are some PATCHes to the boot ROMs of various 
+        KA420/KA430-based VAXen (Vs3100/xx, uVAX3100/10). 
+	Some of them have actually been tried out already ...
+
+
+Background:
+	Boot-ROMs for Vs3100 (and early uVAX3100 models) traditionally 
+	do not allow for SCSI system (boot) disks >1 GB, because they 
+	exclusively use 6-byte SCSI READ and WRITE commands. 
+
+	This patch to ROM code (always the same, only with some offsets
+	adapted to the different ROM & VMB versions) provides for 
+	10-byte SCSI commands in case the LBN to be accessed is .ge. 2^21 .
+	So it ought to allow booting and dumping from/to larger disks.
+
+	In order to make room for the new code, I sacrifice 
+	the very last portion of the debug code contained within 
+	the boot driver (i.e. the code that writes out a screen 
+	titled 'DKBTDRIVER halting ...' and then HALTs). 
+	That last portion would dump 6 words of the VAX stack; 
+	since that's where SP points in case of a HALT anyway, 
+	no information is actually lost.
+	And btw, I didn't see that screen displayed yet - I know it
+	from TVBTDRIVER & MKBTDRIVER, which halt this way when you try 
+	to boot from e.g. MUA0 or MKA100, and SCSI unit 1 is in fact 
+	a disk drive ...
+		
+
+Files:
+	KA42AROM13W.COM is for Vs3100/30 & /40 "KA42-A V1.3".
+
+	KA42AROM16W.COM is for Vs3100/30 & /40 "KA42-A V1.6".	
+
+	KA43AROM12W1.COM and KA43AROM12W2.COM, both applying
+	the same patches, are for Vs3100/76 "KA43-A V1.2".
+
+	KA41AROM14W1.COM and KA41AROM14W2.COM, also both having
+	the same effect, are for uVAX 3100/10 "KA41-A V1.4".
+
+	KA42BROM13W2.COM is for Vs3100/38 & /48 "KA42-B V1.3"
+	(this patch happens to be identical to KA41AROM14W2).
+
+	KA4ROM_READ.EXE reads the boot ROM from within VMS.
+	Needs PFNMAP privilege. Usage:
+		$ MCR dev:[dir]KA4ROM_READ outputfile
+
+	KA4ROM_CKSUM.EXE checks, and optionally 'fixes', the checksum(s)
+	in a disk copy of the boot ROM (in the format produced by KA4ROM_READ).
+
+	KA4ROM_SPLIT.EXE splits a disk copy into two files
+	that might be useful for actually 'burning' new ROMs.
+
+	[.TOOLS] has sources and .OBJ for the KA4ROM_* utilities.
+	Typically, there's no need to re-built the .EXE which I've
+	found to work on VMS V5.3 and higher.
+
+
+'Upgrade' procedure (No support, no warranty, no guarantees!):
+
+    (1) Find out boot ROM version (so far I *believe* this to be uniquely
+	specified by the 'short' id ala "KA42-A V1.3" which is displayed
+	at power-on, and by ">>> T 50" (?)). Note that there's also 
+	a longer id, which can be had from ">>> SHOW VER"; the latter
+	does *not* have the same "Vm.n" in it.
+
+    (2) Copy boot ROM to disk, using KA4ROM_READ.EXE . Best to stick to
+	the naming convention exemplified by the PATCH command files ...
+
+    (3) If the ROM version from (1) is one of the 'known' ones, apply
+	the corresponding 'patch command file' via
+		$ PATCH @KA%%%ROM%%W*
+	(Note that the command files provided 'know' the file names:
+	input is KA%%%ROM%%.BIN , output is KA%%%ROM%%W.BIN ).
+
+	If you have an 'unknown' ROM version, look at KA41AROM14W1.COM ,
+	and see if it can be adapted by fixing up the offsets in the lines
+	marked "???". (I did so for KA41AROM14 and KA43AROM12). Once you
+	have figured out the offsets to VMBVERS and DKBTDRIVER, you may
+	wish to plug them into one of the *W or *W2 files which then might
+	work also, as a sort of 'proof' that your DKBTDRIVER is in fact
+	identical to a know one ...). There are some text strings that
+	should be easy to locate in a full DUMP of the ROM contents ...
+
+	Sure I'd like to know what you find out in this step!
+
+	Do *not* proceed if fixing "???" lines doesn't work out completely!
+	You boot ROM may support booting from big SCSI disks already, or
+	have an 'unknown' (to me) boot driver ...
+
+    (4) Once the PATCH has been successfully applied, run KA4ROM_CKSUM
+	on the *output* file, and answer 'y' to the question posed ...
+	This will update the ROM checksums.
+
+    (5) Somehow 'burn a new boot ROM'. In the Vs3100s that I have looked at,
+	this is actually 2 chips, each 64k*16 bit. The one closer to the
+	'front' (i.e. memory connector side of the board) has the low 16 bits,
+	the other one ('rear', i.e. ethernet connector) has the high 16 bits 
+	of each 32-bit longword. Both 27C210[A] and 27C1024 chips have been
+	seen, even as a mixed pair, so apparently they're all the same ...
+
+    (6) Tell me about your experiences ...
+
+
+Wolfgang J. Moeller, GWDG, D-37077 Goettingen, F.R.Germany, <moeller@gwdg.de>

Patches/ka420/index.html

@@ -0,0 +1,9 @@
+<html>
+<head><title>Index of /pub/vms/ka420/</title></head>
+<body>
+<h1>Index of /pub/vms/ka420/</h1><hr><pre><a href="../">../</a>
+<a href="README.txt">README.txt</a>                                         12-Feb-1999 18:36                4477
+<a href="ka420-rom-patch_010.zip">ka420-rom-patch_010.zip</a>                            12-Feb-1999 18:37               41317
+<a href="scsi-developer-guide-ps.zip">scsi-developer-guide-ps.zip</a>                        27-Sep-1999 20:22              203800
+</pre><hr></body>
+</html>

Patches/pk2k/00readme.txt

@@ -0,0 +1,40 @@
+wjm 18-apr-1999: Almost finalized PK2K kits (Vs3100-like SCSI support
+		for VAXstation 2000 & microVAX 2000) for various flavors 
+		of OpenVMS VAX. Packaging to be improved at some later date.
+wjm 10-may-1999: All kits successfully tested (except for the STABACKIT part,
+		which I might well never use). Consider the files "frozen".
+wjm 06-jul-1999: Kits added for oVMS V7.2 (DIF & SRC identical to V7.1).
+
+   ... NOTE: PK2K is as "unsupported" as can be ... 
+   ... but highly likely to just work fine, for you as it does for me ...
+
+	PK2K_0013-BIN.ZIP	Binaries for VMS V5.5-2, plus the README
+				(slight update from the 0012 version).
+
+        PK2K_0013-BIN.README	(ASCII!) Usage notes for the V5.5-2 version.
+				Applies equally well to the following kits,
+				with the respective VMS version substituted
+				for "V5.5-2".
+
+	PK2K_0013-061BIN.ZIP	Binaries for oVMS V6.1
+
+	PK2K_0013-062BIN.ZIP	Binaries for oVMS V6.2
+
+	PK2K_0013-071BIN.ZIP	Binaries for oVMS V7.1
+
+	PK2K_0013-072BIN.ZIP	Binaries for oVMS V7.2 (NEW!)
+
+	PK2K-BOOT_0013.ZIP	"Secondary VMB" SYSBOOT images for booting into
+				a SCSI disk, to be loaded via DUAn: or ESA0:
+
+	KA410W_V23_ROM-0013.PATCH
+				(ASCII!) PATCH command file for improving
+				upon the "KA410-B V2.3" ROM, allowing it
+				to boot from SCSI disks, instead of "MUA0".
+				The bootstrap code within is identical 
+				to the one in PK2K-BOOT_0013.ZIP .
+
+   ... NOTE: PK2K is as "unsupported" as can be ... 
+   ... but highly likely to just work fine, for you as it does for me ...
+
+w.j.moeller, <moeller@gwdg.de>

Patches/pk2k/index.html

@@ -0,0 +1,21 @@
+<html>
+<head><title>Index of /pub/vms/pk2k/</title></head>
+<body>
+<h1>Index of /pub/vms/pk2k/</h1><hr><pre><a href="../">../</a>
+<a href="old/">old/</a>                                               11-Jul-2000 12:52                   -
+<a href="00readme.txt">00readme.txt</a>                                       06-Jul-1999 07:36                1546
+<a href="ka410w_v23_rom-0013.patch">ka410w_v23_rom-0013.patch</a>                          10-Apr-1999 00:54               25212
+<a href="pk2k-boot_0013.zip">pk2k-boot_0013.zip</a>                                 10-Apr-1999 00:51               94506
+<a href="pk2k_0013-061bin.zip">pk2k_0013-061bin.zip</a>                               10-Apr-1999 00:51               17324
+<a href="pk2k_0013-061dif.zip">pk2k_0013-061dif.zip</a>                               10-Apr-1999 00:53               14885
+<a href="pk2k_0013-062bin.zip">pk2k_0013-062bin.zip</a>                               10-Apr-1999 00:51               16803
+<a href="pk2k_0013-062dif.zip">pk2k_0013-062dif.zip</a>                               10-Apr-1999 00:53               14572
+<a href="pk2k_0013-071bin.zip">pk2k_0013-071bin.zip</a>                               18-Apr-1999 01:03               16966
+<a href="pk2k_0013-071dif.zip">pk2k_0013-071dif.zip</a>                               18-Apr-1999 01:03               14601
+<a href="pk2k_0013-072bin.zip">pk2k_0013-072bin.zip</a>                               06-Jul-1999 07:36               16943
+<a href="pk2k_0013-072dif.zip">pk2k_0013-072dif.zip</a>                               06-Jul-1999 07:36               14601
+<a href="pk2k_0013-bin.readme">pk2k_0013-bin.readme</a>                               10-May-1999 18:55                4767
+<a href="pk2k_0013-bin.zip">pk2k_0013-bin.zip</a>                                  10-Apr-1999 00:53               19186
+<a href="pk2k_0013-dif.zip">pk2k_0013-dif.zip</a>                                  10-Apr-1999 00:53               14736
+</pre><hr></body>
+</html>

Patches/pk2k/old/index.html

@@ -0,0 +1,12 @@
+<html>
+<head><title>Index of /pub/vms/pk2k/old/</title></head>
+<body>
+<h1>Index of /pub/vms/pk2k/old/</h1><hr><pre><a href="../">../</a>
+<a href="test/">test/</a>                                              10-May-1999 18:08                   -
+<a href="00readme.txt">00readme.txt</a>                                       19-Sep-1997 17:27                3715
+<a href="pk2k-boot_0010.zip">pk2k-boot_0010.zip</a>                                 22-Feb-1999 22:35               93009
+<a href="pk2k_0012-bin.zip">pk2k_0012-bin.zip</a>                                  19-Sep-1997 17:28               18644
+<a href="pk2k_0012-dif.zip">pk2k_0012-dif.zip</a>                                  19-Sep-1997 17:28               14283
+<a href="pk2k_0012-src.zip">pk2k_0012-src.zip</a>                                  19-Sep-1997 17:28              130462
+</pre><hr></body>
+</html>

Patches/pk2k/pk2k_0013-bin.readme

@@ -0,0 +1,132 @@
+wjm 02-apr-1999: PK2KDRVR & assorted patches to system programs, V1.3
+
+Changes over V1.2: Support non-zero SCSI host id (like Vs3100).
+
+	*** This is for VMS V5.5-2 only ***
+
+PK2KDRVR is a driver for the Vs2000/uVAX2000 SCSI port
+(traditionally known as the "tape controller port").
+
+	>>> EXPERIMENTAL software, NO WARRANTIES at all! <<<
+
+Apart from one `feature' and one restriction mentioned next, 
+it _ought_ to behave just like the Vs3100 SCSI driver (PKNDRIVER).
+
+SCSI host id determination:
+	The SCSI host adapter _by_default_ used the SCSI id 0
+	(not 6 or 7, as customary with other SCSI adapters), 
+	meaning you can't use a device on the bus with this id. 
+	This setting can be checked from the ">>> T 50" display, 
+	which under "TPC" shows a longword for each of the SCSI ids 
+	0..7 - the host id is indicated by a longword of FFFFFF03. 
+	Analogous to the ">>> SET SCSI[A]" commands found with other 
+	VAXen, the setting can be changed permanently (saved in NVRAM), 
+	in a somewhat non-intuitive way:
+
+	For a host id of ...	enter at the >>> prompt ...
+		7		D/U/P 200B00BC 1C
+		6		D/U/P 200B00BC 18
+		5		D/U/P 200B00BC 14
+		4		D/U/P 200B00BC 10
+		3		D/U/P 200B00BC 0C
+		2		D/U/P 200B00BC 08
+		1		D/U/P 200B00BC 04
+		0		D/U/P 200B00BC 00
+
+	Note: The `field sevice utility' ">>> T 73" (or better, 
+	      ">>> T 20000073"), aka. "tpmker", does not correctly 
+	      cope with a non-zero host id. This is a ROM bug. 
+	      T 73 likely has little use to anyone these days.
+
+Known restriction:
+	PK2KDRVR won't do data transfers of 16kB or more.
+
+	This has the effect of limiting the block size
+	that can be used with SCSI tapes, and also will
+	break any program that _attempts_ to read 16kB or more.
+	The only VMS program that does so (which I'm aware of)
+	is DUMP - see below for a patch.
+
+
+Disclaimer:
+	This is *EXPERIMENTAL* SOFTWARE that theoretically
+	*could* not only crash your system, but *could* cause
+	CORRUPTION on all media connected to the computer on 
+	which it's installed. (In fact, PK2KDRVR has plenty 
+	of code that *attempts* to crash the system if a chance 
+	for corruption gets noticed. I haven't observed any problem,
+	let alone a crash, with PK2K on VMS V5.5-2, since the release 
+        of V1.2 in late August 1997, in spite of trying pretty hard :-)
+	Fact is, the Vs2000/uVAX2000 hardware has never been 
+	"qualified" by anyone to work correctly with SCSI devices. 
+
+	>>> NO WARRANTIES at all! <<<
+
+
+Installation & use:
+
+	*** This is for VMS V5.5-2 only ***
+
+	The "binary kit" contains PK2KDRVR.EXE (not spelled PK2KDRIVER
+	for quite "technical" reasons) plus 5 patch command files.
+
+	Place PK2KDRVR.EXE in SYS$LOADABLE_IMAGES.
+
+	Use
+		$ PATCH @2KSYSGEN.COM
+	to create 2KSYSGEN.EXE in the current directory.
+
+	>>> Make sure that no MUA0 shows up, and that TVDRIVER
+	>>> (the Vs2000/uVAX2000 magtape driver) is _not_ loaded.
+
+	Use
+		$ MCR [dir]2KSYSGEN AUTOCONFIGURE ALL
+	to load PK2KDRVR (ought to show up as device PKA0)
+	and autoconfigure the SCSI devices, just like on a Vs3100.
+
+	If you're confident enough in the driver that you want
+	the machine to auto-configure the SCSI at boot time,
+	create two more programs (which _may_ only be required
+	if the machine is a cluster member),
+
+		2KSTACONFIG.EXE via $ PATCH @2KSTACONFIG.COM
+	plus	2KCONFIGURE.EXE via $ PATCH @2KCONFIGURE.COM
+
+	and copy
+		2KSYSGEN.EXE to SYS$SYSTEM:SYSGEN.EXE
+		2KSTACONFIG.EXE to SYS$SYSTEM:STACONFIG.EXE
+		2KCONFIGURE.EXE to SYS$SYSTEM:CONFIGURE.EXE
+
+	Each of these programs supposedly behaves just like
+	the VMS "original", when executed on a VAX other than
+	a Vs2000 or uVAX2000.
+
+
+	For completeness' sake, there are two more patch command
+	files that create PK2K-aware versions of STASYSGEN.EXE and
+	STANDCONF.EXE . Both of these are only used by stand-alone
+	BACKUP - in order to build a PK2K-aware kit, place the
+	patched programs into SYS$SYSTEM under the original name,
+	and modify SYS$UPDATE:STABACKIT-TABLE.DAT by replacing
+	"TVDRIVER.EXE" with "PK2KDRVR.EXE". You may also wish to
+	change STABACKIT.COM such that it accepts generic SCSI tape
+	(devtype 28) and on that occasion make it refer to a differently
+	named *-TABLE.DAT - I did find a non-DEC DAT drive from which
+	a Vs2000 did boot, with the tape configured as MKA100 
+	(">>> B MUA0" expects the tape to have a SCSI id of 1).
+
+
+	Lastly, there's 2KDUMP.COM which will create 2KDUMP.EXE
+	via	$ PATCH @2KDUMP.COM
+
+	Use the result instead of the original SYS$SYSTEM:DUMP.EXE
+	in order to DUMP blocks from a SCSI tape drive, e.g. via
+
+		$ DEFINE/USER DUMP dev:[dir]2KDUMP.EXE
+		$ DUMP MKAu00:
+
+	or similar. Contrary to standard DUMP, 2KDUMP will - independent of
+	hardware - read at most 16k-1 bytes per tape block (no big deal :-).
+
+
+Wolfgang J. Möller, Göttingen, F.R.Germany	<moeller@gwdg.de>

README.md

@@ -0,0 +1,130 @@
+VAXstation 2000 SCSI Patched ROMs
+=================================
+
+The VAXstation 2000 is a fantastic little "shoe box" VAX computer. A little
+slow maybe but a great entry to the wider world of DEC's VAX computers.
+However it is somewhat lacking in one area: storage. It has one (optional)
+internal hard drive (mine came with a 150MB RD54) and one (optional)
+external hard drive - both of the MFM variety. That's not a big amount of
+storage, and old MFM drives are as you probably know prone to stiction and
+bad blocks, if they even work at all. 
+
+The VAXstation 2000 does have a SCSI interface, however it was only intended
+to be used with the optional external TZK50 tape drive, and as such has never
+had any real support for adding hard drives, and it certainly cannot boot
+from a SCSI hard drive even if the operating system supported accessing one.
+
+But all is not lost. An experimental patch set for the VAXstation 2000 was
+created (but never officially released) to add full SCSI support to both the
+internal ROMs and to VAX/VMS, but only one specific version. Which is what
+we have here.
+
+Using the patches is not the easiest thing in the world, since you need
+an already working installation of VAX/VMS 5.5-2 (yes, that exact version)
+in order to run the patches. And if you don't have a working hard drive
+to operate the VAXstation on, how are you going to get a working installation?
+The answer is to net-boot it with a VAX cluster. But doing so makes it
+rather hard to then make a standalone image. But it can be done with a bit
+of shoehorning. Which thankfully we have done for you. In the releases
+section you will find a set of BlueSCSI hard drive images that should allow you
+to boot a VMS installation (dka200) that is ready to be completed with
+your own details, along with the installation source files (dka300) which
+the installation will ask you for.
+
+Using it
+--------
+
+In short:
+
+1. You need to upgrade your ROMs using the four ROM images (b1-b4) in the ROMs
+   directory. You will need four new 64kB EPROMs (27512, 27C512, etc) to burn the images to then
+   replace the ROMs on your VAXstation 2000's motherboard.
+
+2. Connect the BlueSCSI to the SCSI bus (important: see belo), making sure to enable termination if
+   you don't have the TZK50 tape drive attached or an external terminator.
+
+3. Boot from the dka2 device:
+
+```
+>>> boot dka2
+```
+
+4. Complete the installation following the on-screen prompts. When it asks for
+   the installation media tell it `dka300`.
+
+5. Install the patched binaries into the installed os:
+
+```
+$ mount/over=id dka300
+%MOUNT-I-MOUNTED, VMS552       mounted on _DKA300:
+$ set def dka300:[scsi.bin]
+$ @install
+```
+
+Now the long version:
+
+Installing the ROMs is pretty straight forward. There's 4 EPROM chips on the motherboard
+which need replacing.
+
+![ROMPlacement](https://github.com/user-attachments/assets/eb0417ef-58f3-4042-aaf1-6d31a02361bb)
+
+Note the order, as marked on these ROMs.
+
+The BlueSCSI (which should be a BlueSCSI II Desktop version so you get the proper 50 pin
+IDC connector) will not work with the VAXstation out of the box due to the VAXstation
+being from the dawn of SCSI and not working in quite the same way as other systems
+(the joys of old computers...) so the BlueSCSI will need to be modified in order to work.
+
+The problem here is that the SEL pin and RST pin of the SCSI are weakly tied together inside the
+BlueSCSI, so when the RST pin is asserted by the SCSI initiator the SEL pin gets pulled
+low, which shouldn't happen. Most things don't care - but the VAXstation does, and when that
+happens it just gives up trying to do anything on the SCSI bus ever again.  So we need
+to separate those two signals. This needs some careful SMD rework.
+
+1. Remove the resistor R66. This is the resistor that ties the two signals together.
+2. Connect the left hand pad (while the text of R66 is in the normal orientation)
+   of R66 to the pin GPIO17 of the Raspberry Pi Pico. This
+   gives the MCU direct control over the SEL pin.
+3. Install modified firmware into the Pi Pico which moves the SEL functionality to
+   GPIO 17.
+   
+<img width="466" height="211" alt="BlueSCSIPatch" src="https://github.com/user-attachments/assets/802cbc62-8243-49b3-af2c-86bdc8daa508" />
+
+This modification uses one of the pins that was used for I2C for the SEL pin, so you will
+no longer be able to use the I2C connector on the BlueSCSI.
+
+For the curious
+---------------
+
+If you're curious about the steps needed to create the patched VMS images, here's what
+we had to do:
+
+1. Create a VAX/VMS 5.5-2 cluster using a SIMH emulated server.
+2. Enrol the target VAXstation 2000 into the cluster as a member.
+3. Patch the system using the original patch set
+4. Verify that SCSI is working and create two blank images on the BlueSCSI (id 2 and 3).
+5. Create a standalone backup kit on DKA300
+6. Copy the VAX/VMS-5.5-2 installation backup files onto DKA300
+7. Copy the SCSI patches to DKA300
+8. Boot from DKA300 and install the VAX/VMS base system to DKA200
+9. Reboot from the network and manually copy the patched files to the
+   correct places on DKA200
+
+As you can see it's not a simple operation.
+
+One last word
+-------------
+
+Good luck!
+
+Postscript
+==========
+
+The patches do not calculate the checksum for the ROMs. This means you will get the VAXstation
+failiing at bootup with an error 5?? with `SYS 0000.0002`. Work is going on to rectify this, including
+reverse engineering of the checksum algorithm and the system test 5 to work out what is needed. Watch this space.
+
+## Update:
+
+The ROMs have now been updated with the correct checksums. It turns out the checksum is calculated per physical ROM,
+and is a simple rotate-left-and-add method. I wrote a [little program](https://github.com/MajenkoProjects/vaxcheck) to calculate the checksums for me.