UDOS - a tiny VDRIVE2 operating system for the 8KW HP2114
=========================================================

UDOS is a small program (<0.5KW) that works with a VDRIVE2 USB disk module
and an appropriate interface to permit saving and loading ABS-format binary
files. It can also be used to save binaries to a papertape-punch emulator.
Loading is accomplished by attaching the file to the interface so that it
can be loaded using the existing Binary Boot-Loader (BBL) program that usually
lives in the top 64 words of the machine. A previous implementation (VDOS) was
for a HP21MX-class machine with 64KW+ memory and worked much like a "real" dos,
in that binary files could be loaded and run from the prompt without touching
the machine, then exited to restore the operating system which was saved to
"alternate memory" while the binary was running. This implementation is much
more hands-on and presently requires that the user press buttons on the machine
and the VDRIVE interface to run the bootloader and then run the application,
and return to the operating system. With the appropriate firmware and
bootloader mods I'm sure this can be smoothed out but that's a task for
someone who actually owns a HP2114. Thus consider this material only a
possible starting point, it should be usable as-is but can be refined.

Files...

udos_b2.asm - assembly code for UDOS for 8KW HPBASIC
udos_b2.abs - ABS binary to overlay over basic1.abs
udos_b2.lst - listing for udos_b2.abs
udos_c2.asm - assembly code for stand-alone UDOS
udos_c2.abs - ABS binary for stand-alone UDOS
udos_c2.lst - listing for udos_c2.abs
hpusb2.asm - 8052 assembly source for modified interface firmware
autoptr.asm - 8052 assembly source for firmware that sends HPBOOT file
HPUSB2.hex - 8052 object code for hpusb2.asm
HPUSB2NI.hex - 8052 object code for hpusb2.asm with IDE init disabled
AUTOPTR.hex - 8052 object code for autoptr.asm
UDOSMAZE.ABS - HP-IPL/OS with UDOS and the maze game
UDOSUTIL.ABS - HP-IPL/OS with UDOS, the hhooks code and Octapus
dcon.ipl - IPL source for a UDOS slot configurator word
hpiplos1.abs - raw HP-IPL/OS 1.6 kernel (for rebuilding from scratch)
kernel.txt - summary docs for the kernel (read IPL files for other docs)
internal.ipl - IPL source for some kernel words, load to remove blocks
8Kextra2.ipl - IPL source for 8KW "extra" words
maze_sm.ipl - IPL source for a smaller version of the MAZE game
oct14a.ipl - IPL source for the Octapus utility
hhooks.asm - assembly code for using UDOS from HP-IPL/OS
hhooks.abs - ABS binary to overlay into HP-IPL/OS with UDOS
hhooks.lst - listing for hhooks.abs
hhooks.ipl - IPL code that interfaces with the hhooks machine code
*8K.abs - HP binaries with games based on 8KW HPBASIC/UDOS
8Kgames.txt - info about the games and using HPBASIC/UDOS

There is no guarantee that any of this will work for you. I just made some
changes to the UDOS driver code to fix a potential glitch... theoretically
it's OK now but mistakes can happen.. if problems are encountered let me
know or check back to see if something has been updated. For that matter
feel free to let me know if it does work... us HP mini hackers are a
fairly small group and it's nice to know who's doing what. If you ended
up with this stuff and don't own an HP21xx minicomputer, you can see
some of what this is about using the SimH HP2100 simulator... for the
games run hp2100, enter load [filename].abs then enter run 2.


Web links...

http://newton.freehostia.com/hp/index.html
http://newton.freehostia.com/hp/ideusb.html
http://newton.freehostia.com/hp/usbadapter.html
http://www.ftdichip.com/Products/Modules/ApplicationModules.htm
http://www.ftdichip.com/Firmware/Precompiled.htm
http://www.pjrc.com/tech/8051/board5/
http://www.infionline.net/~wtnewton/oldcomp/hp2100/
http://newton.freehostia.com/hpiplos_main_testing.zip
http://oscar.taurus.com/~jeff/2100/index.html
http://simh.trailing-edge.com/
http://www.cs.ubc.ca/~hilpert/e/HP21xx/index.html
http://www.hpmuseum.net/
http://www.bitsavers.org/
http://www.brouhaha.com/~eric/software/asm21/


