
  VDOS for 32KW HP21xx using the USB disk adapter
  ===============================================

VDOS is a HP-IPL/OS-based system that provides programmable access
to the VDRIVE-based USB disk adapter. It is similar to VDOS for
machines with 64KW+ except for the binary load function, which uses
an embedded copy of UDOS to perform the load (overwriting the VDOS
system), UDOS remains in memory to provide a way to reload VDOS or
load another binary.


Loading VDOS32
--------------

The provided vdos32.abs binary is configured for TTY=11, PTR/USB=12,
PTP/USB=13 and BACI=20 (BACI is not required to run). So long as TTY is
in slot 11 then after loading the CONFIG command can be used to change
the other slot assignments. Normally HP-IPL/OS runs from location 2, if
TTY is not in slot 11 then put the TTY slot in the S register bits 0-5
then execute from location 70 (see HP-IPL/OS documentation for more info).
Once the system is configured, "FILENAME.ABS" VSAVE can be used to save
the configured system to disk. The vdos32.abs file would be copied to
"HPBOOT" on the flash drive to be the default system, or named with a
single-letter name for easy attaching using the USB adapter's controls.

Assuming the default configuration and named HPBOOT, to load...

Power on the HP then power on the USB disk adapter, select register S
and set to 001200, store, preset, ibl, preset, run - the system should
load, when done bits 0-5 should light up. Select register P, set to 2
(clear then set bit 1), run. The terminal should display...

VDOS 32K 1.65       
? 

Entering WORDS at the ? prompt should display...

DO +DO INDEx +LOOx >STEx IFNZ IFZ IF<0 ENDIx ELSE UNTIx WHILx CASE = < > <= 
>= <> DEFAxxx ENDCxxx EXECxxx WBOOx AND OR XOR ADD SUB INC DEC NOT 2CPL DUP 
DROP OVER ROT SWAP GET PUT PNUM CRLF DECIxxx OCTAx BINAxx RADIx SP>S SB>S 
XP>S XB>S YP>S YB>S ZP>S ZB>S END EOD DEFIxx DMPS S>SR SR>S PCHR PWRD CHRIx 
S>X X>S S>Y Y>S S>Z Z>S MUL ASL ASR ROL ROR DIV RUN X>>Y X>>Z Y>>X Z>>X 
$PRIxx $SWAx $CPY $DUP $DROx $LEN $ADR $XTExx $PUT $GET $CRExxx $STR $HEAx 
$APPxxx $TAIx $IN $CAT $VAL <>COx >PTP <PTR MSPAxxx MSBOxx MSBIx MSWOxx 
MSWIx MS$Oxx MS$Ix MSCRxx >MS <MS MS_Sxxx MS_Rxxxxxx CONSxxx #0 #1 @TL @TB1 
@TB2 @ANVxx @LLP @ENSxx @CLH @LITxxxx @STRxxx @RTSxx @DIC @USR @BLK @END 
@DIPxx RND TOKEx SDIC +IRQ -IRQ +AUTx -AUTx ADDCxxx INBLxxx OUTBxxxx GETIx 
SETIx GETOx SETOx $DEFxxx HEADxxx WORDx ADDHxxxxx ADDHxxxxxx FIXLxxxx 
ADDMxxxx VARIxxxx CONSxxxx ALLOxxxx ZEROxxxxx BPUT BGET $EQUxx $SLIxx $TRIx 
ABSOxx PTZExx MARKxxx SETCxx GLOBxx DUMP PDEF EXPLxxx FORGxx ERASx FETCx 
STASx HIDExxxx RENAxx DELExx UNDExxxx WHERxxx LOAD OE OE? SYSAxx CREAxx 
!BACx MSBAxx <BACx >BACx BACIxxx TTYCxx CONFxx !SDC CFGE DADD D2CPx DSWAx 
$DVAx $DSTx TTYPx TERMxxxx ESC POS CLS COLOx -COLxx MKLDx MKCLxx !NOLx 
VERSxxx VDOS VSYNx VCLExx <VDR >VDR &SIW &ORF &OWF &WFVxx @GSB @SSB &UCLxxx 
USBSxxx @PVLx PVDR $>VDx $>VCxx VECS VPROxxx VDIR VCD VSHOx VDEL USBRxxx 
USBAxxxxx USBWxxxx USBCxxxx LDUD UDOS VOWCxxxx VLOAx VSAVx VCOPx VREAx 
VWRIxx VCLOxx UFSIxx 
EOD=033736 FREE=024041 
? 

