HP-IPL/OS 1.64 builds with VDOS
===============================

Two VDOS builds are provided, VDOS.ABS is based on hposdms.abs with
altutil.ipl, vdos.ipl and vdosext.ipl added. VDOSC.ABS is a more
compact build without the TBG and other unneeded words. These builds
require a HP21MX machine such as a HP2113 with at least 64KW memory.

File VDOS.ABS, build date 6/14/11...

HP-IPL/OS VDOS 1.64 
? WORDS
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 
PRESxx DEBUx VERSxxx +TBG -TBG >TBG TBGZxxx >WDT +WDT -WDT !100xx T>>S 
TIMExxx PTIMx !WDA !BACx MSBAxx <BACx >BACx BACIxxx TTYCxx CBUS ?BUS >BUS 
<BUS *BUS +REN -REN +ATN -ATN !HPIx CLRBxx LISTxx TALK $>BUx $<BUx .BUS 
CONFxx !SDC CFGE !DMS -DMS SDMA UDMA UJUMx SJUMx SPAGx C>ACxxx A>CCxxx 
USPAxx DMSTxxxx UPTR MSUSxx ABSLxxx GOUSxx GOSYxxxx ALTSxxx ?DMS MKWOxx 
ENDWxxx DADD D2CPx EMUL EDIV DSWAx $DVAx $DSTx DASL DASR DLSL DLSR DROL 
DROR FIX FLT FP+ FP- FP* FP/ DFLT DFIX PWR1x $>FP FP>$ FSGN FSQR TTYPx 
TERMxxxx ESC POS CLS COLOx -COLxx ZAM HLT ALTRxx RUNAxx PTHExxxx AAOUx 
ALTAxx ALTDxxx CLRHxxx ALTHxxx 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 VOWCxxxx VLOAx VSAVx 
VCOPx VREAx VWRIxx VCLOxx UFSIxx 
EOD=040264 FREE=017513 

Package list...
Start with hposdms.abs (version 1.64 6/13/11)
altutil.ipl
vdos.ipl
vdosext.ipl

Default allocation is 4 blocks, enter 2 ALLOCATE for more IPL memory.
Configuration is TBG=10, TTY=11, PTR/USB=12, PTP=13, HPIB=17, BACI=22,
use CONFIG to change. Supports reconfig on startup... put TTY slot in
switch bits 0-5, BACI slot in bits 6-11 (or leave off), set bit 12 to
default to BACI console or (if not using BACI) set bit 15 to disable
autostarting. Run from location 70 to reconfigure and start HP-IPL/OS.
If the USB adapter slot is not 12 then do slot# VDOS before using.

File VDOSC.ABS, build date 6/14/11...

? WORDS
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 CREAxx PRESxx DADD D2CPx 
EMUL EDIV DSWAx $DVAx $DSTx !DMS -DMS SDMA UDMA UJUMx SJUMx SPAGx C>ACxxx 
A>CCxxx USPAxx DMSTxxxx UPTR MSUSxx ABSLxxx GOUSxx GOSYxxxx ALTSxxx ?DMS 
ZAM HLT ALTRxx RUNAxx PTHExxxx AAOUx ALTAxx ALTDxxx CLRHxxx ALTHxxx OE OE? 
SYSAxx 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 VOWCxxxx VLOAx VSAVx VCOPx VREAx VWRIxx VCLOxx 
UFSIxx VERSxxx 
EOD=033024 FREE=024753 

Package list...
Start with hpiplos1.abs (version 1.6 6/9/10)
extra.ipl (select 32KW)
create.ipl
double.ipl
dms.ipl
altutil.ipl
oct70.ipl
vdos.ipl
vdosext.ipl
version.ipl

Default allocation is 4 blocks, enter 2 ALLOCATE for more IPL memory.
Configuration is TTY=11, PTR/USB=12, PTP=13. There is no config utility,
to change the slot assignments put the TTY slot in location 355, the
PTR slot in location 357, the PTP slot in location 356, then run from 2.


Using VDOS
----------

See the vdos.ipl and vdosext.ipl files for docs of all the words provided.
The main usages are...

slot VDOS - change the USB adapter slot (as in 12 VDOS)
VDIR - list the disk directory
VPROMPT - run a VDRIVE dos prompt
"FILENAME" VDEL - delete a file
"FILENAME" VSHOW - list file contents to the console
"FILENAME" VSAVE - save the current system to a binary
"FILENAME" VLOAD - load a binary or an IPL file
"DIRNAME" VCD - change to a subdirectory (".." and "/" for navigating up)
"FILENAME" "NEWNAME" VCOPY - make a copy a file in the same subdirectory
 (use to rename files or set the HPBOOT file)
USBSTAT PNUM - prints disk error status

These print status info and warmboot if error...
"FILENAME" VREAD - opens a file for reading
"FILENAME" VWRITE - opens a file for writing, prompts to delete if exists
VCLOSE - closes a write file

These do not print prompts or status...
"FILENAME" USBREAD - opens a file for reading
"FILENAME" USBWRITE - opens a file for writing, deletes if it exists
"FILENAME" USBAPPEND - opens a file for writing, appends new data
USBCLOSE - closes a write file

Any MS-capable word(s) can be used to read bytes from an open read file
and/or write bytes to an open write file. These include...

MSBIN - read a byte and push to the stack
MSBOUT - pop the stack and write the byte
MSWIN - read a word (2 bytes) and push to the stack
MSWOUT - pop the stack and write the word
MS$IN - read a line up to CRLF and push to the string stack
 (CRLF required or stack overflow, CRLF not added to the string)