About the VDRIVE interface and firmware commands
------------------------------------------------

The 8052 version of the interface is implemented using a "Paul" Rev5
development board with a few added chips and level-shifters to interface
with a 12V ground-true interface board, the interface is intended for use
with an IDE disk but adding the VDRIVE2 module requires little modification.
The HPUSB2[NI].hex and AUTOPTR.hex files contain new firmware for this
application to provide the ability to emulate a PTR reader so that an
existing bootloader can load a binary without having to know anything
about the disk, the HPUSB2NI.hex version has the IDE disk portion disabled
(the HPUSB2.hex version will lock up if an IDE disk is not attached).
The present implementation automatically sends an "HPBOOT" file to the
HP if it exists on the USB disk, and if powered up with the PF.2 line low.
After sending the boot file the interface has to be reset to exit PTR mode
and accept disk commands. The boot file send can be re-engaged by resetting
with PF.2 high then resetting again with PF.2 low. This is a bit inconvenient
but on my main system this function was only used to initially boot the
system. Note - if duplicating the 8052-based hardware using level shifters
then there needs to be about 75 ohms from the +5V line to ground to ensure
that when the interface is off leakage from the level shifters doesn't
keep the VDRIVE2 module from resetting properly when the power is cycled.

The original 8052-based design was convenient to use for VDRIVE experiments
since it already existed as an IDE interface, all the code for transferring
date to and from the HP minicomputer was already in place. All I had to do
was write new code for sending and receiving SPI data and subroutines for
talking to the VDRIVE and implementing the streaming buffer system. I already
was familiar with 8052 programming and the dev board is programmed using
a serial port - all I needed to implement was a $25 VDRIVE2 module.