This build starts with the 8KW HP-IPL/OS 1.6 kernel and adds...
extra.ipl (select 32KW)
oct70.ipl (Octapus utility)
create.ipl (word assembler)
baci.ipl   (BACI driver)
config.ipl (configuration utility)
cfge.ipl   (code to permit configuring TTY/BACI using SR)
double2.ipl (double math code, non-extended version)
hpscreen.ipl (enter TERMINAL to switch it to normal ANSI)
mkldr.ipl  (utility for encoding binary to IPL code)
mkcldr.ipl (utility for encoding binary to CREATE code)
nolf.ipl   (prevents CRLF terminals from messing up entries)
version.ipl  (utility for changing signon string)
vdos.ipl   (core VDOS words)
vdext32.ipl  (new VDOS extra words for 32KW)

All of these are stock IPL files from the HP-IPL/OS "testing" archive
except for vdext32.ipl, which was written for this application.


About HP-IPL/OS
---------------

HP-IPL/OS is an Interpreted Programming Language and Operating System
for HP21xx minicomputers, originally specified by Bob Shannon and mostly
implemented by me starting in late 2001. We wanted a way to easily make
code for testing and playing with these machines. HP-IPL/OS starts with
a fairly simple 8KW stack-based kernel with a language somewhat resembling
FORTH (without the weird characters, some of the words work differently),
to which more words are defined from the existing words or created from
machine code to adapt a system for doing different things. Many of the
"IPL" packages that came about are for various kinds of operating systems
and utilities for running and manipulating other binary software, including
vintage apps like HPBASIC and running tools like EXTASMB, ALGOL and FORTRAN.
Using these tools several classic minicomputer games have been reimplemented
into stand-alone binaries. While not required to run the binaries, HP-IPL/OS
made it easier to run the tools used to create them and can serve as an
operating system for storing and running the programs from a disk system.

Typically at least 64KW is required for processing arbitrary binaries
since that permitted loading the binary into "alternate" memory leaving
main memory free to run utilities for manipulating the binary code, and
when the app was running HP-IPL/OS was swapped into alternate memory to
give the app most of main memory and permit the operating system to be
instantly swapped back to main memory - the swapper simply exchanged
main memory and alternate memory below 31KW and executed from location 2.

VDOS32 contains an embedded copy of UDOS32 to permit doing at least some
of the things that used to require 64KW using only 32KW.. it can be used
to access the USB disk adapter and its flash drive, launch applications
and make simple file-processing utilities (such as the append copy used
later in this doc to double a source code file to assemble using EXTASMB).
Making binary-patching utilities is difficult without a buffer that can
contain the entire unencoded binary, but theoretically it should be possible
to make utilities that for examples merge two or more ABS binaries into a
single binary and change/add specific locations within an ABS binary.
It's easier to run a DMS version of HP-IPL/OS under SIMH simulation to
prepare binaries, then run just the prepared application on real hardware.

Refer to summary.txt and other HP-IPL/OS documentation for more information
about how HP-IPL/OS works.


Using VDOS32
------------

Here are the comments from the vdos.ipl and vdext32.ipl packages...

