
Documentation for HyperBoot - Version 2.20 - 06 Jan 99
Copyright (c) 1998,99 by Pete Cervasio (cervasio@airmail.net)


INTRODUCTION:
=============

You're holding in your hands one of the most exciting and new pieces of
software for your TRS-80 Model 4 (and indirectly for the Model I and III).
Well, maybe it's not quite so exciting.  It =is= rather new, however, since
I still have to give it one more pass through the MRAS assembler and another
test run before I zip all this stuff up and put it on my web page.

What is it?  Read on and find out!  HBFORM and HBCREATE are the two programs
described here, and you'll be shocked and amazed (okay, maybe more shocked
than amazed... or more likely just shocked) when you find out what they are
and what they can do to make your TRS-80 a more powerful, and trustworthy
friend to have around your home (or office, or whatever).

I have tried not to write something dull and boring in the way of software
documentation, but there are a couple of boring parts that managed to slip
in.  You'll be warned before they show up.


OVERVIEW (and some of that stupid LEGAL JUNK):
==============================================

This isn't supposed to be one of those boring sections, so keep on reading.

HBFORM?  HBCREATE?  Just what is this HyperBoot you're going on about, Pete?
Why is this such a cool program, and why would anyone in their right mind
want to ever use it??  Well.. to let the cat out of the bag (he howls too
much when he's in there).. these are utilities to create self-booting Super
Utility Plus 3.2 disks from the freely available /CMD versions.  What!?!?
Can that be true?  Of course it is!

These self booting disks will work on both the Model I and the Model III/4.
In addition, the /CMD files are patched (in memory) before writing them to
disk to re-enable the logo screen flashing and configuration/patch sector
reads at boot up, as well as allowing the SU+ configuration to be saved to
disk.

The programs, HBFORM and HBCREATE, are copyright 1998,'99 by Pete Cervasio
and may be freely distributed and/or modified, as long as my copyright
notice is neither removed nor modified, either from the programs, the source
code, or the documentation.  You are also forbidden to otherwise represent
this is as your own work (unless you really do make modifications, in which
case you can say that part of it is your work).  Deleting my copyrights
doesn't count, though, even though it technically *is* a modification.  You
know what I mean, you're all intelligent (you're using TRS-80s, aren't you?)

If you make modifications to these programs such as porting them to either
the Model I or Model III (hint, hint, nudge, nudge), please send those
changes back to me at the email address above, so they can be merged back
into the "official" release.

I'm not charging anything for anyone to use this and you shouldn't either,
but you're allowed to if you can actually get people to give you money for
it.  If you do, please email me and let me know, so we can have a good laugh
together.  Disk creation and handling fees don't count, if you want to make
copies for people that can't move the files to a TRS-80 themselves, since
nobody expects you to give away time, disks, mailers or postage.  Well, I
don't expect that, at least.

If you do decide to distribute this on disk to people, be prepared to rack
up ones of sales per decade.  You're required to supply all the files, as
listed below.  You must also grant all the same rights as you have been
granted, as well as the same responsibilities.  You must also let the
purchaser know where the latest version of this package may be downloaded
for free.  Just supplying the files in the .ZIP file you received should
satisfy all the requirements.

This software is currently available for free (other than whatever 'net
connection charges you normally have to pay) download at the author's web
page at http://web2.airmail.net/cervasio/software/ and the author is willing
to make it available on 5.25" (180k) or 3.5" (720k) TRSDOS 6.x compatible
floppy disks, for those people who can't transfer it from their internet
capable machine to a real Model 4 for whatever reason.  Contact me via email
for particulars, but it's basically going to cost you $7.00 (for my time,
the disk, a mailer and postage, none of which comes free).  I'll throw in
copies of SU1/CMD and SU3/CMD, while I'm at it, so you're sure to have
those, too.  In addition, I'll print a fancy-schmancy disk label for it so
you KNOW you're getting your moneys worth.


DISTRIBUTION FILES:
===================

This section isn't supposed to be boring, either, but it probably is.

The following files comprise the HyperBoot package, and must be included in
any distribution of HyperBoot, except as noted below:

HBFORM/ASM   - Assembly language source for the formatter.

HBCREATE/ASM - Assembly language source for the program which writes the
               /CMD files to the disks.

HBFORM/CMD   - Executable disk formatter for Model 4 TRSDOS/LSDOS 6.x.

HBCREATE/CMD - Executable disk writer for Model 4 TRSDOS/LS-DOS 6.x.

HYPBOOT/TXT  - The file you're reading right now.