Since then, a new PIC-based USB disk adapter has been contructed that works
better with UDOS and small-memory machines that have no need (or memory for
code to program) an IDE disk. The new adapter mostly transparently switches
between papertape emulation and disk modes without requiring a reset, supports
papertape punch (theoretically, hardware and code is there but as of 11/19/10
hasn't been tested with actual vintage software... need to make a cable), and
since there isn't any IDE disk code to sidestep, can reattach the HPBOOT file
by simply pressing the reset switch, no power cycling or switch combinations
needed. The new adapter has an LCD and switches for setting up and attaching
single-letter read and write files, making it possible to use purely as a
papertape emulator without requiring HP-side dos software.

The following VDRIVE-related commands are understood by both versions of
the interface...

120000 = 1010000000000000   read from VDRIVE, follow by read transfer
121bbb = 10100010bbbbbbbb   write to VDRIVE, byte in low 8 bits of command
122000 = 1010010000000000   sync VDRIVE (call before starting operations)
123000 = 1010011000000000   clear VDRIVE
130000 = 1011000000000000   open read file, follow by filename[cr]
131000 = 1011001000000000   read from file, follow by read transfer
132000 = 1011010000000000   read using paper-tape emulator mode
134000 = 1011100000000000   open write file, follow by filename[cr]
135bbb = 10111010bbbbbbbb   write to file, byte in low 8 bits of command
136000 = 1011110000000000   close write file (write remaining buffered bytes)
137000 = 1011111000000000   get usb_error value, follow by read transfer

Notes...

All commands consist of a single command/flag cycle, except for the open
commands. Commands that request data should read the data using LIA when
the firmware toggles the flag line.

Command 120000 (read from VDRIVE) sends a request to read a byte directly
from the VDRIVE2, follow by a read from the interface channel which returns
the byte. If bit 15 is set then the VDRIVE is busy, or there is no more data
to send back, the low byte should be clear. For some commands the HP-side
software should delay a bit and check again before deciding there is no
more data. Most commands have specific documented responses so if sending
specific commands the software can wait for the proper response.

Command 121bbb (write to VDRIVE) is used to transfer bytes directly to the
VDRIVE for sending commands. Refer to the Vinculum Firmware User Manual.
Commands sent to the VDRIVE must end with a single CR char (not CRLF).
The UDOS dos prompt option sends user-entered data to the VDRIVE and when
enter is detected, uses the read from VDRIVE command (with a delay) to print
back the response.

Commands 122000 and 123000 are used to syncronize with the VDRIVE, and
remove responses from the buffer when it doesn't matter. Issue the sync
command before starting a specific command sequence to make sure the VDRIVE
isn't in the middle of something else. The clear command can be used after
sending a command to discard the response (faster than sync) before sending
additional commands.

Commands 130000 thru 137000 implement a simple streaming file access system
that permits reading and writing unstructured files. This is necessary as the
VDRIVE requires that the size of (almost) all transfers be specified (except
for the RD command to read all of a file), and can only open a single file at
a time. The streaming commands permit having read and write files open at the
same time, and permit bytes to be read or written without regard to file size.
The interface firmware maintains separate read and write buffers, when the read
buffer is empty the firmware transparently fills the buffer with more bytes
from the file, and when the write buffer is full the bytes are appended to
the file then the buffer cleared to accept more bytes. HP-side software
doesn't see this, and so long as streaming read/write commands are not used,
raw VDRIVE commands can be used to perform more sophisticated file processing
(updating internal areas etc) without interfering with open stream files.
The buffers can be any convenient size, the present 8052 code uses fairly
large (>2KB) buffers for speed, but even 256 byte or smaller buffers will work.

Command 130000 opens a file for reading, follow by sending the filename plus
a CR char directly to the interface channel (not to the VDRIVE itself). Sending
just a CR with no name closes a previously open read file. Filenames must be
in 8.3 format, extra characters past the 12th byte are discarded. Unsupported
characters (such as escape) result in no file being opened and set the internal
error number (returned by command 137000). When a file is opened the file
pointer is set to the first byte of the file.

Command 131000 requests the next byte from an open read file, follow by a read
from the interface channel which returns the byte in the lower 8 bits. If a
read file isn't open or is past EOF then a 0 byte is returned. High bits should
always be returned clear. If needed EOF can be detected using command 137000.

Command 132000 is new, sends whatever bytes are remaining in an open read
file. In the present "hack" implementation the only ways to return to command
mode is to read all bytes of the file, or reset the IDE/USB interface...
theoretically before placing the data on the bus and setting the flag, the
firmware could check for another command (say 133000) to cancel papertape mode
but for now I have to press the reset button the 8052-based interface.

Command 134000 opens a file for writing, follow by sending the filename plus
a CR char directly to the interface channel. Any previously open write file
will be abandoned without writing any remaining buffered bytes. Sending just
a CR with no name will result in no open write file. Sending invalid chars
will result in no open write file and set the internal error number.
If the file exists then the file pointer is set to the end of the file,
in other words command 134000 always appends to an existing file. To replace
a file the existing file must be deleted using the DLF FILENAME.EXT command.

Command 135bbb writes a byte to an open write file, the byte to write is
in the lower 8 bits. If a write file is not open the byte is discarded and
the internal error number is set. The error number can also be set if some
other error occurs, such as the drive removed, out of space, etc.

Command 136000 closes an open write file and writes any remaining buffered
bytes to the file. Always use the close command when done writing or the
file will not be complete. If an undetermined amount of time will pass the
file can be closed then reopened to continue appending bytes.

Command 137000 requests the internal error number, follow by a read from
the interface channel. The following error numbers are returned by the
8052 firmware...

0      no error
1      no disk
2      command failed (not found or a dir specified for a filename)
3      invalid filename
4      file already open
5      disk full
6      streaming input buffer not open
7      streaming output buffer not open
8      past end of input file
255    some other error occured

These are suggested for new interface designs but are not written in
stone - HP-side software should only count on 0 being no error and not 0
meaning some error occured, different designs may implement differently.
In the present design, 255 means an error occured but not wasting code
to try to figure out what the error was, usually because the firmware
sent a command to the VDRIVE but didn't understand the response.

Note that the error numbers are only set by the high-level streaming
system, low-level VDRIVE commands do not set the error number.

Also note that because the commands either contain 0 or a byte in the
lower 8 bits, it is possible to use the same HP-side software to write
to a papertape-punch (PTP) file without a VDRIVE interface. To detect
if a VDRIVE interface is present, send a close command (136000), send a
write 0 byte command (135000), send a read error command (137000) and read
from the interface channel - if a 0 is returned then a VDRIVE interface is
not present and 4 zero bytes were written to PTP, usually not an issue
with binaries since they almost always require a leader anyway.


About UDOS
----------

UDOS is an extremely simple dos for the USB adapter, the menu has options
to save all of memory to an ABS binary, attach a file for reading, run a
VDRIVE prompt for file management, and exit by running from location 2...

1) SAVE BINARY
2) ATTACH FILE
3) DOS PROMPT
4) RUN FROM 2
> 