; VDOS  11/17/10
; Words to control the VDRIVE2 USB drive module from HP-IPL/OS
;
; Core functions...
; slot VDOS - patches VDOS to specified interface slot
; VSYNC - syncronize so responses match last command given
; VECS - syncs, selects extended commands and ascii numbers
; VCLEAR - removes last response if immediately available
; VPROMPT - runs a shell to enter commands and print responses
; VDIR - lists current directory of the USB drive
; "DIRNAME" VCD - changes to a new directory
; "FILE.EXT" VSHOW - lists file contents to the terminal
; "FILE.EXT" VDEL - deletes a file in the current dir
; byte >VDR - sends a byte to the VDRIVE2
; <VDR - pushes a byte from the VDRIVE2 (bit 15 set if not valid)
; "string" $>VDR - sends a string to the VDRIVE2
; "command" $>VCMD - sends a string to the VDRIVE2 plus CR
; PVDR - prints VDRIVE2 response if immediately available
; &WFVDR - wait for response and push 1st byte received
;
; Streaming functions...
; "FILE.EXT" USBAPPEND - redirects MS output to a USB file (appends)
; "FILE.EXT" USBWRITE - redirects MS output to a USB file (overwrites)
; "FILE.EXT" USBREAD - redirects a USB file to MS input
; USBCLOSE - closes a USB streaming output file
; USBSTAT - pushes USB streaming error status (0=ok)

; extra words for VDOS... 5/2/12
; requires VDOS
; This version is for 32KW machines, no alt memory needed.
; The VLOAD word is modified to add a mini-OS at 77000 with an entry point

; that loads the specified file, after loading prompts for input/output
; files and optionally run address (if no vector at 2/3).
; To exit binaries jump to 77000 which runs the mini-OS to load
; another binary or the default boot system.
;
; LDUD - loads UDOS32 into high mem
; UDOS - runs UDOS32
; "file" VOWCHECK - prompts to overwrite if exists, pushes 0 if ok, 1 if not
;                   (filename string not removed from X, used by other words)
; "file" VLOAD - loads an IPL or ABS file, if runable ABS then runs it
; "file" VSAVE - saves current system to ABS file
; "source" "dest" VCOPY - copies a file to another file in the same directory
; "file" VREAD - like USBREAD but warm-boots if file not found or other error
; "file" VWRITE - like USBWRITE but confirms overwrite, warm-boots if error
; VCLOSE - like USBCLOSE but prints a message and starts with a "V"
; "file" UFSIZE - pushes the byte-size of a file, or 0 if not valid/too big

[ok it's new code... the opening comments aren't totally accurate.. ended up
 using UDOS32 for the mini-dos, loads at 76100 with a menu entry at 77000.]

With VDOS32 you can do...

VDIR to list a directory
"FILENAME.EXT" VDEL to delete a file
"FILENAME.EXT" "NEWNAME.EXT" VCOPY to copy a file to another file
 (in the same directory.. copying between directories is very tricky..
  easier to yank the flash drive and stick in a PC to do that)
"DIRNAME" VCD to change directory, ".." VCD to go back, "/" VCD for root
VPROMPT if other VDRIVE commands are needed
"BINARY.ABS" VLOAD to load and run a binary application (starts at 2)
"PACKAGE.IPL" VLOAD to load an IPL package into HP-IPL/OS
"BUILD.ABS" VSAVE to save the current HP-IPL/OS system to a binary
"BASICAPP.ABS" VWRITE "BASIC2.ABS" VLOAD to load the modified HPBASIC,
 enter in some BASIC code then use the BYE menu to punch it to an app.

You can use "FILENAME" VWRITE to attach an output file before running
a binary with VLOAD, but since VLOAD itself opens the read file it
can't be used to run a binary with an input file attached. Instead
do UDOS then use option 5 and specify the binary to load, after loading
use option 2 and specify the input file (and if needed option 7 for output),
then run from 2. If a different starting address then halt and manually run.