SVCMAC/ASM   - Model 4 SVC macros.  This is actually from the LS-DOS source
               code package, and you can leave it out if you feel you have
               to.  It's avalailable on Tim Mann's site (see below) in the
               LS-DOS source.


HISTORY and HOW IT WORKS: 
=========================

(or "How I spent my Thanksgiving and  Christmas vacations")

This is rather long and boring, and you should skip down to the next section
titled "IMPORTANT NOTE" if you don't want to be put right to sleep.  I want
to document this for posterity, because in 20 years I'll be an old-timer
(well, 59 won't be that old, really) and =already= I can't remember stuff.
The TRS-80 will have re-taken over the world by then (I give it another 359
days before that starts - this is January 6th, 1999 as I write this) and I
just know that someone will ask "How and why did you write such a cool and
wonderful program?"  Hey, it could happen.  :)

These utilities came about as a result of one of those sudden flashes of
thought.  I had scanned and OCR'd the Super Utility manuals for Tim Mann's
TRS-80 web page, and was messing around with Mike Gingold's HyperZap, trying
to get my real SU4/4P disk backed up using it.  I'd made a backup before
using a CopyIIPC Option Board (what a cool piece of hardware) on an XT a few
years ago, and was just basically "compubating" --- sitting alone in a
darkened room stroking a keyboard for personal gratification.

Anyway, it hit me that HyperZap makes self-booting disks that work on both
the Model I and III, and the source code for its two boot sectors was
sitting right there in the back of the manual.  It also occurred to me that
I had a perfectly good SU4 backup, so why was I messing with what I was
doing... The *real* problem was I wanted a self-booting SU3 disk that could
be copied easily with HyperZap instead of having to load up its "autopilot"
routine.  To make a long story longer, somehow all this info clicked into
place, and "HyperBoot" was born.

"HyperBoot" is the name I've decided to use for programs that use this
highly modified version of HyperZap's very fast dual machine, dual density
loader. The original HyperZap boot code was just a single sector.  It is a
simple little piece of code that quickly (very quickly) loads a bunch of
tracks from disk to memory in one swell foop and jumps to a start address.

HyperZap (the self booting disk version) even has a "make self-booting disk"
option on the main menu, which uses this boot sector and a program you load
into memory to create a fast self-booting copy of that program.

Unfortunately, it requires much smaller programs than Super Utility Plus.
So... I went ahead and wrote a nice small program as a test, and made a
HyperZap self-booting disk out of it.  I then verified that it worked on
both the Model I and Model III.  (Basically, it just cleared the screen,
wrote a "Hello world" message, and hung in a loop.  Once I knew that was
working, I set out to turn that disk into a SU+ disk.  I formatted the rest
of the tracks the way they should be, and then used Super Utility to pain-
stakingly move the sectors (from "core image" files I created out of the
Model I and III SU+ /CMD files) onto the soon-to-be self booting SU+ disk.

To say that this took some time is an understatement.  HyperZap's boot
process expects sectors numbered from six down to one, in order, on each
track.  Both the single *and* the double density sectors use the same sector
ID numbers, which makes the boot code easy, but makes doing something like
moving a 30K+ program from one disk to another one sector at a time...
well... a nightmare!

To save my sanity (what's left), I wrote a short program to reverse the
sector order of the /CIM files every six sectors.  This let me tell SU+ to
copy six sectors at a time, which cut down both the time it took and the
number of mistakes I made.  When it was all on the disk the way it should
be, I modified the single and double density boot sectors to have the
correct track counts and transfer addresses and tried it out... and it
worked!  On both machines, even.

I found the locations to patch to allow the loading and saving of the SU+
configuration data, added the rest of the single density sectors to track
zero (HyperZap just writes a single-density sector 0 and a double-density
sector 1) and went on to try that part out... it *almost* worked.

It seems that whatever track is listed in the boot sector as the DIR track
gets wiped out when SU+ writes its configuration data out to disk.  The boot
sector I was using had a 01 (or was it 06?) byte in that position... which
means one of the program tracks got wiped out and the disk wouldn't boot
again!  That was definitely a bad move.  I modified the boot sector code I
was using to have a normal 00 FE 03 byte sequence at the beginning, and to
start loading the program starting at track 4 of the disk.  This worked much
better, but I had to go through the process of moving the sectors over from
my core image files to the specially formatted disk again.

As I said, doing this manually was a real pain, and I wanted something that
was a little easier.  Actually, I wanted something a *LOT* easier.  Writing
HBCREATE took a day of coding and one of testing, and in the end I had a
nifty little program that would write SU1/CMD, SU3/CMD, and the boot sector
onto a specially formatted dual-density disk.  Formatting the disks with
HyperZap wasn't really that big of a pain in the behind, but it did take a
number of steps.

Since I planned on sharing my bit of code with the whole TRS-80 world (or
those who are interested, anyway) it also required people to have HyperZap,
and follow explicit instructions on formatting the disk.  I had a HyperZap
"autopilot" done by this time, but that was only usable by the self-booting
HyperZap, which isn't available on the 'net.  You can't really represent it
with any of the emulator .DSK formats other than the extensions used by
Tim Mann's work on xtrs.

An additional downside was that SU+'s "Special Format" option didn't seem to
make disks in quite the proper format, so I decided that a disk formatter
was in order.  Around this time, Kim Watt sent Tim Mann all his old TRS-80
stuff (which is still being gone through at this writing) and Tim sent me
the source for Super Utility 3.1a.  Included in that was the program that
Kim wrote to create the copy protected SU+ disks!  I made two (just playing
around) but I didn't want to create *copy protected* disks.  I wanted quick
booting ones that are easy to copy (or make).  So... I took a few parts of
that program, some small parts of LS-DOS's FORMAT utility, and other parts
of the LS-DOS floppy disk driver (from SYS0) and chopped them all up,
sprinkled them over the top of a bunch of code I wrote myself, and put
together a program that would format disks just the way I wanted them.

I now had a program that would format disks, and another that would write
the command files to them.  Woo hoo!

In the course of going through Kim's SUCOPY source code, another one of
those moments hit me.  SU+ works on either 40 or 80 track drives.  It also
has a memory test to make sure that SU isn't going to load into bad memory
(and that it's a 48k machine!)  I wanted my HyperBoot disks to be just as
cool, so it was time to re-write HBCREATE so it writes out 80 and 40 track
loaders into tracks 1 and 2 respectively, along with the logo screen shot
appropriate for the machine.  Since the boot sector loads up six sectors at
a time, I had four sectors reserved for the screen, and two sectors (512
bytes) to play with. This was much more than enough.  The boot sector of the
disk could be simplified to just step the drive head twice, load in the six
sectors it finds, and jump to the loader routine it just grabbed.

Quick theory time: An 80 track 5-1/4 inch drive, when on track 0 and stepped
twice, will wind up on what a 40 track drive would call track 1.  A 40 track
drive will (of course) wind up on track 2.

This winds up being perfect for HyperBoot's purposes.  Track 1 gets written
with the screen image and a loader which steps the drive twice for each
track, while track 2 gets the same thing with the extra calls to the step-in
routine replaced with NOP bytes (for the non-assembly literate, the GOSUB is
remarked out).  Track 3 winds up getting ignored (since SU+ is going to wipe
it the first time the config data is saved) and the actual SU+ program gets
loaded starting from track 4.

I'm not as proud of the loaders as I probably could be, since the code is a
little messy.  It works, though, and that was my main objective.  The memory
test is straight out of the SU+ loader, and basically is a test to make sure
that nothing blatant is wrong (like not having a full 48k of RAM in the E/I).
It's not anything like the memory test that's on the SU+ menu.

That's it.  The whole history of HyperBoot.  I can tell you're impressed by
that glazed look of awe in your eyes.  Hey.... wait a second!  That's not a
glazed look of awe!  It's a glazed look of.... WAKE UP!  I told you to skip
this, so it's your own fault.


IMPORTANT NOTE:
===============

At the current time, Model I and III /CMD versions of the HyperBoot format
and disk writing utilities do not exist, although a minor bit of what would
be required has been stubbed in.  A very minor bit.  I probably shouldn't
have even mentioned it, it's so small.  Forget it, it's not even started.

HBFORM would be the easiest of the two to port to the Model III, since the
non-maskable interrupt (used to tell when the whole track has been written)
works the same way as the Model 4.  The Model I would be a beast of an
entirely different color.  I've never really tried doing my own formatting
on the Model I, even after all these years,

It would probably be a royal pain to try to port HBCREATE to either of the
LDOS 5 machines, since the way it works right now is to just load the /CMD
files into memory where they would load in a I/III if you ran them from the
LDOS command line.  The HBCREATE program itself ends before 3C00H, which is
where the Model I/III screens get loaded, and the 40/80 track loader routine
is set up to load (in HBCREATE) at 4000H, right above the last byte of the
screen.  When the actual SU/HB disk is booted, the screen and loaders get
put at 4C00H through 51FFH, and the screen is block moved down to the 3C00H
address.

Some other scheme would be needed to make a Model I/III version, since the
operating system and the real screen hang out in the 3C00h to 51FFh range,
and the program part of SU?/CMD loads right after that at 5200h.  ORGing it
way up at E900h might be an option, if you want to try.  That's the first
free page of memory after the larger of the two SU cmd files.  It doesn't
leave much room if you have stuff in high memory, though.


HBFORM OPERATION:
=================

HBFORM is pure simplicity to operate.  Enter the command name at the LS-DOS
prompt.  It will show you a sign-on message and ask you for the logical
drive number that you want to format.

Enter the logical drive number that you wish to format a HyperBoot disk on,
and press ENTER.  If you press BREAK, the program will exit.  After the
drive # is entered, a check is made to make sure you haven't specified a
hard disk partition, as well as performing a few other sanity checks on the
DCT (like, is that an enabled drive?, etc.)

The program will then prompt you to mount a diskette in the drive and press
ENTER to continue.  The disk will then be formatted and verified. Finally,
you will be asked if you want to format another one.  Answer "Y" or "N", as
desired.


HBCREATE OPERATION:
===================

To run HBCREATE, you need a diskette that was formatted with HBFORM.  You
also need the SU1/CMD and SU3/CMD files that are available from Tim Mann's
web page (see the end of this document).  It is suggested that you either
create a minimum system disk to hold both of the SU+ CMD files and the
HBFORM and HBCREATE programs, or run it from a hard disk if you have one
(which is what I do here).

When you start HBCREATE, the first thing it does is say hello and start
loading SU1/CMD into memory, so SU1 needs to be available right away.  It
then applies the patches in memory to allow config load/save and prompts you
for the drive to write the Model I SU+ to.  Switch disks, if you need to, to
make the HBFORMatted disk available, and enter the logical drive number that
it's on.  You can specify drive 0, since there are prompts to change disks
at the appropriate times.

The disk will then be written with the single density sectors, and when that
is complete, you will be prompted to replace the disk (in case you need to).
If you *do* need to, go ahead and do that, so the program will be able to
load SU3/CMD into memory next.  You'll be prompted to put the diskette back
in after that so the double density sectors can be written, which is what
happens after SU3/CMD is loaded and patched in memory.

Finally, you'll be told that the program is done, the disk is made, and that
you should test boot it on a Model I and a Model III/4.  That's IT.  You've
successfully created a self-booting Super Utility Plus 3.2 disk that works
on both the Model I and Models III/4.  When you go to the config screen, it
will ask if you want to save your configuration, and when you reboot, it'll
have that configuration all set up, not totally unlike the manner in which a
real SU+ disk would behave.

If you need to copy the disk, you can either use HyperZap (which will
preserve the order of the sectors on the disk) or Super Utility's Special
Backup (which won't - and the resulting copy will boot a bit slower).  The
best bet is just to HBFORMat another disk and use the HBCREATE program
again.


FUTURE PLANS:
=============

Future plans for these utilities include allowing the filenames for the SU1
and SU3 command files to be specified on the command line, as well as the
drive to format.  Right now the files are hard coded as SU1/CMD and SU3/CMD.

I also plan on changing the sector order so that it goes from 1 to 6, more
like a regular disk does.  It will require changing a two byte test/loop
instruction into a several bytes, but the extra time that takes shouldn't
make a difference to the boot speed.  That change might make SU+'s Special
Backup much happier, and disks copied with it boot as fast.  (Alas, I have
done that... while the disks copied with Special Backup are faster than
before, they're still slower than original HyperBoot disks.)

Since the HyperBoot utilities only run on a Model 4 (though it creates Model
I/III disks) there's no reason to have it create single density only disks,
although that might be useful if/when the programs are ported to the Model
I.

Porting the programs to the Model I/III is also planned, but if that ever
happens it might be sometime in the next millenium.  The source is there, so
you can bypass my timetable if you need/want to.

WEB PAGES:
==========

Web pages - either mentioned in this document or just cool places to visit:

Pete Cervasio's home page (okay, maybe not so cool):
http://web2.airmail.net/cervasio/

Pete's TRS-80 software (but this one is):
http://web2.airmail.net/cervasio/software/

The TRS-80 Home Page (this one is not bad):
http://www.kjsl.com/trs80/

Tim Mann's TRS-80 page (this one's definitely cool):
http://www.research.digital.com/SRC/personal/Tim_Mann/trs80.html


CONCLUSION:
===========

I hope you find these utilities useful.  They have been fun to play with.

Pete C.




