HP-IPL/OS Disk Programming

5/1/05 - contents of this page are subject to change... this is an area of active development.
3/6/07 - still developing :) just not this text anymore so may not exactly match current code.
7/20/07 - out-of-date disk builds removed, procedures should be mostly the same. Older versions of XDOS had a bug in XDEL (left a value on the stack), never noticed until I tried to call it from another IPL program, corrected in XDOS 1.26 and in the v1.1 builds. Also modified XLOAD so that it executes -TBG if present to prevent failure when loading systems without a TBG interrupt handler present.
8/30/08 - added info/links for the new library system.

Disk drive programming can be tricky business, especially considering all the different drive types that can be hooked up to a HP21xx minicomputer or simulator. Hard-coding disk functions to a particular drive prevents its use with other drive types, so we developed a device-independent solution which uses a collection of low-level block-oriented disk words that interface with device-specific driver code, reducing all drives to a few simple functions. Transfers are performed 1KW at a time regardless of the actual sector size, allowing disk software to be written that works without change on a variety of drive types. Presently drivers are available for the 7900 disk using the 13210A interface, the 7906 using the 13037 interface, and for Bob Shannon's custom IDE interface. More drivers are planned.

Skip ahead to...

Currently available files concerning disk programming...

Dos Progress...

For awhile all we had for a "dos" was TDOS, which is limited to 32 files and uses file numbers rather than names. Crude to say the least but it proved the concept, I developed it using a 7900 disk then Bob ran it on his IDE disk and despite its limitations it was better than nothing. Then came XDOS in April 2005... much better! Whereas TDOS only supported 32 files with no filenames or directories (all it knew was block offsets derived from file number), XDOS supports up to 64 volumes each containing up to 64 files with up to 16 character filenames. XDOS has commands for adding, deleting, renaming, and changing to volumes, saving system binaries, transfering files to and from alternate memory, displaying file contents, listing volume and file directories, deleting/renaming files, loading binary systems or IPL files, and various recovery and import/export functions... pretty much everything needed to operate HP-IPL/OS from a disk.

XDOS is based on a draft spec from Bob called "Simple File System" (SFS) which I've had for awhile but for various confusing reasons haven't been able to fully implement. The SFS specs consisted of two parts, a disk layout and a set of words for accessing disk files. XDOS implements the disk structure of SFS but not the file access words. In XDOS the only way to "process" files is copy to alternate memory and process there, or just go straight to the disk and do what's needed block by block. For operation purposes this is fine and in some cases the only way to get the job done. A "dos" needs to operate at a low level and doesn't fit with a high-level file programming model like SFS so I found it hard to implement SFS without a dos. Now I have a way to operate and debug the system so I started writing sfs.ipl again [...]

5/12/05 - SFS lives! Presently 0.66 seems to be hanging in there, came out about 2KW in size. The present configuration borrows the 16Pad and FindEntry subs form XDOS, same code is copied into sfs.ipl and commented out for reference and to adapt to other configurations. The SFS ipl provides only file-access words, it contains no words for formatting the disk, manipulating volumes, renaming files, listing directories etc and relies on XDOS for these things. Still very early, needs lots of testing and possibly changes or bug fixes if problems are detected.

5/15/05 - fixed XINIT and XSHOW, added $VOL to push the current volume name (from the XCV variable set by XDOS). Also added ?SFS that prints CW, drive#, vol# and file# for each of the 4 SFS buffers, handy.

5/16/05 - the XSHOW bug-fix in build .67 probably wasn't really a bug, after fiddling with it realized I was pressing enter so reworded the prompt to say "space" instead (but ended up being smaller because of other tweeks), but now I found another XSHOW bug... when listing binaries it fails to stop at the end of memory and locks up in an indirect loop. Press Q to exit when binary listings get past 77000 or so, will look into it when there's other fixes to make.

5/26/05 - SFS 0.67 had a serious bug I should have noticed but didn't until I tried to write a file copy. The problem was <FILE and >FILE saved the specified buffer number to the same internal variable causing major malfunction... separated the buffer number variables for SFS 0.68, don't know what I was thinking. While I was fixing that I also modified ?SFS to list filesize and pointer for open files, and modified XDIR so instead of printing dir block info (same numbers can be had from LSVOL) it prints current drive number then volume name.

6/1/05 - SFS 0.69 posted, binaries include the slow library system.

6/15/05 - posted experimental 7906 build, has all the "stuff" except no boot extension yet, fixing to write one that incorporates a few new features over the 7900 bootext, including auto-adapting to slot# and an option to halt to give an opportunity to enter config info manually. Coming soon...

6/19/05 - posted "TestB" version of 7906 build with the config stuff. Note that unlike my 7900 boot extension this one runs from 2012 to write to disk - there is a HLT in 2011 for when things go wrong and execution wraps. SR must contain the disk controller slot in bits 6-11 (if not in slot 16). Set bit 15 of SR before running to write boot extension to fixed platter. Only drive 0 is supported for booting. After writing it halts with code 44. This boot extension can patch its own slot addresses if the disk controller is moved, rewriting is not necessary. To reconfigure slots when booting from disk, set bit 5 of SR to halt after loading then enter TTY and BACI slots into bits 0-5 and 6-11 and press run. Set bit 12 for baci console (not tested), set bit 15 with bits 6-11 clear to disable autostarting with a TTY console. Autostarting is required for baci to work. When booting from papertape, when it halts to reconfigure put TTY and BACI slots in SR as described, set P to 70 and run. Normal running from location 2 has not been altered.

This is about the simplest scheme I could come up with, most of the functionality is in a tiny CFGE word which sets 70 to jump to itself and clears 72. If run from 70 it sets the slots, puts the SR value in 72 and runs from 2. !SDC picks up 72 and if non-zero sets TTY or BACI console depending on the setting of bit 12, clears location 72 and runs from 2 again to reconfigure the console. CONFIG itself has been expanded to allow setting the slot of the new HPIB driver (also not tested), and sets slot vectors up to 47 to dummy subs if any slots are changed. It is not necessary to have !SDC and CONFIG present, CFGE is enough to reconfigure via SR and run from 70.

Here's an edited dump of a simulated 7906 SFS/XDOS session from this morning, as I arranged files to my liking and removed the baci and hpib drivers and high-level config stuff from my personal build.

Library Updates and Original Speculations...

