YA-DOS


YA-DOS is a branch of HDBDOS for the CoCo2 and CoCo3.  Original
HDBDOS is a 8K ROM.  YA-DOS is a 16K ROM.  Although based internally
on the HDBDOS code, much of the functionality has been changed and
appended to. 

* Modularized, multiple simultaneous drivers.
* MPI support
* Real Drive Partitioning
* Extended BASIC support of DriveWire4 and SDC commands.
* Compatible with HDBDOS/RGBDOS partitions / applications

yados


README.TXT:


**************************
 Introduction
**************************

YA-DOS is a branch of HDBDOS for the CoCo2 and CoCo3.  Original
HDBDOS is a 8K ROM.  YA-DOS is a 16K ROM.  Although based internally
on the HDBDOS code, much of the functionality has been changed and
appended to.  The drivers have been fully modularized and a new
device/drive switcher has been added to allow the simultaneous use of
many different devices and or drivers.  Where HDBDOS only allowed
relatively static setup of a single device plus a stock FDC at a time,
YA-DOS allows for the the dynamic setup of devices. To this end,
YA-DOS supports the use of a Multi Pak Interface (MPI) inherently,
and other than initial setup, little is required to use devices on
different MPI slots.

Another great feature of YA-DOS is the support of a Drive Partition
Table.  Drive partition tables have been used to great advantage in
many other systems, and until now have been unsupported by the Color
Computer's main operating systems, BASIC, OS-9, and Nitros9.
Partition tables not only allow cross-OS cooperation of the use of
large media, they also provide for larger use of the media, and take
the burden of setup off the user.  Where as HDBDOS was generally
restricted to a single, ROM based drive offset, YA-DOS supports
on-the-fly setting and multiple partitions in use (14 per device, 4 in
simultaneous use).  Removable media of different sorts (SD,CF,DW)
becomes much easier to use as the media itself contains it's own
partition table.

YA-DOS also provides for better integration of BASIC and Drive Wire4's
(DW) and CoCoSDC (SDC) user interface.  New BASIC commands have been
added to allow for control of disk images.  The insertion and mounting
of disk images in DW and SDC can now be fully automated with YA-DOS
at boot.  DriveWire's advanced controls over server logs, MIDI
channels, is now at least partially supported.


**************************
 Technicals
**************************

The DSKCON interface is switched throughout different resident drivers
through the standard BASIC DSKCON's variable DCDRV.  Normal DECB uses
DCDRV as a direct index of the Drive Number.  YA-DOS now used this as
a index to a table of mounted drives.  DCDRV serves as a table index
to two parallel tables: the FAT Table, and the Mount Table.  The
traditional use of the FAT table is left unchanged... a cache of each
mounts FAT table.  The Mount table is a table of entries describing
each mounted file system (a mount).  There are 4 mount and fat entries.
This limits us to the use of 4 mounted file systems at one time.


THE MOUNT TABLE


Each Mount Table entry contains the following data:

* Logical Device Index (DEV)
* The Major number of the device (MJR)
* The Minor number of the device (MIN)
* The Subpartition of the device (SUB)
* The Drive Offset (OFF)

The Device (DEV) is a index to a table of configured Devices.  It is
essentially a reference to a table of Devices.  In-turn, each Device
has an associated Driver (DRV).  There can be up to 6 devices in the
system at any one time. 

The Major Number (MJR) is the mount's traditional device or drive number.
FDC support 4 devices, The SDC driver 4, Drivewire supports 256
devices, and IDE 2. 

The Minor Number (MIN) is the mount's partition number.  If the device
mounted has a valid partition table, the mount's offset (OFF) is
automatically set.  The partition number can be set to anything from 0
to 13 - The number of partitions supported by CCPT, the author's
partitioning format.

Yet another metric can be set for large media, the Subpartition
number.  This takes the place of traditional HDBDOS's idea of a "drive
no" as known by HDBDOS.  There can be up to 256 sub-partitions on each
of the 4 mounts.  See BASIC command "DRIVE ." below.