Option 1 prompts for a filename then writes the entire 8KW memory from
2 to 17677 to the file in absolute binary (ABS) format.

Note - if the file exists, the new binary is appended to the end rather
than replacing the file. To replace an existing file use the DOS PROMPT
option then use DLF [filename] to erase the file first.

UDOS doesn't have a binary load, rather it opens the file for read and uses
the firmware's "read as PTR" command so the HP's stock papertape loader can
load the selected binary file. The attach option can also be used to attach
IPL or data files to load into HP-IPL/OS (or other applications).

Option 3 runs a raw VDRIVE dos shell. Useful commands include...

DIR - list a disk directory
DIR FILENAME - list information about a specific file
DLF FILENAME - delete a file
REN OLDNAME NEWNAME - rename a file (be careful, a PC will see the old name)
RD FILENAME - list the contents of a file to the console (garbage if not text)
CD DIRNAME - change to another directory (CD .. for up, CD / for root)
MKD DIRNAME - create a new directory
DLD DIRNAME - delete an empty directory
FWV - print firmware version (at least 3.65 or 3.66 needed, current is 3.68)

Refer to the Vinculum Firmware User Manual for more information. The VDRIVE
supports many more commands but be careful as some cannot be used from an
ASCII-based terminal and some commands can directly manipulate files and
raw disk sectors. Use the FWV command before getting too far, if < 3.65
then the firmare in the VDRIVE2 module should be upgraded to avoid issues.

Option 4 simply jumps to location 2 to rerun the host binary. With HP-IPL/OS
this restarts HP-IPL/OS, with HPBASIC (and the UDOS mod) this starts the
embedded BASIC program running.

Some notes regarding using the modified 8052 firmware...

Once the file is attached do not use further dos commands until
the interface is reset to return to command mode, otherwise a lockup
or endless loop may result. After attaching immediately halt and run
the bootloader, or exit to load whatever was attached. Reset the
VDRIVE interface to exit PTR emulator mode.

After running a binary that doesn't contain UDOS, the interface has
to be kicked back into boot mode to reload the fixed-filename boot system.
With the current interface this is done by power-cycling, or by doing
a double reset with the PF.2 line high then low.

The PIC-based interface firmware is better-behaved about mixing dos and
papertape commands, usually it doesn't care. Reset the interface to
reattach the HPBOOT file.