When done with the application, halt and run from 77000 to rerun UDOS and
use option 6 to reload VDOS32 (HPBOOT or whatever it's named).

This is somewhat more involved than the 64KW version where running 77000
returns directly to VDOS and binaries can be run with attachments by
loading to alt mem, attaching, then swapped to main to run... but at
least VDOS32 can directly run binaries without too much trouble.

Sometimes, especially when using the vintage assembler/compiler tools,
it's necessary to append a file to another file. This can be done by
entering this simple word...

DEFINE CPAPPEND  ;USAGE: "SOURCE" "DEST" CPAPPEND
USBAPPEND USBREAD USBSTAT IFZ
DO MSBIN MSBOUT USBSTAT UNTIL
ENDIF USBCLOSE END

All that does is attach the top (2nd) string to a write file using
USBAPPEND to not delete it first, attach the next string (1st) to
the source file using USBREAD, do USBSTAT and if 0 run a loop that
reads a byte from input, writes it do output and loops until USBSTAT
returns non-zero (hopefully EOF). USBCLOSE closes out the write file.

Enter something like "VDOS32X.ABS" VSAVE to save the build with
the added CPAPPEND word.

To use it to assemble a file using the vintage 2-pass EXTASMB, do...

"SOURCE.ASM" "TEMP.ASM" VCOPY
"SOURCE.ASM" "TEMP.ASM" CPAPPEND
UDOS

Using UDOS, load SIO.ABS, load EXTASMB.ABS, attach read from TEMP.ASM,
attach write to TEMP.ABS (or TEMP.REL if a module), halt, select P and
set to 000100, store, preset, run. At halt press run again, should list
the assembled source while outputing the binary. At next halt bits 0-5
should be lit for success, select P and set to 077000, store, run.
Load and run VDOS32X.ABS (or whatever it's named) to return to VDOS.

This procedure is a bit more involved than with the 64KW version, but
at least it's workable. Similar (but very specific) procedures can be
used to operate the ALGOL and FORTRAN compilers and the BCS linker.
Use CPAPPEND to append together all the files required by a tool to
make up for the inability to change files while an app is running.
The 64KW version of VDOS with the vintage package also has to do that,
but with the extra memory the tools can be loaded into alternate memory
first so files can be attached before running, so the copy/append/attach
steps can be automated. While not impossible with 32KW, with a limit of
less than 1KW code (typically I set up BCS for 31KW) it would be somewhat
difficult to make it "just do it".


Updating the embedded UDOS
--------------------------

The embedded copy of UDOS32 is contained in the UDMAIN word in the
vdext32.ipl file. If necessary to update the code, do the following...
(this assumes running on real hardware and the new udos32.abs has been made)
(this procedure has not been tested, I usually use SIMH to build, see below)

Make a word that clears the PTR/USB output lines to force
reading using papertape mode...

CREATE CLRUSB
 CLA
 OTA 12
END

...change the 12 to the actual slot of the PTR/USB interface card.

Attach the read file to the new binary: "UDOS32.ABS" VREAD
Attach the write file to a temp text file: "TEMP.TXT" VWRITE
Enter CLRUSB to force the interface to papertape mode.

Use the HP's IPL loader to load in the new UDOS32...
Select S, set to 001200 (or PTR/USB slot), store, preset, ibl, preset
Should halt with bits 0-5 lit up. Select P, clear display, set bit 1, run

Now write the encoded binary: fromaddress toaddress MKLDR
replace fromaddress to the first address to save and set toaddress to the
last address to save (usually I pad it a bit). For example 76100 77437 MKLDR
for the current version.

When writes complete enter VCLOSE to make sure all data is written,
wait a few seconds then remove the thumbdrive. Use a PC text editor to
copy/paste the encoded lines overwriting the encoded lines in vdext32.ipl,
make sure the number above the first encoded line is the starting address.
Save the new version as say "vdext32b.ipl" to preserve the original version.
if using Linux make sure the file is put back to "dos" format (use flip etc).

Reinsert the thumbdrive into the USB disk adapter, reset the adapter,
then from the still-running VDOS, enter: "VDEXT32B.IPL" VREAD
Remove the existing VDOS extra words: FORGET LDUD
(this erases CLRUSB entered before but no longer needed, it's just
 a trick for forcing papertape mode before using the stock IBL)
Load in the new package: LOAD
Save to a new build "VDOS32B.ABS" VSAVE
(change the filenames as needed)

I haven't tested this exact procedure on real hardware, rather I usually
do builds under SIMH. Don't need the CLRUSB hack in simulation because there
is no disk interface to have to trick, and PTR(read)/PTP(write) attachments
are made using sim prompt attach commands instead of V-commands.

----------------------------------------------------------------------------
Docs last modified May 3, 2012
Terry Newton (wtn90125@yahoo.com)