The last mount metric is the Drive Offset.  This is simply the logical
Sector Number (LSN) that the file system starts on.  It is
automatically set by the Minor Number (MIN) at mount, or can be set
manually with the "DRIVE O" command.


THE DEVICE TABLE

The Device Table, as referred to above, is a table of six devices that
are setup up for the machine at boot time.  Unfortunately because of
the time, complexity, and peculiarity of Color Computer devices, only
one common device will be searched for in the default MPI slot at
boot.  The other devices in your system can be setup in the
AUTOEXEC.BAS BASIC program.  The purpose of the device table is to
store the not-so-dynamic information; This is done with the intent to
make it slightly easier to mount file systems by not having to tell
YA-DOS the Hardware Address (ADD), MPI slot setting (MPI), and extra
parameters (MSC) every time you mount or change a device.  Notice
that these parameters would rarely change, and once set, will likely
stay set for many boots.

Each Device has an associated Driver No. (DRV).  This is an index to
one of 8 drivers.  Each driver can be reused by different devices,
allowing one to have several SDC's or IDE controller in use at the same
time.

Device's also have a Multi Pak Interface setting (MPI).  This tells
YA-DOS which slot this device sits in.  IF you do not have an MPI,
simply leave this as "0".  NOTE:  YA-DOS number MPI slot from 0 to 3,
*not* 1 - 4 as they are physically numbered.

The Hardware Address (ADD) setting allows you to specify a specific
hardware address to use for this device. See the individual Driver
docs for specific instructions for the use of this field.  This field
is only 8 bits in length, and it is assumed that the upper 8 bit of
the address is &HFF.  Example: If your IDE is dip-switched for
address &HFF70, set this value as &H70.

And finally, the Miscellaneous (MSC) field, lets you specify driver
specific options.  A FDC driver, for instance, my use this datum to
decide if it should access its disks as a 35 track or a 40 track
drive.  As this parameter is driver specific please refer to the
documentation for each driver.

Each device has a 8 bit miscellaneous field, used for driver specific
settings.  Please consult the specific Driver's documentation for use.


THE DRIVERS

As of the writing of this document up to 8 drivers are supported.  Not
all are implemented:

Driver No. 0   DriveWire3 over RS232 PAK
   This Driver runs drivewire over a standard RS232PAK at 115,200,
   or external clock, at stock base address: $ff68.

Driver No. 1  DriveWire3 over Bitbanger
   This driver is the "regular" speed/timing.  This driver supports
   device Major numbers 0-255. There are four <MSC> field settings that
   will control the operation of this driver:
       0 - Regular Speed (57k or 115k)
        1 - Only slow speed (57k), even on CoCo3
        2 - Turbo Mode (115k or 230k)
    3 - CoCo1 Mode (38k)

Driver No. 2  DriveWire3 over Becker Port
   This driver is similar to the regular DW driver, however it is
   designed to use the magical "becker" port for emulators.  There are
   two <MSC> field settings that control the operation of this driver:
    0 - Regular Speed (fast for CoCo3)
        1 - Always Slow Speed (slow for CoCo3)

Driver No. 3  CoCoSDC
   This driver uses the CoCoSDC's extended LBA mode interface to
   access large volumes.  It is NOT a FDC driver, however.  It
   supports device major number 0 and 1.

Driver No. 4  Glenside IDE (SuperIDE) LBA MODE
   This driver accesses a Glenside style IDE controler or SuperIDE
   controler in Large Block Address (LBA) mode only.  Nearly all IDE
   drives since the early 90's support this mode.  If a CHS driver is
   needed, please contact the author.  This driver defaults to a port
   address of 0xFF50, unless a non-zero address is specified in the
   device's <ADR> field.  

Driver No. 5 SD Card for CoCo3FPGA
   This is an experimental driver for Gary Becker's CoCo3FPGA Project.
   This driver is (mostly) his doing.  It supports only 1 logical
   drive, number 0.