There are two versions of UDOS - The udos_c2.abs binary is a stand-alone
version that loads at 17000 octal and can be added to HP-IPL/OS or about
anything else not using the top 0.5KW of memory. The hhooks.abs overlay
loads at 16400 octal and links to udos_c2.abs to provide stack pop/push
and other code to easily access internal UDOS functions using RUN commands.

The udos_b2.abs binary is designed to be used with the preconfigured
basic1.abs binary obtained from "The HP2100 Archives". It loads between
16350 octal and the beginning of the HPBASIC drivers (17217), puts a
jump to 5137 in locations 2/3 (autorun), puts a jump to UDOS in locations
77/76 to run UDOS when BYE is entered, and adjusts locations 106 and 116
to make room for UDOS. To install, load basic1.abs, load udos_b2.abs, then
run from location 100. For more BASIC program memory remove the matrix
functions as indicated in the udos_b2.asm comments. Binaries saved using
UDOS will contain the interpreter plus BASIC code, run from location 2 to
start the BASIC program. Running from 100 will erase the BASIC program
for entering new programs. A few 8K-compatible BASIC programs are in
the 8Kbas directory.

Two HP-IPL/OS builds with UDOS are provided, a build with the MAZE game, and
a build with extra utilities, file access words and Octapus. For both of
these builds, 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.
Do slot# DCON to change the USB adapter slot.

File UDOSMAZE.ABS, build date 11/16/10...

HP-IPL/OS  8K   V1.6
? 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 $DEFxxx HEADxxx WORDx
ADDHxxxxx ADDHxxxxxx FIXLxxxx ADDMxxxx VARIxxxx CONSxxxx UDOS DCON FORGxx
PDEF EXPLxxx $EQUxx $SLIxx $TRIx RENAxx MAZE
EOD=016637 FREE=000140
? 

Package list...
Start with hpiplos1.abs (version 1.6 6/9/10)
internal.ipl - select option 2 to remove block support
overlay udos_c2.abs
DEFINE UDOS to 17000 RUN END
dcon.ipl
8kextra2.ipl
FORGET WHEREIS
@BLK 17000 PUT @END 16777 PUT
maze_sm.ipl

(see kernel.txt for the basics, essentially .abs files are binaries that
 are loaded using the HP's papertape loader, run from 2 unless it says
 overlay or run from some other address, IPL files are loaded by attaching
 the file to PTR then entering <PTR, CAPS are things typed into HP-IPL/OS.)

For other uses FORGET MAZE for 4764 octal words free.

File UDOSUTIL.ABS, build date 11/17/10...

HP-IPL/OS  8K   V1.6
? 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 $DEFxxx HEADxxx WORDx
ADDHxxxxx ADDHxxxxxx FIXLxxxx ADDMxxxx VARIxxxx CONSxxxx UDOS DCON FORGxx
PDEF EXPLxxx $EQUxx $SLIxx $TRIx RENAxx WHERxxx DUMP $>VI $>VD $>VC &WFD
VECS PVDR VDIR VDEL VSTAx VREAx VAPPxxx VWRIxx VCLOxx VLD OE OE?
EOD=012706 FREE=001071
? 

Package list...
Start with hpiplos1.abs (version 1.6 6/9/10)
internal.ipl - select option 2 to remove block support
overlay udos_c2.abs
overlay hhooks.abs
DEFINE UDOS to 17000 RUN END
dcon.ipl
8kextra2.ipl
FORGET ABSOUT
hhooks.ipl
oct14a.ipl

Memory from 16500 to 16777 is empty and available for custom machine code.
Machine code can written in assembly and loaded as an overlay, or if not
too complex, entered using the Octapus utility (or PUT).

For more IPL programming memory, Octapus can be removed...

? FORGET OE
? @BLK 16400 PUT @END 16377 PUT

This provides 3513 octal words free.

The hooks provide a set of words that resemble VDOS but are simpler...