8/30/08 - This new implementation of the library does away with the binary byte to mark the end of the library (although can still read the old format, if adding code the mark won't be removed). The transfer utilities are now named D>L, LDEL became LFORGET because it removes everything after a segment too (like FORGET), added A>L and L>A for copying alt mem to the library and vice versa, and MS>L for copying a library file from papertape into the library. Putting multiple words into a library segment to run-and-forget requires that the first word be the same name as the library name, and also be the word that runs the application. For example, to put the following contrived app in the library...


...rename the main word (DOCOUNT in this case) to (say) MAIN and add a new word with the desired name that runs MAIN, print the components to alternate memory using redirection, then copy it into the library...

ZAM 2 MSUSER >MS ;clear and redirect prints to alt mem
EXPLAIN DOCOUNT ;add the new "chain" word that runs it first
"VARIABLE COUNT" $PRINT CRLF ;manually print any variable lines needed
EXPLAIN PCOUNT ;add any subwords needed by the app
EXPLAIN MAIN ;add the renamed main app word
"LIBEND" $PRINT CRLF ;manually print LIBEND line to end the segment
CONSOLE ;undirect MS and console
"DOCOUNT" A>L ;copy to library (assumes it's open)

Another way to make a library app is to write it directly...


...then use "name" A>L (if written with AEDIT) or "name" MS>L (if a PC file attached to PTR). It is also possible to convert existing IPL apps/files to use with the library by changing the CONSOLE at the end to LIBEND (and maybe remove comments to make smaller). It's still a manual process but still quite useful, one of the main advantages of loading utilities from the library is it does not disturb alternate memory, which may contain something being worked on.

11/19/07 - The "fast" library system
uses machine code to search for ";;" markers, makes a HUGE difference
in operation speed. The old system might have taken a minute to search
for a file, now it only takes a second or so and without having to use
an index system. A new SETLIB word permits changing the library file
and saves the details in an array variable so it sticks with DGEN. An
LBUF variable defines which SFS buffer is used for the library. An
LCLOSE word saves changes and releases the buffer, LIB reopens the last
library defined/opened by SETLIB. Operationally it's pretty much there.

5/17/05 - This "slow" implementation is a bit simpler than I originally envisioned, no variables are needed to hold the "current" library and to switch to another library simply open another one (using a new LIBOPEN or similar word). Rather than variables and stuff to set them just DEFINE MYLIB drive "volume" "filename" LIBOPEN END then entering MYLIB would load the library without further complication. Assuming the library-opener gets named LIBOPEN.

In general mostly nameless terms, from my perspective to make a library system useful I need to be able to...

Tell it with a variable what buffer to use. Default 3 to use the last SFS file buffer but can be changed with a PUT in case there isn't that much memory available. The minimum practical SFS / Library configuration would be 32KW each for system, alternate, buffer 0 and buffer 1 (128KW total) with the library assigned to buffer 1 leaving buffer 0 available for programmed file operations.

Open a specific library file into the assigned buffer. If the file doesn't exist it should create an empty library in the required format, then open it. I've written this code, haven't tested but just a straightforward use of DIRECTORY OPEN and CNF. Because SFS should be off when running non-SFS utilities that write to disk (-SFS) need a quick way to get the library back but that's trivial as noted above.

Close the library file, writing changes to disk if modified. For efficiency I don't want things that save to the library to write to disk every time they're used, and a mistake could corrupt the library, therefore nothing is written to disk until the library is closed.

Run something from the library and remove it from the dictionary after the program exits. Very simple (fast) syntax, something like R name. This is fairly easy to program using an easily-parsed index table, but requires a lot of code and extremely slow using non-seeking stream methods like MSSCAN which is ok for papertape but I don't want to wait 25 seconds for it to find something that takes 1/2 second to run. SFS has SEEK, works great and since only a pointer is updated, it's extremely fast. Once found, loading, running and forgetting the IPL code is easy.

Load something from the library, leaving it in the dictionary, same process as above but skip run/forget.

Write a single high-level word in the dictionary to the library (in memory). This is where it gets pretty tricky. I could put an index table at the very beginning but that puts garbage in front of a simple text viewing of the library. Putting the index at the end makes the filesize of the library always the same, worse. Both methods put hard limits on how many IPL chunks can be addressed. Instead the index should be appended to the last IPL chunk. The best arrangement I've discovered so far is:

definition END
perhaps an existing IPL defining multiple words
starting with an ETC word
[space pad if not even] (remaining is binary, no more CRLF's)
(i) [000000]
[WO] [RD] [000004] [offset a]
[ET] [C ] [000003] [offset b]
[offset i] (last word points to 0 before index)

All offsets are in bytes to permit feeding them directly to the SEEK command. The last 16-bit word of the file (always even in size) contains a SEEK pointer to the zero marker that starts the index, this marker location must contain zero to be a valid library file. Note that the names are stored in the same mannor as HP-IPL/OS words, a listing of the library contents would resemble a WORDS display. A little inconvenient as far as listing names but this method is very efficient (4 words per chunk of IPL) and permits use of existing HP-IPL/OS subroutines to parse the command parameter and convert the name to the internal TB1/TB2/TL format. Note that IPL chunks should end in something besides CONSOLE, which precludes running and forgetting unless that functionality is hard-coded into the IPL chunk itself. I'd rather specify. Whatever the chunks end with, that word would do the CONSOLE, and provide run/forget if that's what was requested.

The format allows entire multi-word IPL files to be considered one chunk, so need something that copies an IPL disk file into the library, automatically changing the normal CONSOLE at the end into whatever word is needed to allow run and forget to work. Entire packages consisting of dozens of words can be run then removed so long as the name in the index is the same as the first word of the package, that can be arranged.

Need to delete words from the library. This will probably be tricky since it is not desireable to leave holes, everything after the deleted word needs to be moved down to fill the space, and index offsets adjusted accordingly. Just a thing, nothing too difficult.

Finally could use a word that lists the contents of the library, XSHOW would work (listing the entire file) but something that looks like the WORDS display would be more useful.

As usual all of this is subject to change as [or if] code is written. If anyone has any comments let me know.

A Slow but Simple Approach to Library Files...

[the following is really outdated... left to document HP-IPL/OS history...]

5/28/05 - The index-based system of library storage is likely a superior method, especially for speed, but the algorithm involves a few tricky operations like temporarily storing indexes at the end of the file's space but backwards to avoid introducing artificial limitations like the number of words that can be stored. Then there's error-checking while all that's going on to limit it before there's a collision. Same old stuff but I just went through all that and my desire to implement a library scheme exceeded my time I have for programming, so I went back to MSSCAN just to get something working. Scanning an input stream (any stream let alone one that has to USPACE twice for every byte read) is extremely slow, taking up to 20 seconds or more to find a word to load, but at least it works.

The original implementation used the existing msscan.ipl words but I discovered a serious problem with the old RUN&DEL, in that it kept the address to delete on the stack while the word was running, very very dangerous and prevents using the stack to pass parms. Boy did it prevent... random pokes, ouch. So I modified it to save the address in a variable to allow typical utilities to function when running out of the library.

6/1/05 - This implementation includes msscan and adds words for using as a library system...

LIB loads or creates LIBRARY in the volume LIB which must already exist on drive 0.
"name" D2L saves a definition in the dictionary to the library (but not to disk).
"name" R loads and runs a word from the library then removes it from the dictionary.
"name" L loads a word from the library, leaving in dictionary.
"name" LDEL deletes word and all following words from the library.
LDIR lists word names in library.

Nothing is written to disk unless the library is closed (3 CLOSE), if desired a library save command can be defined to contain something like 3 CLOSE LIB to save the library then open again.

This scheme allows large multi-word IPL chucks to be run/removed provided the word carrying the chunk name appears first, this is the case if MKWORD/ENDWORD is used to encapsulate subs vars and all into a single word. At the moment I don't have a file-to-library fuction but I don't think it would be all that difficult. IPL-chunks must end with LIBEND rather than CONSOLE so they can be run then deleted, arrange accordingly. There must always be an ascii 128 at the end of the library file to tell MSSCAN to stop.

Installing and Using XDOS

XDOS lets a HP-IPL/OS user save, load and show files to and from named disk files arranged in named volumes. For convenience XCV contains a number that defines the entry number of the "current" volume. Changing to a volume sets XCV and other words use XCV to know what volume to operate in. This gives an illusion of traveling, under the hood it specifies the volume for the lower-level functions so the user doesn't have to specify it as often. XDOS includes words for creating, renaming, deleting, and changing to volumes, transfering alternate memory to and from files, listing the volume or directory blocks, and for renaming and deleting disk files. The formatter and other utilities are in their own ipl file, load as needed.

The first thing to do is get XDOS and the utilities into memory. XDOS requires the words in dms.ipl and disk.ipl, and a working disk driver must be in place. If TDOS is loaded and you don't need it anymore, FORGET +DB to get rid of it. Attach xdos.ipl to papertape reader then LOAD, then attach xutils.ipl to paper and LOAD that too. At first it's ok to load xdos.ipl on top of TDOS to make both available, just be careful not to use TDOS to save files to a XDOS volume because no directory entry is added and XDOS will eventually overwrite it.

Next, "format" the disk using XINIT or XI79 if using a 7900 disk. The init process puts geometry numbers into disk block 6 and resets the volume names to all-space. Nothing outside of block 6 is changed. XINIT prompts for the number of volumes, and the number of files in the last volume. Intermediate volumes are allocated 64 files each. To get the maximum SFS "partition" size of ~260 megabytes enter 100 octal for both numbers. XI79 is hard-coded to divide the disk into 3 volumes of 12 files each. Once the init has been run, nothing else is supposed to ever change the geometry numbers. If for some reason block 6 gets corrupted, rerun XINIT (or XI79) then run VRECOVER to add generic volume names to entries that appear to point to a non-empty directory.

Now create a volume to work in. If there are TDOS files present do "TDOS" MKVOL right after XINIT to protect the files, then optionally "TDOS" CHVOL XRECOVER to create a directory for those files (note.. takes awhile to determine filesize by scanning the file itself). If you just don't go there the files should be safe. Using a 7900 formatted with XI79 this protects only the first 12 TDOS files, make another volume if necessary to protect more. Finally (or right after formatting if not preserving anything) make a volume to work from, something like "MYSTUFF" MKVOL then "MYSTUFF" CHVOL to make it "current". If you DGEN at this point, then booting the disk or entering DBOOT will take you back to this location. "filename" XSAVE saves the current system to a file, "filename" XLOAD loads a system or ipl file. XDIR lists the directory and the current volume. Note... the current volume concept is strictly for operating convenience, nothing to do with SFS (but an SFS program is free to make use of the current volume code if it helps).

Caution... do not use XDOS commands until XINIT, XI79 or another SFS-compatible formatting utility has been run first to write a valid volume index table to block 6. Operating with random data would not be good.

The xdos.ipl file provides the following words...

"VolName" MKVOL - creates a new volume and overwrites the directory block with zeros
"VolName" CHVOL - makes named volume current
"VolName" "NewName" RENVOL - renames a volume
"VolName" DELVOL - deletes a volume after confirming
LSVOL - lists available volumes and their stats
XDIR - prints current volume name/stats and lists the files it contains
ZAM - writes zeroes to alternate memory
"FileName" bytes AM2F - copies specified number of bytes from alt memory to a file
"FileName" F2AM - copies a file into alternate memory and sets DirInfo array
"FileName" XSAVE - saves the current running system to a file
"FileName" XLOAD - loads a system binary or ipl file
"FileName" XSHOW - shows file contents as text or hex if binary
"FileName" "NewName" XREN - renames a file
"FileName" XDEL - deletes a file after confirming
XCV - variable containing current volume number
WKBUF - constant containing address to use as a 1K buffer
VolInfo - 5-location array containing current volume stats
DirInfo - 6-location array containing current file stats
FindEntry - subroutine for searching for volume or directory entries
GetVol - subroutine that uses XCV to load VolInfo with current volume stats
GetFile - subroutine that searches for a named file, if found pushes location and sets DirInfo
PutFile - subroutine that uses DirInfo to create a named file, if successful pushes location

The xutils.ipl file provides...

XINIT - general-purpose SFS formatter, run first for IDE
XI79 - formatter for the 7900 drive, 3 volumes of 12 files each [now in its own file]
"FileName" bytes MS2F - copy MS input to a file (not redirection)
"FileName" F2MS - copy a file to MS output (not redirection)
"FileName" ABS2F - import ABS from MS input to a system file, prompts for ra and exit
VRECOVER - recovers deleted volumes, use after using XINIT to fix block 6
XRECOVER - recovers files in current volume and attempts to guess size

When importing IPL files you must know the filesize, use a dos prompt to determine file size in decimal. After attaching the PC file to the MS input device (default is papertape reader) then If the file is say 12345 bytes long use something like DECIMAL 12345 OCTAL "MYFILE" MS2F to copy to a file. Get the size right, if MS is read past the end of the input stream it essentially locks up until you feed it the specified number of bytes. To copy from something other than papertape then preceed the MS2F command with MSBACI or another MS driver.

When importing ABS or other binary files the transmission medium must accept all characters without terminating, there might have trouble trying to punch it through BACI when BACI is also the console but who knows might work. More likely the trouble will be getting the PC terminal software to send a binary with no formatting without barfing, some terminals try to echo the garbage with unpredictable results. Papertape is the most reliable HP<>PC method, and is the only method under simulation. Typically when running under SIMH I ctrl-e to get the sim prompt then enter attach ptr whatever.ipl followed by run 2 (or c to continue but that doesn't redisplay the prompt which bothers me so I reset a lot...) to return to the HP-IPL/OS prompt and do whatever.

ABS2F checks the imported file to see if it has 124003 in location 2 (a jump vector, required to load), if not present then it prompts for a startup address and asks if it should add an exit vector at locations 77/76. To my knowledge this is specific to HPBASIC and restores HP-IPL/OS after entering BYE. The XDOS load function saves the currently running system in alternate memory before loading another system, so long as the newly loaded system doesn't use alternate memory you can return to the previous system by executing location 77000. Successive calls to 77000 swap the two systems back and forth. The exit vector prompted for by ABS2F puts 77000 in location 76 and JMP 76,I in location 77.

The F2MS command copies a HP disk file to MS output, by default papertape punch. The output file must already be attached. On a real machine the best bet is rig up software to capture a raw serial stream then MSBACI "filename" F2MS, unless you're lucky enough to have a punch emulator. Under SIMH punching to a file works fine, attach ptp filename.

VRECOVER and XRECOVER utilities allow recovery of deleted volumes and files, especially useful if something corrupts block 6 requiring the use of XINIT. The new volumes and files are given generic filenames like VOL000000 VOL000001 FILE000007 etc. For shorter names DECIMAL first, don't forget to OCTAL afterwards. The number indicates fileslot, rename with VOLREN as needed. I just tried XRECOVER after copying a file then deleting it, got back my file plus a garbage file. VRECOVER and XRECOVER aren't supposed to touch entries that already have a name so theoretically they won't hurt anything. XRECOVER scans empty entry filespaces, if 124003 is present then assumes its a binary system and fills in the bytesize as 177400, otherwise it scans the file word by word until it encounters a zero, doubling to fill in a byte size that's always even. Not perfect but IPL files are tolerent of appended characters so in practice this seems to works fine.

Copying a file can be accomplished by copying to alternate memory using "file" F2AM then saving to a new file using "file" #bytes AM2F - use XDIR to determine #bytes, or get from DirInfo 3 ADD GET. For example: "sourcefile" F2AM DirInfo 3 ADD GET "destfile" AM2F. Copying between volumes can be accomplished by inserting "volname" CHVOL after the F2AM command.

Presently XDIR only works correctly in OCTAL mode, in decimal the formatting isn't right and numbers larger than 32767 are displayed incorrectly. Octal numbers are more useful when most everything else is in octal but eventually I'll probably clean up the decimal display.

Using SFS for File Access

Bob Shannon's Simple File System allows the programmer full read/write access to files by linking them to HP-IPL/OS' "MS" (mass storage) stream system. SFS provides commands for attaching a directory block (volume) to a buffer, opening files by copying them to the buffer, reopening a file at the last access point, attaching MS out to an open file for writing, attaching MS in to an open file for reading, setting the byte pointer for random access, closing the file writing it to disk if changed, creating a new file and deleting a file. When redirected MSBIN MSBOUT MSWIN MSWOUT MS$IN MS$OUT MSCRLF and anything using them (including LOAD) can be used for reading and writing files. MSPAPER (or CONSOLE including after an IPL load) restores normal papertape MS I/O.

SFS uses subroutines from XDOS as written must be loaded after XDOS, also needed at minimum to format the disk and make a volume to work from. Total requirements for sfs.ipl are extra.ipl create.ipl, dms.ipl, double.ipl, disk.ipl, ide.ipl 7900.ipl or another disk driver, and xdos.ipl. The xutils.ipl file is required for formatting but can load after sfs.ipl, FORGET when done. For convenience sfsbins.zip contains binary builds for Bob's IDE disk and for the 7900 disk, tested under SIMH but maybe it will work on the real thing.

The main SFS words are...

"name" buffer drive DIRECTORY - loads specified directory into specified buffer
"name" buffer OPEN - copies specified file into specified buffer with pointer=0
"name" buffer REOPEN - copies file into buffer with pointer=last access point
buffer >FILE - redirects MS output to buffered file for writing
buffer <FILE - redirects buffered file to MS input for reading
buffer byte SEEK - sets pointer for next read or write
buffer CLOSE - close the file, writing buffer to disk if anything was written
"name" buffer CNF - create a new empty file
"name" buffer DEL - deletes a file
buffer RELEASE - marks buffer as unused

SFS supports up to 4 buffers max, buffer number must be 0-3. Before a file can be opened, reopened, deleted or a new file created there must be a directory in the buffer. >FILE and <FILE should only be used with open files, if not no error message is displayed (those are machine-coded words) but FSS is set to indicate error and nothing useful happens. SEEK and CLOSE only work if the specified buffer contains an open file. RELEASE can be used at any time but if a file is open all changes including last access pointer are abandoned and nothing is written to disk. XDOS commands that write to disk don't work unless all SFS buffers are released first to avoid potential tangles.

The FSS variable contains file system status, FSS GET PNUM to view, FSS 0 PUT to clear. Several variable arrays contain information about directories and files attached to buffers. See sfs.ipl for error codes and what the various variables do, some contain vital information about where things are so don't change them except for FSS. CWA array entries can be manipulated if you know what you're doing.

Programmers can also select the proper alternate memory page directly using USPACE with the buffer number plus 1 on the stack then manipulate alternate memory directly. ALWAYS 0 USPACE WHEN DONE! if you access alt mem directly. The streaming subroutines do this automatically so this is only a concern when the programmer uses USPACE (as always but with files also in memory it becomes very important). After making changes set the appropriate bit in CWA (locations 200-203) to mark the buffer as dirty so CLOSE will write it back.

Terminology note... generally "directory" refers to a 1KW disk block containing file information, and "volume" refers to the collection of files defined by that directory block. As I write it, you change to a volume to do stuff in that volume with XDOS, and you load a directory to access files listed in it with SFS. In normal use the terms are interchangeable.

SFS example...

"WORK" MKVOL ;make a volume using xdos
0 >FILE "Hello, file" MS$OUT MSCRLF
"WORK" CHVOL ;change to volume using xdos
"FILE" XSHOW ;display file just created
0 >FILE "More stuff" MS$OUT MSCRLF
"FILE" XSHOW ;line was appended
0 <FILE MS$IN $PRINT ;print 1st line of file
0 <FILE MS$IN $PRINT ;prints 2nd line of file
0 RELEASE ;if done to use XDOS commands that write

Note... be careful using MS$IN to read unknown files, if CRLF is not encountered or an SFS error occurs the X-stack overflows. Another reopen, read, print would have produced this error because the file only contained two lines, this is how MS$IN works. If an attempt is made to read past the end of file, 0 is returned and FSS set to 601. Of course MS$IN doesn't know that so it piles up 0's until the X stack overflows. For better control use MSBIN/MSBOUT to read and write bytes directly, for example...

;assumes dir already loaded
FSS 0 PUT ;clear previous errors if any
DO ;until eof
MSBIN ;get byte
FSS GET IFNZ ;if eof error
DROP 1 ;drop 0 and push 1 to terminate
PCHR ;print char whatever
0 ;push 0 to keep going
UNTIL ;eof

Some disk operating systems set EOF immediately after the last byte was written but as currently written SFS doesn't flag an EOF until it tries to read past the end. I'm not sure which way is more correct, perhaps setting EOF after the last byte is read would make coding a bit easier (but not by much), however that means FSS would contain a non-zero word when no error took place. As written the FSS=601 code is an error that occurs if an attempt is made to read past the end of file which makes more sense to me, and permits more simplistic EOF detection of text by just looking for the 0.

SFS Utilities

The SFS utilities package is now in sfsutils.ipl, these are the original words...

; "DefName" D2F - writes def to file of same name in current vol
; must be high-level def, otherwise prints error message to file
$DUP $DEFADR IFZ ;if DefName not found
$PRINT " not found" $PRINT
ELSE ;DefName found...
#0 DRV GET $VOL DIRECTORY ;set buffer 0 to current volume
FSS GET IFNZ $DROP ELSE ;if error exit otherwise
$DUP #0 CNF FSS GET IFNZ $DROP ELSE ;create file, exit if error
$DUP #0 OPEN MS_SAVE #0 >FILE >MS ;open file, redirect print to file
$DEFADR PDEF "CONSOLE" $PRINT CRLF ;print loadable definition to file
<>CON MS_RESTORE #0 CLOSE #0 RELEASE ;undirect, close and release
; "file" destdrv "destvol" FCOPY - copies a file
; text/ipl files only, does not set LA/RA
#0 SWAP DIRECTORY ;load destination directory in buffer 0
FSS GET IFNZ $DROP ELSE ;if error drop filename otherwise
#1 DRV GET $VOL DIRECTORY ;load current volume directory in buffer 1
#1 $DUP OPEN ;open source file
FSS GET IFNZ $DROP ELSE ;if error drop name otherwise
#0 $DUP CNF #0 OPEN ;create and open destination file
MS_SAVE #1 <FILE #0 >FILE ;redirect MS outs to dest file
#1 FSA INC GET ;push 1 then byte filesize
+DO MSBIN MSBOUT +LOOP ;copy every byte

5/26/05 - these are early versions, need to figure out a way to make FCOPY update the load/run addresses since CNF can only create text files. SFS is designed for file access and does not use the LA/RA directory fields, perhaps we need a utility for setting them. An automatic workaround is do like XDOS does and if location 2 contains 124003 then make LA/RA=2, ok for now but eventually we're going to want to use the fields for binaries besides entire systems, a more general solution would be "file" buffer loadadr runadr SETBIN or similar. [6/1/05 modified SFS to include the necessary arrays, to fix the example add code after the copy loop that copies the LAA and RAA array entries before closing]

5/27/05 - fixed minor D2F bug, removed extra $DUP. D2F and FCOPY have become "must have" utilities, still aren't in a IPL file yet but I've typed them in manually several times after finding myself without them.

6/1/05 - uploaded better sfsutils.ipl package that takes advantage of SFS 0.69's LAA and RAA arrays to properly set the load and run addresses when copying binary files. Modified FCOPY and added FMOVE which works the same way except deletes the source file after copying, and BCOPY which quickly copies one buffer to another using DMS techniques, updating the appropriate file stat directories. FCOPY and FMOVE include the core code from BCOPY for speed but are self-contained to allow running from the library without requiring BCOPY. See comments for more compact forms if BCOPY is kept in memory, not sure how often file operations will need to be programmed. Anything stored only in the library cannot easily be used for programming since loads do not take place until the console appears. BCOPY is a bit large so presently it's in the utilities package but could end up in the main SFS package.

8/13/05 - updated the sfs.ipl and sfsutils.ipl packages, now version 0.70, fixing bugs in FCOPY and FMOVE, and moving the very useful BCOPY word into the main SFS package. Also added a FDUP word which duplicates a file to a new filename in the current directory. At the moment these changes have Not been incorporated into the pre-made builds, until then if you want the new versions FORGET the old packages and reload the IPL files from papertape. The bugs were insufficient error-checking, be careful when using the old FMOVE which deletes the original file if the destination file already exists even though the copy did not take place. If this happens use the XRECOVER utility to restore the source file.

Low Level Disk Operations

The disk.ipl file defines low-level words that permit device-independent disk programming...

high low SBLA - seeks to a specified 1KW block
memadr R-1K - reads the current 1KW block into memory then increments the driver's block pointer
memadr W-1K - writes memory to the current 1KW block then increments the driver's block pointer
LDFB - loads a 31KW system binary image from the current block
<IDE - reads the disk drive status to detect errors, 0 means OK

...and also defines a few operator functions...

DRV - a psuedo-variable linked to a zero-page location that contains the drive number
n CHDRV - changes DRV to n, all disk functions use DRV to know what drive to act upon
DGEN - writes the current system to block 10 octal, updating the boot image
DBOOT - loads a system from block 10, in effect rebooting a HP-IPL/OS disk

The disk driver ipl file (in addition to the disk driver itself) also should define drive-specific functions, in particular ?DRV. How the DRV number is interpreted is up to the driver, the IDE driver uses it to add the double-word 000002 000146 to the blocks specified by SBLA, in effect skipping the entire SFS disk space. The 7900 driver uses DRV numbers 0 to 3 for removeable platters on real drives 0 to 3, and DRV numbers 4 to 7 to indicate the fixed platters of drives 0 to 3. 7900.ipl defines an additional word for changing platters on the current drive, 0 CHPL for removeable, 1 CHPL for fixed. ?DRV for the IDE prints the drive number and equivalent offset, whereas ?DRV for the 7900 prints the current drive and platter.

When XDOS is loaded its internal variables and subroutines are available, including the WKBUF constant, the XCV variable, subroutines FindEntry, GetVol, GetFile and PutFile, and variable arrays VolInfo and DirInfo containing numbers from the current volume and directory entries. DirInfo offset 3 contains the filesize in bytes after an XDOS file operation, handy for even higher level functions like providing filesize for AM2F, and WKBUF makes a handy substitute for typing 66000 or another memory address when using R-1K and W-1K to examine or modify disk blocks. The other XDOS subroutines and the low level disk words can be used by programs to directly manipulating volume or directory entries but aren't designed for console use except when debugging, and are not to be taken lightly. One wrong move can corrupt the disk! PutFile returns a block location you're supposed to write a file to but if your program confuses the stack you could end up overwriting something. Do not debug low-level disk software unless you don't mind losing the entire disk, you've been warned. Having said that, it is relatively safe to experiment on a different drive provided you ALWAYS make sure a reset or something didn't reset DRV back to zero. By convention a simple reset is not supposed to alter DRV but if a system binary is loaded then DRV is reset to whatever it was when that system was saved, just be careful. I develop under simulation so before every risky test I zip up my disk drive file then if something goes wrong it's no biggie, I just find and fix the problem and restore my disk.

LSVOL and XDIR display low-level details that can come in handy when debugging...

Name Size DB_lo DB_hi FS_lo FS_hi
OLD 000014 000007 000000 000047 000000
WORK 000014 002247 000000 000647 000000
MYSTUFF 000014 002250 000000 001447 000000
Current volume: MYSTUFF NE/DBL/DBH: 000014 002250 000000
XDOS 000002 000002 000000 174000 000000 001447 000000 000000
MAZE.IPL 000000 000000 000000 041521 000000 001507 000000 000001
CAPSLOCK.IPL 000000 000000 000000 003526 000000 001547 000000 000002
1DCA.IPL 000000 000000 000000 013727 000000 001607 000000 000003
XDOSCAPS 000002 000002 000000 174000 000000 001647 000000 000004
HPBASIC 000002 000002 000000 174000 000000 001707 000000 000005
XDOSGAMES 000002 000002 000000 174000 000000 001747 000000 000006

[note XDIR no longer displays dir block location, use LSVOL for this information]

The locations of directory blocks and files are displayed but keep in mind that in volume and directory entries (and LSVOL/XDIR output) locations are arranged low word first, SBLA expects the low word on top meaning you have to push the high word first. In this 7900-formatted disk the third volume is located at 2250 low, 0 high so to load it into memory and dump it use something like...

? 0 2250 SBLA 66000 R-1K
? 66000 66060 DUMP

66000:054104 047523 020040 020040 020040 020040 020040 020040 XDOS
66010:000000 000000 000000 000002 000002 000000 174000 000000 ................
66020:046501 055105 027111 050114 020040 020040 020040 020040 MAZE.IPL
66030:000000 000000 000000 000000 000000 000000 041521 000000 ............CQ..
66040:041501 050123 046117 041513 027111 050114 020040 020040 CAPSLOCK.IPL
66050:000000 000000 000000 000000 000000 000000 003526 000000 .............V..

66000 is where HP-IPL/OS' last user memory block usually located, if you specify the wrong location  bad things happen so make sure you're in OCTAL and don't give commands like this quickly. In XDOS the WKBUF constant pushes 66000 so it's safer to 0 2250 SBLA WKBUF R-1K then dump using WKBUF DUP 60 ADD DUMP. Change the 60 to how many words to dump. Now let's make the CW number in MAZE.IPL equal to 1 instead of 0...

? 66037 1 PUT 0 2250 SBLA 66000 W-1K
Current volume: MYSTUFF NE/DBL/DBH: 000014 002250 000000
XDOS 000002 000002 000000 174000 000000 001447 000000 000000
MAZE.IPL 000000 000000 000000 041521 000001 001507 000000 000001
CAPSLOCK.IPL 000000 000000 000000 003526 000000 001547 000000 000002
1DCA.IPL 000000 000000 000000 013727 000000 001607 000000 000003
XDOSCAPS 000002 000002 000000 174000 000000 001647 000000 000004
HPBASIC 000002 000002 000000 174000 000000 001707 000000 000005
XDOSGAMES 000002 000002 000000 174000 000000 001747 000000 000006

This is scary stuff, when making this example I accidently typed 66027 in the PUT and corrupted the filename, requiring (with dir block in mem at 66000) 66027 20040 PUT 0 2250 SBLA 66000 W-1K to fix. 20040 of course is double spaces.  BTW currently I don't know what the CW field is for, that's why I chose that one to change as an example but changed back to 0, no telling what CW will come to mean. Caution... always SBLA before W-1K or R-1K, remember that they increment the internal block pointer so consecutive calls read/write consecutive blocks (handy when writing load/save routines).

In a program it is desireable to <IDE after disk operations to push the error status, if at any time it is not 0 then the program should abort with an error message or other indication of failure.

The SBLA R-1K W-1K and <IDE are all that's needed to do most low-level operations except for loading a system file, which requires code that jumps high to avoid being overwritten. LDFB (calls code that) does this and loads a system binary from the current block. In the above example I can "boot" the XDOS binary by (using numbers returned by XDIR) entering 0 1447 SBLA LDFB (-IRQ first if loading something that expects interrupts to be off, HP-IPL/OS doesn't care).

Disk Driver Programming

The disk driver provides device-specific code for the low level disk words to call. The driver word must write subroutine entry addresses to locations 240 through 245 in zero page to connect code to the low level disk words >IDE <IDE W-1K R-1K SBLA and LDFB. Subroutines within the driver use locations 246 through 250 to receive block address low, high and the drive number. If desired the >IDE vector can point to a dummy subroutine  since the commands are really only useful with Bob's IDE interface although the 7900 driver supports a limited subset of the IDE interface command set. Using >IDE for general disk programming is not recommended at this point, whatever it does will likely be specific to a particular drive so if the driver programmer needs specific functions not covered by the low-level words this would probably be a good place to hang them from.

Low Level Device Independent Disk Words

The disk.ipl file provides the following HP-IPL/OS words...

command >IDE     Send low level disk command using Bob's IDE interface language (1)
<IDE Push disk interface status (0=ok) (2)
highblock lowblock SBLA Set current block address (1K word increments)
Address W-1K Write 1K words from Address to current block (3)
Address R-1K Read 1K words from current block to Address (3)
LDFB Load 31K binary from current block and run from 2 (4)
DBOOT Load 31K binary from block 8 decimal (default boot image)
DGEN Save current system to block 8
drive# CHDRV Change drive number (5)

(1) How much to support on non-IDE drives is optional, the 7900 driver emulates the following IDE interface commands...

; Interface commands...
; 101XXX - SB1 - Sets 8 lsb's of 1K word block address
; 102XXX - SB2 - Sets next 8 msb's of 1K word block address
; 103XXX - SB3 - Sets next 8 msb's of 1K word block address
; 104XXX - SB4 - Sets two 2 bits only of 1K work block address
; 110XXX - RDB - Reads XXX blocks from disk. If XXX=0 one 1KW block
; is read into the disk data buffer from the current block address.
; If XXX>0 then XXX blocks (up to a maximum of 31) is read from disk
; and then transfered to the HP.
; 111XXX - WRB - Writes XXX blocks from HP to disk. If XXX=0 the
; contents of the disk data buffer are written to the disk at the
; current block address. If XXX>0 then XXX blocks (up to a maximum
; of 31) is transfered from the host and written to disk.

(2) Currently <IDE is the only way to obtain disk status for all kinds of drives, the driver can return raw status bits or generalize as desired so long as 0 means OK. In the future we may devise a more general <DSTATUS word to be included with drivers that translates the raw <IDE status bits into standard meanings. Ideas? For now if <IDE pushes 0 then the operation was (probably) successful. Having "IDE" in the name of a device-independent word is a little confusing but that's the way it started out and the name stuck. Subject to change.

(3) Drivers should keep their own internal block address and increment it after each read or write so that subsequent operations do not require resetting the block address. Can be separate variables or the same variable, any app depending on this behavior should not count on separate read/write counters. Disk-based sysgens DO perform sequential W-1K operations so driver MUST increment its internal block counter.. to be totally IDE compatible don't increment the zp BLKAL location, just the driver's internal block pointer (with IDE it's really on a 8051).

(4) Binary images are offset by 2 (the first word of a file is for location 2 in memory), and consist of 31 consecutive blocks containing addresses 2-76001 octal.

(5) CHDRV merely changes location 250 which tells the driver what drive is selected, how the driver interprets this information is up to the driver. The psuedo-variable DRV is tied to this location for convienience. Large drives can be "partitioned" into multiple "drives" by multiplying the locations set by SBLA (246/247) by the drive number.

The device-independent words work by calling subroutine vectors...

CMDVE  EQU 240                 command, >IDE code
STAVE EQU 241 status, <IDE code
W1KVE EQU 242 W-1K code
R1KVE EQU 243 R-1K code
SEEKV EQU 244 seek vector, sets seek adr to 246,247
BOOTV EQU 245 boot vector, seek or manually set first

...that connect to the actual driver code, passing variables...

BLKAL  EQU 246                 block address low
BLKAH EQU 247 block address high
DRVNM EQU 250 drive number

For example, look at the code for SBLA...

; Set Block Address
; high low SBLA as in 0 10 SBLA LDFB

This code pops the stack to zp location BLKAL (246) and BLKAH (247) then calls the SEEKV vector (244) as a subroutine. High level disk software can seek to a specific 1K block by pushing the high and low block address then using SBLA, independent of the drive and how many words are really in each sector. R-1K, W-1K and LDFB work the same way. Machine-coded disk software can simply poke the zp variables and call... to seek to block 65538 decimal put 2 in BLKAL, 1 in BLKAH and JSB SEEKV,I.

The disk driver must write the driver subroutine addresses to locations 240-245 octal when it initializes, typically as a startup word. If there's anything else needed to make the drive "go" it should be done here. If slot patching via software is desired then all locations containing IO instructions or constants need to be patched. Alternatively the driver can be written to run in one slot only, edit and reload to change the slot number.

A Discussion of the IDE Driver IPL Code

The formatted text is code from ide.ipl, generally the text describes code appearing above it. I chose the IDE driver to discuss for simplicity, the IDE command set is so simple it's almost a shell that could be used to create other drivers. Browse through 7900.ipl for a more complex example.

; !IDE   Initialize IDE interface  1/10/04 5/4/04 9/1/04
"Setting default IDE slot to 23" $PRINT CRLF
OCTAL 274 23 PUT

Since this is self-patching code, the desired slot address needs to be written to a zp location reserved for specifying the ide slot. See config.ipl for the locations that are currently defined. Note that MT and GPIB may never become self-patching and those locations can probably be recycled for other things. An almost-requirement for self-patching code is they have an autostart word that contains all the code that needs patching, not the case with the magtape and GPIB support packages. On the other hand disk drivers tend to be contained in a single CREATE word and fairly easy to make self-patching.

;note! this driver IPL must be loaded AFTER disk.ipl
;easier to swap drivers this way anyway
"Loading ?DRV" $PRINT CRLF
"IDE virtual drive " $PRINT DRV GET PNUM
"offset: " $PRINT
#0 #0 ;push total
DRV GET IFNZ ;if not zero
#1 DRV GET +DO 2 146 DADD +LOOP ;add 2 146 dn times
SWAP PNUM PNUM ;print high low offset

This is not a driver but an IDE-driver-specific word that prints the contents of DRV and the equivalent block address offset. Because DRV is defined in disk.ipl the ide.ipl file has to be loaded after disk.ipl is loaded. If the driver.ipl doesn't refer to anything in disk.ipl (besides the zp equates which are copied) then there's no order requirement. In practice it works better to load disk.ipl before the driver to allow drive-specific words included with the driver to make use of disk.ipl words and the DRV variable.

"Loading !IDE" $PRINT CRLF     ;note autostarting for default
;caution... rename !IDE to IDE if IDE drive not present or it hangs

This begins the real driver. The driver word is named !IDE to make it run whenever hpiplos starts. The driver no longer hangs because the init was taken out but if the drive requires resetting or other initialization then it might/will hang if the drive isn't connected. To work around this put 177777 in the switch register to prevent hpiplos from running autostart words, then rename !DRIVER to DRIVER to keep it from running. This is also how multiple drive types can be supported on one system, make one the default, say IDE then rename the !7900 driver to 7900, execute 7900 to use the 7900 drive, reboot or !IDE to use the IDE drive. Note that the drive-specific ?DRV words collide in this example, we didn't design the system to have multiple disk drivers loaded but should the need arise it's possible, all in the name.

All autostart words run at startup so as long as a driver doesn't hang because of init of unconnected hardware, specific drive support can be enabled by just loading the driver ipl and rebooting or running the !driver word.

The first instruction JMP IDEEN jumps around the internal variables...

* slot assignment... (when assembled anyway)
IDE EQU 23 configured for IDE interface in slot 23
* zero page vectors....
CMDVE EQU 240 command, >IDE code
STAVE EQU 241 status, <IDE code
W1KVE EQU 242 W-1K code
R1KVE EQU 243 R-1K code
SEEKV EQU 244 seek vector, sets seek adr to 246,247
BOOTV EQU 245 boot vector, seek or manually set first
BLKAL EQU 246 block address low
BLKAH EQU 247 block address high
DRVNM EQU 250 drive number
* virtual disk size
* possibly temporary implementation pending firmware changes
* set to 131174 blocks per drive
* Do Not SBLA to this block or higher or you'll be on the next drive.
VDSHI OCT 2 putting up front for easy changing
* patch slot number...
ISLOA EQU 274 location containing slot number

The IDE interface is EQU defined to slot 23, because this code is self-patching it doesn't really matter but for non-patching drivers this would be the slot number. Next is the zp equates copied from disk.ipl that define the low-level interface. Next is a pair of variables used to offset the real block address for simulating multiple drives. For some reason this feature is not working... finally is an EQU defining the zp location chosen to hold the self-patching slot number.

IDEEN  LDA IDEPL               get patch list address
LDB ISLOA get slot address
JSB PSUBA,I call patch sub

PSUBA is a standard CREATE built-in EQU that holds the address of HP-IPL/OS' patch subroutine. The A register is loaded with the address of a patch list consisting of a list of addresses to modify ending with 0, B is loaded with the desired slot number, then JSB PSUBA,I to patch the code.

* set vectors to IDE subs...
LDA ACMD get address of command code
STA CMDVE save in command vector
LDA ASTA status
LDA AW1K write 1K
LDA AR1K read 1K
* not resetting to avoid problems if drive not present
* LDA RESDR get reset command
* JSB CMD send it
JMP END back to hpiplos with vectors set

This code gets the address of each driver subroutine and pokes into the zero page vectors reserved for disk operations. The reset code has been commented out to prevent hanging if an IDE interface is not installed. After setting the code vectors JMP END returns to HP-IPL/OS with the driver "connected".

* patch list...

This is a DEF list of all the locations that will be slot-patched.

* Send IDE Command from A...
CMD NOP these are subroutines
JMP *-1
* Get Status into A...

This is the code connected to the command and status vectors, ACMD holds the address of the CMD subroutine and is put in CMDVE (location 240) so anything doing JSB CMDVE,I will run the CMD subroutine. Labels are placed at each IO instruction to use in the patch list.

* Write 1 word from A...
JMP *-1
* Read 1 word into A...
JMP *-1

These are IDE-specific subroutines used by W1K and R1K below.

* Write 1K words from address in A...
AW1K DEF *+1
STA ADDR save address
STA WCNT init counter
LDA W1BLK get command to write 1 block
JSB CMDVE,I send IDE command
W1KL LDA ADDR,I get one word
JSB W1W write one word
ISZ ADDR bump address
ISZ WCNT bump counter
JMP W1KL loop until counter = 0
JMP W1K,I exit sub
* new constants...
W1BLK OCT 111001 ide command to write one block
R1BLK OCT 110001 ide command to read one block
RESDR OCT 100000 ide command to reset drive
ADDR OCT 0 Address
1KLEN OCT -2000 Complement of length
WCNT OCT 0 counter
* Read 1K words into address in A...
AR1K DEF *+1
STA ADDR save address
STA WCNT init counter
LDA R1BLK get command to read 1 block
JSB CMDVE,I call IDE command
R1KL JSB R1W read one word
STA ADDR,I save it
ISZ ADDR inc addr
ISZ WCNT inc counter
JMP R1KL loop until done

The above code implements the R-1K and W-1K functions for the IDE interface. These are calling the CMDVE vector to perform their functions but that's IDE-specific, the 7900 driver has read/write code here.

* seek
* this avoids complicated 101xxx >IDE etc commands, instead set
* BLKAL(246) to block low, BLKAH(247) to block high, and call SEEKV
* implementation of virtual drives
* if drive 0 uses raw blkal/blkah
* otherwise d-adds vdshi/vdslo drvnm times
JMP SEEK1 no change if drive 0
STA 1 save -drive in B for counter
STA TBALO 32-bit add
ISZ 1 done?
JMP DNMLP no, keep looping
AND C377
AND C1774
AND C377
AND C1774
C377 OCT 000377
C1774 OCT 177400
SB1 OCT 101000
SB2 OCT 102000
SB3 OCT 103000
SB4 OCT 104000

Above is the IDE seek code with support for virtual drives.

* boot
* can be called as a sub, but never returns
* note! seek must already be set!
* good idea to -IRQ etc before calling

This code copies the machine code below to 77700 and executes it, the machine code loads 31 (decimal) blocks from the current block address then starts it running from location 2. Depending on the drive the code can be adapted from an existing bootrom, but more likely needs to be written from scratch, see 7900ldr.hpa for the code used in the 7900 drivers.

* modified 5/2/04 for LDFB
* ORG 77700B
OCT 170001 STA 1,I
OCT 006004 INB
IPL11 OCT 102623 OTA 23B
IPL12 OCT 103723 STC 23B,C
IPL13 OCT 102323 SFS 23B
OCT 027716 JMP *-1
IPL14 OCT 103723 STC 23B,C
IPL15 OCT 102323 SFS 23B
OCT 027723 JMP *-1
IPL16 OCT 102523 LIA 23B
OCT 000000 LCNT OCT 0
OCT 110037 RDBW OCT 110037
OCT 000002 ADDR OCT 000002
OCT 102000 TCNT OCT 102000
* last addr 77732
DEST OCT 77700

This is really "system file loading" rather than booting. A true boot for IDE would load from block 8 decimal, a true boot for 7900 would load the bootext in blocks 0-5 and start it running to load in the rest of the system. System-specific booters etc can be included in the driver ipl file if desired but unless a foreign system is being booted it's faster to -IRQ 0 10 SBLA LDFB (or just DBOOT) rather than go through the whole boot process. Even though this isn't true booting it loads and runs a system binary as if it were booted, so "boot" got used in the names.

Creating the LDFB/BOOTC code is one of the harder aspects about writing a disk driver. The code has to be stand-alone and assembled to run in high memory, then encoded as octal so it can be included in a normal CREATE word that relocates the code to its original assembled location. The LDFB word (that runs the BOOTC code) is supposed to load the system binary from the current block set by SBLA. For drives with separate seek operations like the IDE interface, it was a matter of simply removing the seek commands from existing boot code. For many drives however (like the 7900) the SBLA/seek code doesn't send anything to the drive but rather sets internal variables so that the next operation can perform the seek. For example, the 7900 driver's SBLA/seek code sets an internal var BLADR to the contents of BLKAL which was set by SBLA. The 7900 LDFB/boot code copies the internal BLADR var to BLKAL in zp (in case it changed, just to be strictly compatible with how the IDE interface operates... you'd probably be just as good to use BLKAL/BLKAH directly), then when the hi-mem code in the octals runs it seeks to the block in BLKAL first before loading and running the system binary. The 7900 driver ignores BLKAH since it's a small drive, drives over 128 megabytes need to use BLKAL/BLKAH and use 32-bit math for computations. Then there's the drive number to support, it's in location 250 (argh.. just noticed a bug in the comments of 7900.ipl - I called BLKAL loc 250 but it's 246 - not fixed). For the 7900 I use DRVNM 0-3 to reference the removeable platters of drive numbers 0-3, and DRVNUM 4-7 to refer to the fixed platters.

Nothing in HP-IPL/OS can assemble code directly to high memory (at least not without  serious hacking to subvert the system), practically the LDFB/BOOTC hi-mem code needs to be written and assembled using HPASM. The code can be tested by doing a DGEN to make sure there's a bootable image present in blocks 10-46 (octal), do 0 10 SBLA (or poke BLKAL location 246 octal with 10 octal if your code reads loc 246 for seek) then run the hi-mem code directly with -IRQ 77700 RUN (or wherever your code is assembled to run from, keep it somewhere above 77500 or so to avoid conflicting with other things like the exit code typically placed at 77000). Once the code works and can load/run a system binary then it can be converted to octal and included in the driver along with relocation code and anything needed to tell it where to load from. The octal can come straight from the HPASM listing, or created with the mkcldr.ipl utility which encodes any area of memory to octal along with code that copies it back to its original location.

;--- end of IDE core driver code

That's it. END stops CREATE, CONSOLE restores the prompt.

A quick way to test a new disk driver is do DGEN to write a system binary, add/subtract stuff to detect the change, then DLOAD to boot the system saved by DGEN, should return to the DGEN'd system. If  the driver supports multiple drives you should be able to n CHDRV to DGEN to drive n, n CHDRV DBOOT should load different systems saved to different drives.

Created 5/1/05, Last Modified 8/30/08