Driver No. 6 EmuDsk
   This drive is designed to work with Vcc and MESS's "VHD" or Virtual
   Hard Disk (Drive?) system.  This driver support a work-around of
   this "hardware's" 8k boundary problem. 

Driver No. 7 FDC (DS DD 35T 18S)
   This is a "wrapper driver" to the traditional DECB driver.  It
   supports only the traditional disk geometry at this time. It is
   has four Major's:
      0 - front side of disk drive 0
      1 - front side of disk drive 1
      2 - back side of disk drive 0
      3 - back side of disk drive 1
   Because the CoCoSDC looks identical to a FDC, one may use this
   driver to access small drives in addition to Driver No. 2.

Driver No. 8-13
   These driver number are unassigned at the time of the writing of
   this document
   
Drivers No. 14 and 15 User Loadable Drivers
   These two driver numbers are reserved for user loadable drivers.
   It it possible to write a driver that implements YA-DOS's driver
   interface and load it via a "LOADM" or "RUNM" statement.

**************************
 New Drive Sub-Commands
**************************

DRIVE M<F> LOG, DEV, <MJR>, <MIN>,<SUB>  - Mounts a drive*
DRIVE M                - Prints a list of Mounts
DRIVE U LOG                     - Unmount a drive
DRIVE I DEV, DRV, <MPI>, <ADD>,<MSC>  - Sets Device Table
DRIVE I                         - Prints Device Table
DRIVE O LOG, OFF               - Manually Sets Mount's Offset
DRIVE . SUB              - Change Current Mount's Sub partition
DRIVE , MNR+SUB            - Change mount to linear mapped MNR and SUB
DRIVE D DRV            - Interactive DW UI Console
DRIVE E DRV,"string"        - Sends command string to DW UI Console
DRIVE S DRV,MJR            - Interactive SDC UI Console
DRIVE T DRV,MJR,"string"     - Send command string to SDC UI Console


NOTE:  Parameters delimited with "<..>" are optional.  If they are not
specified, consider them preset to 0.  Don't skip option arguments -
there is no way for the system to parse these.  Example: in "DRIVE M":
you want to specify the subpartition but not the Minor number.  Then
you *must* specify all previous optional args.

* Mounting a drive with the "F" flag, forces YA-DOS to mount a drive
  regardless of any errors encountered.  This is particularly
  important when trying to low-level format (DSKINI) a real floppy or
  an unformated SDK on the SDC.


LOG - Logical Drive / Mount Number to mount.
DEV - Device No.
DRV - Driver No.
MJR - Device Major
MIN - Device Minor (Partition Number)
SUB - Subpartition (Old HDBDOS drive no.)
MPI - MPI slot containing device ( 0 - 3 )
ADD - LSB Hardware Device Address (MSB assumed to be 0XFF)
MSC - Miscellaneous Configuration byte
OFF - 24 bit Partition Offset (Old HDBDOS's HOFFSET )
MSC - Miscellaneous Driver Configuration

Examples:


DRIVE I 0,1    ' Associates device 0 with DriveWire over becker port
DRIVE I 1,2,1  ' Assoc. Device 1 with SDC in MPI slot 1
DRIVE I 2,3,0,&H50  ' Assoc Device 2 with IDE driver in MPI slit 0
                  with address of FF50.

DRIVE M 0,0   ' Mounts device 0 (DW, above) on Mount # 0
DRIVE M 1,2,1  ' Mounts device 2 (IDE, above) on Mount # 1, IDE slave
DRIVE M 2,1,0,3  ' Mounts device 1 (SDC, above) on Mount # 2, drive 0,
                 Partition number 3

DRIVE O 1,&H52ddc  ' sets mount # 1 above to offset 0x52ddc (SuperIDE
standard)


**********************************
 BOOTUP
**********************************