"FILENAME" VREAD - opens a file for reading via MS input commands
"FILENAME" VWRITE - opens a file for writing via MS output commands (deletes)
"FILENAME" VAPPEND - opens a file for writing, data is appended to the file
VCLOSE - closes a write file
VDIR - lists the disk directory
"FILENAME" VDEL - deletes a file
"FILENAME" VLD - loads an IPL file
VSTAT PNUM - prints error status

MSBIN MSWIN MSBOUT MSWOUT MS$IN MS$OUT and MSCRLF can be used to read from
and write to open files. >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...

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

...afterwards "WORDNAME.IPL" VLD can be used to reload the word.
This is handy for rearranging dictionary words. Groups of words can
be saved to a single file by using multiple EXPLAIN commands.

A possibly useful aspect of UDOS is it can also punch... if the USB device is
connected to a PTP device it detects the situation and just saves memory to
ABS. This can be used to make UDOS builds under simulation without having
the usual punch code loaded, which is how these builds were made.


The games binaries were made using the basic1.abs version of HPBASIC with
UDOS "B" loaded and the matrix instructions removed to provide more memory.
These binaries are configured with TTY=slot 11, and PTP/VDRIVE=slot 12,
run from location 2 to run the embedded program, or run from 100 to erase
the program to enter in and save a new program. The TTY slot is not easily
changed other than going through all the code between about 17300 and 17677
and changing the bottom 6 bits of I/O instructions that reference slot 11.
To alter the PTP/VDRIVE slot edit the udos_b2.asm file (change the USB EQU)
and reassemble using a HP21xx cross assembler (such as Eric Smith's asm21.pl)
then load the resulting ABS on top of the binaries to overlay and replace the
existing version. Provided the ORG remains the same (16350) nothing else needs
doing other than running from 2, stopping any program in memory and entering
BYE to run the dos to test and save the new version. If the ORG and memory
layout is changed then have to start from location 100 to reset the pointers
(erasing the embedded BASIC program). Alternatively, the PTP/VDRIVE slot
can be changed by directly altering the bottom 6 bits of the 5 locations
that reference the USB equate, see the udos_b2.lst file for locations.

Refer to the "PocketGuide" docs (at bitsavers and hpmuseum) for more info
about HPBASIC, the version used for this material (basic1.abs) does not
support papertape operations (doesn't need to with UDOS). Getting BASIC
source into HPBASIC without actually typing it in can be tricky, most modern
terminals paste code far to fast and immediately overrun the console. The
Windows Hyperterminal supports character and line delay to slow it down
(if you can get it to work - my copy quit working, no longer can see my
serial terminal). Under Linux I use a program (actually a simulated
HP-IPL/OS program) to read bytes from a file and write them to /dev/ttyS0
with delay, the terminal emulator should be running at the same time to
monitor progress and make sure the port speed etc is properly set.

Refer to the HP-IPL/OS docs and pages for more info about using HP-IPL/OS.
Best to get the hpiplos_main_testing.zip and wade through the stuff best
you can, the hpiplos.html file in the docs folder is a good place to start,
covers the kernel and the extra words. 8KW versions of HP-IPL/OS cannot
practically support the CREATE word assembler so if machine code is needed
use a cross-assembler and overlay the binary, or use the Octapus utility.


About Octapus...

The Octapus utility in HPOSUTIL.ABS is run by entering OE? or OE - entering
OE just runs the utility, entering OE? displays the help screen first...

OCTAPUS-E CONTROL KEYS:
A) ASM AT ADDR    D) DUMP CORE
R) RUN AT ADDR    I) DUMP TAPE
T) LOAD TAPE      P) PUNCH TAPE
V) VERIFY TAPE    B) TAPE BOUNDS
L) RELOCATE CODE  S) SEARCH
HIT ESC TO ASSEMBLE NEXT LINE
CTRL-C FOR CURRENT LINE CONTENTS

*** OCTAPUS-E ***
?  

All functions are engaged using control keys. The more useful functions are...

