
This Week With My Coleco ADAM  9709.07

by Richard F. Drushel  (drushel@apk.net)

I.  More About the EOS-8 Project.

I've  had  a few inquiries about the internals of EOS-8,  my  in-
progress/abandoned  upgrade to the EOS operating  system.  I  was 
digging  through some old correspondence and found some  informa-
tional  descriptions which might be of interest.  I also  decided 
that  I  would post some commented code for the universal  serial 
and parallel drivers that I wrote,  since these are in active use 
in ADAMserve (and also SmartBASIC 1.x, whence they were derived). 
This makes a rather easy TWWMCA article for me,  since I did  the 
actual writing in 1992 :-) But *you've* never seen it before,  so 
I'm not blushing too badly about dredging it up.

II. A Detailed Description of EOS-8.

Here  is a helpfile I wrote for the benefit of the other program-
mers  who  were nominally helping with the  EOS-8  project.  This 
accompanied a complete source listing and bootable SmartBASIC 2.0 
binary  which had been uploaded to Mark Gordon's BBS.  I  haven't 
found my disk with this binary yet,  but when I do, I will put an 
.IMG of the disk up for anonymous ftp.

Two errors of faulty recollection I made in TWWMCA  9708.31:  the 
prototype  ADAMnet  parallel  device is accessed as  PR  #2  from 
SmartBASIC 2.0,  and the serial device as PR #4 and IN #4. I will 
correct the archived version of this article;  newsletter editors 
and other archivers, please make this fix or grab my fixed vers-
ion from the ftp site (see end of article).


*****************************************************************

*** EOS87.HLP *** help file for EOS8 rev.7 (9209.20) by Richard
F. Drushel

This  file provides a brief overview of the design philosophy and 
implementation of EOS8,  specifically rev.7. This should serve as 
a  guide for outside reviewers and programmers as EOS8 is  final-
ized.
*****************************************************************

WHAT'S NEW IN EOS8 rev.7.


  o     Logical-to-physical device mapping.  ADAMnet device numbers
can be reassigned to non-ADAMnet physical devices, to allow existing
programs to function with non-ADAMnet hardware (i.e. use a parallel
printer 
2-63
        are reserved for up to 32 non-ADAMnet devices; the following 
        are defined:

        32   USERPAR_ID       parallel port (64)
        33   USERSER_ID       serial port (any Eve/Orphanware/MIB2)
        34   USERAMDISK_ID    RAMdisk using standard XRAM
        35   USERHD_ID        Hard disk (any Mini Wini/SASI/IDE)



This  includes  complete  emulation of ADAMnet  devices  by  non-
ADAMnet  equivalents.  Physical devices use dummy DCBs which  are 
set up as if they were controlling an actual ADAMnet device. This 
includes  the  status byte at (DCB+0)  and  the  device-dependent 
status at (DCB+20).  For serial devices, the (DCB+20) status bits 
for  #  characters pending and ok to send are maintained  exactly 
like  the  prototype ADAMnet serial board.  I/O  for  non-ADAMnet 
devices is *NOT* concurrent/background.  Thus,  all I/O initiated 
with a _START_...  call is performed to completion before exiting 
the  call,  including  updating the dummy DCB.  This  means  that 
_END_...  calls  for  non-ADAMnet I/O don't  do  anything  except 
return the status from the dummy DCB.


  o     Defined overlay area for hard drives.  The overlay has a
defined  code  and data interface so that any type of hard  drive 
(or  other block device) can be used.  The overlay  includes  the 
volume  offset table which is used to specify the volume sizes of 
the particular EOS partition.  This overlay is positioned so that 
the  current  HD volume remains at absolute  address  58343,  for 
compatibility  with existing programs.  The overlay must be  less 
than 400 bytes long.  The overlay interface accommodates up to 16 
EOS  volumes,  and has provisions for 2 hard drives per  physical 
interface:

        HD_MW1_CODE    EQU   1
        HD_MW2_CODE    EQU   2
        HD_SASI1_CODE  EQU   3
        HD_SASI2_CODE  EQU   4
        HD_IDE1_CODE   EQU   5
        HD_IDE2_CODE   EQU   6

        Note:  the current version was assembled with Mini Wini HD
drivers in place,  assuming 10 EOS volumes 1024 blocks each.  You 
will  have  to reassemble it for your own HD  characteristics  to 
access any volume other than 0; 0 will always work :)

  o     Hotkey functions for hard drives.  The following keys are
trapped:

        Shift-Undo           reboots HD from volume 0/block 0
        Shift-WildCard       parks HD heads
        Shift-Tab            toggles ahead the current HD volume,
                             wrapping back to 0 when MAX_VOLUMES 
                             is exceeded

  o     User-defined hotkey.  This was implemented as part of