There is a slight delema concerning the dynamicy of YA-DOS: Where do
settings come from?  In short, *you*.  Autodetection is and will be
flakey, at best.  This was true in the PC days before the PCI BUS, and
it definately true with the Color Computer series. On Boot, YA-DOS
scans the keyboard for user startup overrides.  If the operator holds
down <SHIFT> during boot all drivescans are skipped.  If the operator
holds down a number key then that particular driver (see THE DRIVERS,
above) is tried first.  Otherwise, YA-DOS tries to find a valid
driver/drive the boot-up MPI.  Different drivers are tried one at a
time.  Once a driver works, YA-DOS ends the search and proceeds to
mount the first subpartition of the first partition, of the first
major number.  This is analogous to the BASIC pseudo-statements:

DRIVE I  0, 0...4
DRIVE M  0, 0, 0, 0, 0

After the mounting of the boot drive, YA-DOS tries to find and run a
BASIC file called "SYSCONFG.BAS".  The purpose of this file is to
allow you, the user, to specify all your "DRIVE I" and "DRIVE M"
necessary to match your hardware/needs.  In general, you should setup
your device table *before* mounting anything. 

NOTE: Just as in HDBDOS, holding down the left shift key on your
keyboard will tell YA-DOS *not* to auto-detect anything.

NOTE: Nothing precludes you from unmounting the pre-mounted filesystem
and resetting up the driver table, if YA-DOS's autodetection routines
get things wrong.

EXAMPLE SYSCONFG.BAS:

10 DRIVE I 0,0         ' DEVICE 0:  DW OVER BIT-BANGER
20 DRIVE I 1,2,0       ' DEVICE 1:  SDC IN MPI SLOT 0
30 DRIVE I 2,3,1,&H50  ' DEVICE 2:  IDE IN MPI SLOT 1, PORT FF50
40 DRIVE I 3,3,2,&H70  ' DEVICE 3:  IDE IN MPI SLOT 2, PORT FF70
50 DRIVE I 4,4         ' DEVICE 4:  FDC IN MPI SLOT 3
60 ? "DEVICE TABLE CONFIGURED!"
70 DRIVE M 1,2,0,3     ' MOUNT 1:  IDE IN SLOT 1, DRIVE #0, PARITION 3

After running "SYSCONFG.BAS", the traditional "AUTOEXEC.BAS" file is
loaded and ran.


******************************************
  Extended BASIC support of DW and SDC
******************************************

There is a need, at boot-up, to control the mounting and use of SDC
and DriveWire drives.  This is especially true of SDC, as attempting to
mount on an "empty" SDC drive will fail.  YA-DOS allows for two modes
of communicating with your SDC or DW interface. One that is designed
for real-time interactivity, and the other that is designed for
inserting commands into a BASIC program.

DRIVE D <DEV>             - An interactive DW console.
DRIVE E <DEV>,"command"   - send command string to DW console.

DRIVE S <DEV>,<MAJ>             - An interactive SDC console.
DRIVE T <DEV>,<MAJ>,"command"   - send command string to SDC console.


Commands differ from DW to SDC.  See the respective documentation for
each system for help in formatting command.  Note: the string "DW "
will be auto appended to Drivewire commands for the convenience of the
user.

The SDC commands are string formated as follows:

"M:filename"  - mount an image
"N:filename"  - create an image
"D:dirname"   - change directory
"L:dirname"   - print directory
"K:dirname"   - make a directory
"X:name"      - delete a file or directory

The SDC also supports a Rename command (R:), however this command NOT
supported by YA-DOS at this time.

Examples:

DRIVE E 0,"DW INSERT 0 MYBOOT.DSK"  ' INSERTS A DW DISK INTO DRIVE 0
DRIVE T 1,0 "M: MYBOOT.DSK" ' INSERTS A SDC DISK INTO DRIVE 0


NOTE: The "DRIVE S" and "DRIVE D" commands are interactive.  They
offer a simple prompt-do-print-repeat cycle.  These commands can be
"broken" out of and control returned to traditional BASIC at any time
by pressing the "BREAK" key.