MS$OUT - pop the string stack and write
MSCRLF - write CRLF
LOAD - redirect read into the console
SYSALL - save the current system
ABSLOAD - load ABS binary into alternate memory
 (ALTSAVE ZAM to clear alt, run 77000 to swap and run)
 
From altutil.ipl (included in VDOS builds)...
RUNABS - load and run an ABS binary (run from 77000 to exit)
PTHEADER - writes 8 zero bytes for ABS leader/trailer
from to AAOUT - writes alt mem range in ABS format
ALTABS - menu-driven alt mem saver

From fcam.ipl...
AM2ABS - scans alt mem and saves non-zero ranges in ABS format

From fedutil.ipl (utilities for fed.ipl, an "array" text editor)...
MASAVE - saves edited text (adds ~TERMINATE~ for MALOAD)
MALOAD - loads text to edit (requires ~TERMINATE~ else halt, run from 2)

>MS can be used to redirect console prints to an open write file...
almost anything that prints can print to a file instead. Use CONSOLE
to reset redirection back to the console and stock papertape drivers.
For example to save a word definition to an IPL file...

"WORDNAME.IPL" VWRITE >MS
EXPLAIN WORDNAME
"CONSOLE" $PRINT CRLF
CONSOLE VCLOSE

Multiple EXPLAIN commands can be used to add multiple words to the file,
which can be reloaded into the dictionary like any other IPL file. This
is useful for rearranging the dictionary. There are limitations to the
technique - only high level words made using DEFINE can be saved, and
if variables or constants are involved they need to be printed to the
file where they need to appear.


Using HP-IPL/OS
---------------

HP-IPL/OS is a (relatively) new operating system for HP21xx minicomputers
with an emphasis on hacking the machine - unlike other operating systems
there is very little protection besides basic error handling. If you tell it
to overwrite an area of memory it does it, no questions asked. Type carefully
when using the PUT word, it is all-powerful. Higher-level operations and apps
attempt to protect data from errors but don't count on it... GIGO. The main
reason HP-IPL/OS was written was because there isn't much in the way of
HP21xx software that can run on just a CPU and a console (at the time it
was written, the only software we had that could simply be run was HPBASIC
and Octapus, we wanted a full blown dev system). Another reason for writing
HP-IPL/OS was to simplify the creation of drivers to attach homemade gizmos.
Such as the USB disk adapter. The CREATE assembler converts machine code
into low-level words that (like all added words) become part of the language.
Built-in labels permit popping and pushing parameters from and to the stack
using code like JSB ZSPOP,I and JSB ZSPSH,I and other things like reading
and writing from and to the console and MS streams. See create.ipl for info.

The price of simplicity is HP-IPL/OS is an absolute-memory system - machine
code cannot cross a 1KW boundary without code help or CREATE displays an
error message and halts the load. When building systems the user has to
load things in an order that avoids page errors - usually I just do WORDS
to check the current dictionary before loading something with a bunch of
CREATE code - if EOD is just past a 1KW mark (34000 36000 etc) then it'll
go but if near the end (say 35400) then there might be trouble depending
on the package, load some needed non-CREATE code first to push it past
the 1KW mark, or in a pinch use VARIABLE to define a big enough dummy array.
Some packages like fed.ipl do this automatically. It's not a big deal,
if something won't load just enter ERASE and confirm then try a different
order, generally it only takes a couple tries to load the needed packages.

Various packages require that other packages be loaded first, usually this
is noted in the IPL comments but not always. If a needed word isn't present
the system prints the first 4 characters of the needed word and stops the
load, ERASE, load the required package and try again.

Once a package is loaded, it becomes part of the system until removed.
If something is needed temporarily then remove the package afterwards
using ERASE, or if only some words in a package need to remain then use
FORGET WORDNAME to remove that word and everything after it (truncates
the dictionary of words). After loading in the desired packages, the
complete system (called a "build") can be saved to a binary for reuse
without having to build it again (for VDOS, use "FILENAME" VSAVE).
There is only so much room in the dictionary (it's just a 32KW machine
and some of that is used for the OS and high-memory machine code).
If there is no room left the system prints an error message and stops
loading. Sometimes more room can be made using ALLOCATE, the default
for 32KW is 4 1KW data blocks but most packages require only 2 blocks
so 2 ALLOCATE for more memory. The LIFE demo requires 3 blocks to run.

HP-IPL/OS is a stack-based system that resembles FORTH but isn't.
There are 5 stacks, a system stack for passing 16-bit numbers between
words, an internal return stack so the system can keep track of where
it's at, a string stack (X), and two auxillary stacks (Y and Z) for
juggling strings/numbers and saving temporary data without messing
up the system stack order. In addition to the stacks, programs can
also reserve direct-access memory using VARIABLE, or directly read
and write memory anywhere it is safe (memory from 100 to 137 octal
is reserved for user programs).

Examples...

? 7 1 ADD PNUM
000010
? DECIMAL 7 1 ADD PNUM OCTAL
8
(it's recommended that OCTAL be used ASAP after using DECIMAL)
(at least don't forget to OCTAL before specifying memory addresses)
? ;calculate (3+4) * (5-7)^2
? DECIMAL 3 4 ADD 5 7 SUB DUP MUL MUL PNUM OCTAL
28
? DEFINE H
> "HELLO " $PRINT END
? DEFINE W
> "WORLD " $PRINT END
? DEFINE HW
> H W END
? HW
HELLO WORLD
?

See summary.txt for a summary of the words in some of the packages that come
with the full HP-IPL/OS archive - only the major packages that would be useful
for a VDOS build are included here. Many of the packages are already present
in the supplied builds, but if needed HP-IPL/OS can be taken down to the
kernel and rebuilt with a different configuration.

-----------------------------------------------------------
Last mod 6/14/11