EOS7. The user specifies a key to trap, and a vector to a handler 
routine. When this key is pressed, the handler routine is called; 
control returns to the main program.

  o     User-defined number of FCBs and DTAs.  Instead of being
hard-coded at 3,  the user can change the contents of NUM_FCBS to 
have  as  many  files open at once  as  desired.  Make  sure  you 
_FMGR_INIT after changing NUM_FCBS :) This was also part of EOS7.

  o     NMI clock driver routine.  Each CALL to this routine updates
the clock by one tick,  complete with weekday,  day,  month,  and 
year rollover. Additional locations in EOS_GLOBAL_RAM are defined 
to hold 60th of second, second, minute, hour, and weekday.

  o     Auxiliary jump table for direct access to non-ADAMnet devices
and extra EOS functions.

*****************************************************************

WHAT'S MISSING FROM EOS8 rev.7.

  o     Hardware initialization routines for both Eve/Orphanware and
MIB2 serial ports.  A management decision is needed regarding the 
parameter  passing mechanism--namely,  will we remain  compatible 
with the prototype ADAMnet serial board (device 14)? The difficu-
lty with this approach is that the values 0-5 will have to become 
reserved  data  values which flag initialization  parameters--you 
would lose the ability to send them as serial data independent of 
initialization, for the non-ADAMnet serial boards. If initializa-
tion  compatibility is not maintained,  then (1)  dedicated  init 
routines will be required for non-ADAMnet serial boards,  and (2) 
it  will not be possible for non-ADAMnet serial boards to emulate 
the  initialization code for device 14.  SmartBASIC 2.0 does  not 
attempt to initialize device 14,  but it is unknown if any  other 
Coleco EOS software attempts to do so.

  o     Trapping of serial port overrun, parity, and framing
errors.  The  source  code has conditional assembly of traps  for 
these errors.  The enclosed binary has these left out,  to  avoid 
problems with SmartBASIC 2.0.  (The way the code is in SmartBASIC 
2.0,  if you type too fast and overrun the port, the routine will 
loop  forever;  unlike  SmartBASIC  1.x,  it  will  not  force  a 
PR#0/IN#0 if an error occurs.) You can reassemble the source with 
the traps put back in if you like :)

  o     Software RAMdisk routines.  Since EOS8 ver.7 is currently
larger than 8K,  EOS code has spilled into what under EOS5 is the 
2nd  user  DTA.  The existing prototype RAMdisk  routine  (demon-
strated at ADAMcon IV) appropriates this area for its own  inter-
bank  transfers.  While it is possible to rewrite the RAMdisk I/O 
to  page through a smaller buffer,  I have decided to wait  until 
both  the  hardware  clock I/O routines and  the  VRAM  interrupt 
deferral routines are implemented,  so I know how large a RAMdisk 
buffer I will have available (either 256 or 512 byte).

  o     The 2nd user DTA.  To my knowledge, only SmartBASIC act-
        ually allows  the user to open 2 files at once.  Moreover,
because the  file I/O routines in SmartBASIC are defective, there
is no practical use for 2 open files.  EOS8 allows the applica-
tion programmer to both set the number of DTAs and to relocate 
the DTAs/FCBs, so future programs can have more than 1 user file 
open at once if proper  setup is done.  At least one  existing  
program,  however (ADAMlink  V) uses the 2nd DTA at its absolute 
address under EOS5 (not  relative  to the pointer to start of 
DTAs)  as  a  transfer buffer;  these  unfortunate  programs 
overwrite the larger  EOS8.  SmartBASIC  hackers  also have been 
known to store  machine  code routines here.

  o     Hardware clock I/O routines.  I can extract them from
SmartBASIC 1.x,  but have decided to wait for comments about what 
I have done already.

  o     VRAM I/O deferral during interrupts.  The logic of this
deferral has been described previously (in VRAMDISC.TXT).

  o     BLOCKS LEFT.  EOS7 unfortunately does *NOT* write BLOCKS 
LEFT as the name of the "not a file" directory entry.  Many exis-
ting programs look specifically for BLOCKS LEFT,  and hence  will 
crash under EOS7-8. I have not yet looked into fixing this.

  o     Bidirectional parallel printer emulation for SmartWriter.
I have not included  the routine which intercepts  the  printhead 
direction changes sent by SmartWriter to the ADAM  printer.  This 
means  that  text printed from SmartWriter will have every  other 
line spelled backwards. (This does not happen from the Electronic 
Typewriter  mode.)  An  80-byte line buffer  and  line  inversion 
software must be added to __PR_CH and __PR_BUFF.

*****************************************************************

-Rich