*****************************************
  Using BASIC's "DIR"
*****************************************

We have reverted HDBDOS's multi-column display back to a traditional
one column approach, but kept the added informational header and
trailer.  The directory listing is now paused when a page has been
filled, displaying "MORE...".  Pressing "Q" will break out of "DIR",
anyother key will display the next page of files.


*****************************************
  ML Programmer's Notes
*****************************************

YA-DOS supports the DSKCON interface.  This works essentially the same
as prior versions of DECB.  Please note the the RAM variable, "DCDRV"
not refers to the mount number, not the drive number.  Erroneous
opcodes are now caught and a DSKCON call using bad opcodes will
immediately return with DCSTA set.

System variables in RAM above 0x989 have moved!  These include the
start of the file control blocks and random access buffers.  Please
don't load your "BIN" files below 0xE00.

A new system call is available for use.  The system call interface is
designed to allow ML programs to "safely" call more advanced features
of YA-DOS.  These include adding your own drivers, and direct
operations using Logical Sector Numbers (LSN's) rather than
traditional floppy geometry.  For example, the utility FDISK, uses
this interface to query IDE drives for their size and meta-data. The
interface is called in ML as follows:

      .....
      jsr        $d934    <- interface routine
      fcb        $0         <- post-byte routine number
      .....

The interface routine is a pass-through routine, and no registers are
changed during its calling.  The end-routine, however may, and usually
will, change registers to return information to the caller.

No further Documentation is available for this routine (and it's
associated end-routines) at this time.  The system calls are still
changing quite a bit so please see the YA-DOS source or contact the
author for help.

Magic bytes for YA-DOS appear at addresses $d930-$d933.  These bytes
are set to "YADS".  This is included as an aid to the programmer to
detect if the YA-DOS and its extended interface is installed.


CUSTOM DEVICE DRIVERS:

YA-DOS allows a clever ML programmer to add up to two device drivers
to the system, on-the-fly.  These drivers can be installed via a
System Call into the driver table as driver numbers 14 or 15.  The
device driver will register itself and pass a pointer to a OS9 style
jump table to the system.  The user or programmer then may mount
file systems on this device.

table
     lbsr   init    ; initialize driver
         lbsr    setup   ; pre execute driver setup
     lbsr    execmd  ; and execute a command
     lbsr    deinit  ; de-initialize the driver

start     
     ldx    #table  ; get table pointer
     ldb    #12     ; register as driver 12
     jsr    0xd934  ; System call
     fcb    4    ;   call number - register driver

     .....

NOTE:  YA-DOS enables ROM mode on calls to drivers.  Don't expect
Super Extended Basic variable to be in high memory (0xE000 - ?
). Nothing can stop the driver from changing this, or even changing
ROM's via the MPI, however, please put things back before RTS'ing back

NOTE: New flash-able products (CoCoSDC) and Kip Koon's large ROM
banker offer tremendous ROM storage for the Color Computer.  It would
be fairly simple to write a driver to use a bank(s) of ROM as a BASIC
drive. Even a RAM drive is possible.

Where you choose to install your RAM drivers is up to you.  Please
note that any RAM-based driver is succeptable to being overwritten.



***********************************
  FDISK utility
***********************************

There is an included FDISK utility to help you quickly setup and use
partitions on YA-DOS supported drives.  Anyone familiar with MSDOS or
old-time Linux users will remember their version of "fdisk".  This
utility is modeled after this classic utility.  Be warned: this FDISK
writes to the partition sector (LSN 0) of your designated hard drive.
Many CoCo-ers have their OS9 RBF file system there.  If you wish to use
use partitioning, then you will have to most likely reinstall Nitros9
and reconfigure it's Cloud-9 "superdriver" to use an offset different
the "0".  Hopefully, Nitros9 will someday be in the mind-set of
partitioning better than: "insert a 3 byte hex code into the device
descriptor".  Multiple YA-DOS drives have become a delight to set and
use now that the old "offset" problem is nearly killed.

* Although any YA-DOS supported device can be partitioned, not all
  drive types make sense.  A traditional floppy-sized image/disk, for
  instance is too small to bother with partitioning!

* FDISK displays absolute partition start sectors in HEX - hence the
  "$" preceding the displayed number.  Why are these numbers so BIG?
  The partitioning format supports 48 bit LSNs.  Too bad, YA-DOS,
  HDBDOS, and Nitros9 only do 24 bit LSNs !

* FDISK displays SIZES in a scaled decimal format.  After a size will
  appear one of the following suffixes:

  B - size in bytes
  K - size in kilobytes
  M - size in megabytes
  G - size in gigabytes
  T - size in terabytes

  fdisk uses a fast but inexact way to scale huge numbers down to
  something displayable - these numbers are scaled by 1024 bytes,
  rather than 1000 bytes.  Please take this into consideration.

* When entering an absolute partition start sector into FDISK, there
  are two ways to specify: in hex or decimal.  If the LSN you specify
  is preceded by the "$" prefix, then FDISK will read this as a
  hexadecimal number.  Otherwise FDISK will treat this number as a
  decimal number.  When specifying a new partition, leaving this input
  field blank (AKA just hitting "ENTER") will cause FDISK to auto fill
  this parameter from the previous partition's data.

* When entering sizes, just as in entering start sectors, you may
  prefix this field with "$" to specify a hexadecimal number.  You may
  also suffix your size with one of the scaling units as shown in the
  table above.  In addition to the display units, an additional unit
  is provided as a convenience:  the "S" until will consider the
  number as a multiple of traditional 35 Track DD SS disk sizes.  This
  will be handy for specifying HDBDOS/YA-DOS partitions. Considering
  the huge hard drives available today, most users will want one or
  more max partitions.  In this case, a size will be "256S".  No
  suffix will be considered a flat scale of "Sectors" (aka- not scaled)

* After loading and exec'ing FDISK, FDISK will need to know which
  "Mount No" you intend on setting up.  Please have this Mount No
  mounted before starting FDISK.

* When FDISK boots up, it will query the Hardware, if possible, and
  display the drive meta-information.  It will also try to read the
  existing partition table and display information about this too.

* When creating a new table header, if there is hardware
  meta-information, you may choose to auto-fill in the volume size and
  CHS settings from this data.

BASIC flow of creating a new partition table:

* load up FDISK.
* choose your mount number.
* create a new table header with "H"
* create new partitions one at a time with "N"
* save and quit via "W"

Basic Command table:

D - DELETE PARTITION
        Enter a partition number, it will mark it as deleted.  If you
        goof, you can "undelete" it with "U".
H - MODIFY HEADER
        Sets the table header, will with sizes, sector size, C/H/S
        geometry, etc.
I - PRINT HEADER
        Prints out the header information (as seen when starting FDISK).
L - LOAD PART FROM DISK
        Reloads the partition table from disk, all current changes
        will be erased.
M - PRINT THIS HELP
        Print a basic HELP screen.
N - NEW PARTITION
        Creates a new partition.
P - PRINT TABLE
        Lists the current partition to the screen.
Q - QUIT W/O SAVING
        yup, exactly!
S - SAVE TABLE
        Save the current header/table to disk.
T - PRINT KNOWN TYPES
        Print the known partition types.
U - UNDELETE PARTITION
        Constantly fights "D" for control.. :)
W - WRITE TABLE AND QUIT
        Yup....
X - PRINT EXTRA DEVICE INFO
        Print meta-info about drive, if any
E - WIPE ENTIRE TABLE
        Deletes all partitions!

   

*******************************
 RENAME.BAS and FORMAT.BAS
*******************************

FORMAT.BAS - "DSKINI"'s multiple YA-DOS disks on a partition
RENAME.BAS - "RENAME DRIVE's" multply YA-DOS disks on a partition
FLASH.BAS  - use with SDCDOS to flash "YADOS.ROM" into ROM.

Comments