Control-A - Prompts for address then assembles entered lines. DEL/BS to stop.
            Supports standard HP 21xx instruction forms but all addresses
            must be specified, not a symbolic assembler so no labels, first
            characters on each line must be an instruction or OCT for data.
Control-R - Prompts for address then jumps there.
Control-T - Loads an ABS-format binary from the paper-tape reader.
Control-D - Prompts for range (from,to) then dumps memory in octal and
            as disassembled instructions.
Control-P - Prompts for range (from,to), then outputs ABS-format binary
            to the paper-tape punch. Multiple ranges are not supported.
Control-B - Reads an ABS-format binary from the paper-tape reader and
            prints the ranges of each load segment.
Control-S - Prompts for a value to search for, then prompts for range
            (from,to), then prints the addresses that contain the value.

Note that the assembler/disassembler is very primitive, doesn't get
some compound instructions correct, encode these using OCT statements.
Backspace or Delete (depending on terminal) to stop assembling.
Ctrl-R then 2 to return to HP-IPL/OS.


About the UDOS "hooks"...

Machine code can be run from the HP-IPL/OS prompt or an app word using
the RUN word.. [address] RUN executes a jump to the code. To exit back to
HP-IPL/OS without restarting (or if called from a word, continue running)
then the machine code has to do a JMP 321B,I instruction. To pass data
back and forth using the stack do JSB 324B,I to pop the stack into the A
register, do JSB 323B,I to push the A register to the stack.

The beginning of the "C" version of UDOS contain the addresses of internal
subroutines which can be called to make dos apps. If the address for GSB
is placed in location 350B then anything using MS input can read from a
file instead, similarly if the address for SSB is placed in location 351B
then anything that writes to MS output can write to a file. These functions
can be used to create a nicer dos for HP-IPL/OS than possible with UDOS alone.

[see hhooks.asm and hhooks.ipl for the code]

The hooks machine code loads after Octapus, if present nothing needs to
be done to protect the memory. If Octapus isn't present then tell HP-IPL/OS
not to access past 16400 octal by entering: @BLK 16400 PUT @END 16377 PUT

Locations 16500-16777 are still available for more machine code.

Usages:

To list the directory: VDIR
To delete a file: "FILENAME" VDEL
To load an IPL file into the dictionary: "filename.ipl" VLD
To save system to an ABS (if SYSALL present): "FILE.ABS" VWRITE SYSALL VCLOSE
To write string(s) to a file: "FILENAME" VWRITE "string" MS$OUT MSCRLF VCLOSE
To read the string back and print it: "FILENAME" VREAD MS$IN $PRINT
To set MS in/out back to papertape: MSPAPER (or 2 RUN to restart HP-IPL/OS)
To see why it said error: VSTAT PNUM

To save dictionary words to an IPL file: (didn't try but should work)

"FILENAME.IPL" VWRITE >MS
EXPLAIN 1STWORD
...
EXPLAIN LASTWORD
"CONSOLE" MS$OUT MSCRLF
VCLOSE CONSOLE

Output is suppressed while redirected, if you need to use commands etc
then continue writing to the file do <>CON to restore console output
then do >MS when ready to continue directing output to the file.
The CONSOLE command word also resets MS to papertape as a safety
feature to avoid leaving MS directed to arbitrary driver code
which might get removed while hacking.

Not wasting memory on a full dos prompt but commands can be given manually
by doing VECS "command" $>VC then PVDR to see response. Some commands take
a bit to process, PVDR might not print anything if busy, try again.
Simple VDRIVE commands can be given from words (see the VDIR and VDEL words)
but this simple system isn't designed for heavy-weight usage - for example
to save memory the &WFD word to wait for a response discards the byte to
keep from having to preserve it just to drop it, a real file-processing
app that needs to actually parse the first response byte needs to read
the VDRIVE channel directly, looping until bit 15 clears.

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

These notes last modified 11/19/2010
Terry Newton (wtn90125@yahoo.com)
