This Week With My Coleco ADAM 9708.31 by Richard F. Drushel 
(drushel@apk.net). 

Technology Note. This  week's  TWWMCA  is  being composed using a  
rare  (but  not valuable) IBM PC/XT clone from 1983, a TAVA PC (made 
by TAVA Co., whoever  or  whatever they are or were).  There  must  
have  been enough  of  them  around at one time to make  it  
worthwhile  for Norton  Utilities version 4.5 to specifically detect
them in  the SI  (SYSINFO)  program.  Externally,  it's a dead ringer 
for  the original IBM PC;  internally,  however,  aside from having 
an ISA bus  and  the same arrangement of DIP switches  for  setting  
the memory  and video configuration,  it's totally different.  I  got 
this  as  a  freebie from a lab postdoc when I  was  in  graduate 
school.   Mostly   it  has  been  used  as  an  MFM  hard   drive 
formatting/testing  system,  and also to house the interface card 
for  my  EPROM  burner.  But  after  ADAMcon  09,  my  wife  Joan 
(am335@po.cwru.edu)  decided that she wanted to start looking  at 
USENET   newsgroups  for  some  60s  rock-n-roll   groups   she's 
interested  in,  using  the Cleveland Freenet.  I have  ADAMs  in 
abundance that I could have used,  but this PC system was already 
set  up,  would  already  do  80x24  screen  and  VT100  terminal 
emulation.  So,  until  such time as I can make a turnkey  system 
using an ADAM,  TDOS or CP/M, and my genuine H19 serial terminal, 
I guess I'll let her use this system.
Those who remember the door prize giveaways at the ADAMcon 08 banquet 
will remember the Hayes SmartModem  2400 I won from HLM-GMK Co.;  
this is the modem  that I'm using now.

The  other reason for using 
this TAVA system is that I still have been  too busy/lazy to unpack 
my travelling box from ADAMcon  09, which  has my 486 system in it. 
Right now,  this TAVA PC is  the only computer I have operational in 
my basement. 

I. ADAM Operating Systems
Most  of what I want to do in this issue of TWWMCA is  think  out 
loud and hopefully bounce some ideas off of other people's heads, 
regarding  a topic that was my initial interest in the ADAM,  and 
which has occupied most of my ADAM programming efforts:  enhanced 
ADAM operating systems. To review,  the ADAM has currently 4 
operating systems for  which user  software  is available:  
OS-7 (the ColecoVision video  game operating system), 
EOS (the Elementary Operating System developed by Coleco),  
Digital Research's CP/M  (ControlProgram/Microcompu ter), 
and an enhanced CP/M clone called TDOS (Tony's Disk Operating System,
named after its author,  Tony Morehen). OS-7 and EOS are present in 
ROM on every ADAM (OS-7 only on ColecoVisions, and EOS only on Expan
sion Module #3s). CP/M and TDOS must be run from tape or disk (though 
former B.A.S.I.C.  member Ron Collins had an ADAM in which the Smart
Writer word processor ROMs were replaced with  TDOS,  so this ADAM 
would boot to TDOS in the absence of an external  disk  or tape;  I 
saw this system myself  so  it's  not folklore).  Here  is a table 
summarizing the circulating versions of the different ADAM operating 
systems:     
operating system        version         date         
========================================================        
OS-7                    7PRIME          28 December 1982         
EOS                     5*              8 October 1984         
EOS                     7**             September 1984         
CP/M                    2.2             1984         
TDOS                    4.59            1992      
  Notes:* This is the value found at REV_NUM (FD60 hex) in all existing
ADAM EOS ROMs.  However, the actual version of the operating system is
 6, not 5.  This is explained in the following comment from the EOS-6 
source code:       
EOS_REV         EQU     005H    ;current EOS revision number  
                              ---NOTE---   this is actually rev;06 but 
to match the production ROM; it was labeled rev. 05 we fudge; just a 
bit (two bits actually)   
(For the binary-impaired, the joke in the comment is that 5=0101, 
t 6=0110; two bit positions must be changed to go from 0101 to 
0110.)**     
 EOS-7 was distributed on disk with the Disk Manager software, as well
as with the abandoned SmartBASIC 2.0. EOS-7 was a total internal 
rewrite with several additional functions, including (1) the ability
to trap a keypress as a "hotkey" and jump to a user- supplied service 
routine, and (2)  the  ability to have as many files  open  simultan-
eously  as desired,  provided  the user allocated sufficient memory 
for disk buffers. The major liability of EOS-7 is that it uses only 
2-byte instead  of  4-byte disk blocks,  thus limiting disks  to  
65,535 blocks  or  64 megabytes,  instead of 4,294,967,296 blocks  
or  4 gigabytes.

III. Limitations of ADAM Operating Systems.
All  4 ADAM operating systems have significant limitations  which have
hindered the development of new software (and hardware):

OS-7:  The 
operating system itself is quite well-designed,  being object-oriented 
and flexible.  The chief hindrance has been  lack of programmer docu-
mentation and suitable development tools, espe cially  for  creating 
background graphics screens  and  composing songs and sound effects. 
I   have   a  20th-generation  photocopy  of   the   ColecoVision 
Programmer's  Manual (obtained in 1992 from A.N.N.  founder Barry 
Wilson),  which  I have restored and made several copies  of  for 
interested parties;  as well as the OS-7PRIME source code listing 
from  the ADAM Technical Manual set.  To my knowledge,  since the 
ADAM/ColecoVision were dropped from the market,  no new cartridge 
games have been written except for Marcel de Kogel's Cosmo  Fighter,
which  appeared  in spring 1997;  this was a  byproduct  of Marcel's 
ColecoVision and ADAM emulator projects.

EOS: The biggest limitation 
of EOS is the sequential file system, which requires that the blocks 
of each file be contiguous;  there are  no  EOS  functions to "squeeze"
out holes  left  by  deleted files.  There  is  no  direct support for
subdirectories  or  for partitioning  large physical media into smaller
logical  drives. Finally, the ROM version present on every ADAM leaves
unimplemented  (i.e.,  just a RET instruction) the _POSITION_FILE 
function, which is supposed to be used to move a read/write pointer  
around in  a file,  to provide random access file I/O.  Because of 
this deficiency,  most existing EOS programs bypass EOS file I/O func-
tions  and read/write raw blocks of the  files--ick.  Third-party 
hardware can only be supported by (1) applications including their 
own driver code, or (2) direct patches to EOS after it is loaded from 
ROM to RAM.

CP/M:  Pre-existing  CP/M programs run fine under ADAM 
CP/M  2.2, except  that the CP/M world assumes your screen is 80 
columns  by 24  rows;  the  ADAM screen is 32 columns by 23 rows,  
so  you're stuck with an annoying,  horizontally-scrolling window as 
a  poor man's  80 column screen.  While CP/M supports I/O redirection
to and from serial devices (like modems and terminals),  the ADAMnet 
serial/parallel card never left the prototype stage,  so there is no 
serial/parallel access.  (The routines to access the prototype are 
present, but useless in the absence of the actual hardware.)

TDOS:  TDOS is modelled after ZCPR2 (an early CCP replacement for CP/M)
and contains built-in support for all available  3rd-party ADAM  
hardware (non-ADAMnet devices like serial  cards,  parallel cards, 
hard drives,  floppy drives larger than 160K,  and memory expanders
larger than 64K),  so it's possible to replace the ADAM video  screen
with a real 80x24 serial terminal and use all  the existing CP/M soft-
ware without the moving text window hassle. The chief problem with 
TDOS is that its creator,  Tony Morehen, is no longer  active in the 
ADAM community and is hence unavailable  to maintain the code. The 
TDOS source code is an unmanagable mess of uncommented  spaghetti,  
full of confusing  conditional  assembly directives, scattered over 
too many non-modular source files. You must assemble a new version of 
TDOS from source for every possib le  hardware configuration,  and 
the source is in  such  disarray that it's no longer expandable to 
accommodate new hardware.  (The source is probably not yet freely-
distributable,  either; there's been  no recent word from Tony about 
what he wants to do with it. Binaries are supposed to be  freely-
distributable,  however,  and have been.)

IV. The Future is the Past.
Progress in the realm of ADAM operating systems is limited by the 
same  issues which retard progress on Wintel and MacOS platforms: 
namely, the large installed base of existing software which needs 
to  be supported,  because of the economic clout of the users  of 
that software.

This  is also known as "the backward compatibility  
problem".  In short, it doesn't matter how nifty a new version of the 
operating system  is;  if  switching to it means that everyone has  
to  get (i.e.,  buy) new versions of their existing application 
programs, then  very few people will switch.  There are other 
 contributing factors, but much of the internal disarray of Win3.1
 and Win95 is due to this economic pressure to continue to support 
DOS software from  the  early and mid 1980s--software which did  
"bad"  things like  take over all the system resources,  modify its  
own  code, take  advantage  of undocumented features (which perforce 
 become "documented" as the need to retain the existing behavior  
becomes paramount).  Win95  makes  few concessions to DOS  programs, 
 and generally tries to make their continued use unpleasant;  but 
most Win3.1 programs still run under Win95--with the penalty that 
they destabilize  the system for the true-blue Win95  applications.  
A totally-from-scratch Win95 might have been "better" from a computer  
science viewpoint (and maybe from a user viewpoint as  well, in that 
the system would be more stable), but a certain financial disaster in 
the real world.
The backward compatibility problem is acutely worse 
for an  obsolete system like the ADAM, for which 98% of all the 
software that will every be written *has* already been written.  
Unless someone (or  a  team of someones) is also prepared to provide 
a suite  of compatible  applications,  writing a new and  improved  
operating system from scratch is a mere academic exercise.  The result 
will be interesting,  but nobody will actually use it, because none 
of the existing applications people have a large investment in (over 
10 years of active use in some cases) will run.

On  the CP/M side,  
there is a lot less to worry about;  CP/M was designed to be portable 
to many different hardware  architectures (all  using the 8080/Z80 
CPUs,  of course),  and there is a great conformance   of  CP/M  
applications  to  the  operating   system standards.  The  trick,  
then,  is to have a suitably  conforming version of CP/M running on
 your own hardware; then you will never have to patch applications 
(except in very precise ways,  such as escape codes for terminal 
programs).  TDOS with a serial terminal for  display  does this 
adequately  for  existing  hardware,  but cannot  now easily be 
altered to accommodate new  hardware.  Many TDOS users have been 
waiting since ADAMcon 06 for a TDOS-compati ble version of my ADAM
serve serially-linked device driver program (which  lets  an  ADAM 
control PC drives and other  hardware  via serial link).  In theory,  
it should be simple: replace the BIOS- level I/O routines with the 
ADAMserve protocol.  Alas,  the  TDOS BIOS is not really a well-
encapsulated BIOS module;  it is inline spaghetti  all over the 
place.  Disentangling it would take  more ADAM time than I have 
available at present.

On the EOS side,  the applications are really 
more important than the  operating system.  The Smart[fill in the 
blank] applications were designed to completely take over the machine. 
EOS itself is little  more than a program loader with some minimal 
system  ser vices.  In the EOS world,  you put in the program disk/
tape, pull the reset switch,  and run the program;  to switch programs,
you put in another disk/tape and pull the reset switch  again.  There 
is no concept of a shell, of programs exchanging information with each 
other except perhaps through files,  and especially of sha ring hard-
ware resources.  The worst offense in this regard is  in the  use of 
expansion memory.  Just about every EOS program  that finds  a memory 
expander appropriates it for itself.  Ironically, the contents of 
XRAM remain intact across system resets (as  long as you don't turn 
off the power,  just pull the reset switch), so the  idea of an 
expansion RAMdisk to share data between  applica tions  is attractive.
Unfortunately,  there are several  RAMdisk implementations,  all  
require  patching of EOS in order to  fun ction, and the patches are 
incompatible.

V. Escape Through the Universal Application?
The guiding design principle in my enhanced SmartBASIC 1.x inter 
preter  (released  1991)  was that all  available  ADAM  hardware 
should be supported with high-level commands,  and something sim ple 
like editing an ASCII text data file should be sufficient  to change  
hardware configurations.  Since I included all the driver code  as 
part of SmartBASIC 1.x and didn't try to patch  it  into EOS, I was 
completely successful. I was literally creating my own independent  
programming environment,  from which escape was  not necessary  
because  everything you needed to write  anything  you wanted was 
right there :-) But while I have sold 50-odd copies of SmartBASIC 
1.x over the last 6 years, I know of only one program mer besides 
me who used SmartBASIC 1.x that way, i.e., for every thing.
The ultimate  failure  of SmartBASIC 1.x was that it  could  not 
directly  run  existing SmartBASIC programs which  were  full  of
PEEKs,  POKEs,  and  CALLs.  I had provided high-level  functions 
which  made all those PEEKs,  POKEs,  and CALLs unnecessary;  yet 
rather than write new programs with the new tools,  people wanted to 
run their old ones unchanged. Perhaps if I had taken a year to write  
a suite of applications in SmartBASIC 1.x...but I  didn't, and so now 
I imagine that I am the only one still using  SmartBA SIC 1.x for 
anything (I do still use it for everything).

VI. The EOS-8 Project.
Before  I had come round to this rather pessimistic viewpoint,  I had 
considered that I could extend EOS in much the same way I had extended 
SmartBASIC.  Why not make EOS user-configurable?  Design overlay  areas
at defined locations in EOS RAM so you could  swap in  the driver for
whatever serial card you had,  or hard  drive, etc.;  provide pointers 
with which you had  the freedom  to  change the internal organization 
of EOS,  yet  still provide  user access to global data;  protect the
video  routines from  reentrancy during interrupts by building a defer-
ral  queue; use the ADAMnet device interface to non-ADAMnet devices by 
emula tion.  After ADAMcon 04,  I started work on this project, which I
called EOS-8 (since the last official version of EOS was  EOS-7). This 
was  ostensibly to be a group effort  involving  me,  Chris Braymen,  
Guy Cousineau, and Bruce Walters, with the programmer's forum  on Mark 
Gordon's Micro Innovations BBS to be our means  of communication. Other
than getting a few comments from the others, I did all the work. (No 
flames intended.)

The  EOS-8  project achieved some interesting proofs
of  concept. The  ADAMnet emulator idea (with its  logical-to-physical 
device mapping  table)  was  quite workable,  and it survives  today  
in ADAMserve EOS.  Using my own commented disassemblies (from  1988, 
before  I  knew that there was a broader ADAM community) and  the 
source listing from the ADAM Technical Manual I bought at ADAMcon 04, 
I regenerated a commented, assemblable source listing of EOS- 5,  
then optimized away all the junk and spaghetti and waste; the freed-up 
space was filled with new EOS-8 features.  One  version mapped an 
Orphanware serial board to the prototype ADAMnet serial device, and a
PIA2 printer card to the prototype ADAMnet parallel device;  when 
ADAMcalc was booted under this EOS,  the icons  for the  prototypes  
showed  up on the device  detect  screen--I  was probably  the  first
person outside of Lazer Microsystems to  see them actually work--and 
I had 3 printers to print from instead of just  the  ADAM printer.  
SmartBASIC 2.0 also could talk  to  the serial/parallel  card as IN 
#3/PR#3 and PR  #4;  under  EOS-8,  I could use a serial terminal in 
place of keyboard and screen.  Yet another  EOS-8 version had drivers 
for both the MFM and IDE  hard drives loaded simultaneously; I could 
read/write both hard drives and copy between them.  These were 
exciting times for me, because I felt like some kind of software 
archaeologist,  finding fossils of  things  which  actually did 
exist once,  and would  again  if awakened in the right way.
But  the  EOS-8 project could not achieve its  intended  goal  of 
being a universal,  all-in-one, support-everything-out-of-the-box 
operating system,  because of one fundamental limitation:  it had 
to fit into the 8K of EOS RAM beginning at address E000 hex.  EOS 
provides  no  top-of-memory function (i.e.,  the address  of  the 
highest  free memory address available to a user program  without 
colliding with the operating system).  Thus,  all of Coleco's EOS 
software  assumed  that E000 hex was the top of  memory,  because 
that's where EOS-5 started.  All the extra functionality I wanted 
to  put into EOS-8,  *working* functionality as  demonstrated  in 
tests,  could  not fit into that 8K limit,  no matter how much  I 
squeezed  and  optimized.  If I spilled below E000 hex,  my  code 
would get clobbered by the applications.  And in practical terms, 
there was no hope of disassembling every single Coleco program to 
figure out its memory map and change it (either by patching--very 
lucky--or  by wholesale rewriting/reassembly--a huge job with  no 
source).

A  possible  solution to the space problem would be  to 
write  a bank-switched  EOS;  that is,  use XRAM as additional 
storage and either swap needed routines in and out of intrinsic RAM,  
or else transfer control directly to code located in XRAM.  The 
difficul ties with this solution include (1) applications (like 
SmartWriter and File Manager) which  usurp XRAM for their own use, 
regardless of what's there already; (2)  handling  interrupts 
(especially non-maskable)  during  XRAM bank switching; and (3)  
determining the current memory configuration (including application
XRAM  usage) so that the correct configuration can  be restored at
exit.

(2) and (3) are especially problematic because the Video  
Display Processor  (VDP)  registers and all the memory map control  
ports are write-only;  you can't read them back to find out what  
their current value is.  Thus, unless the program saves the contents 
of all  these write-only registers somewhere for its own  reference, 
there's  no  way to tell what they are;  and if the bank  of  RAM 
containing  the copies gets switched out,  there's no way to read 
it.  The only foolproof way would be to add hardware (latch chips 
on  every write-only control port) to allow reading back of  cur 
rent  VDP and memory map status.  Of course,  anything which  re 
quires new ADAM hardware can never have widespread use; so again,
what's the point? This last objection can be overcome if I switch 
to  Marcel de Kogel's ADAM emulator;  I can modify  the  emulator 
code to save any I/O port data I want, without having to actually 
build the hardware. But I'm not quite ready to discard the physi 
cal ADAM in favor of a virtual version.

VII. Future Directions 
for ADAM Operating Systems.

I  think that the most promising 
avenue for ADAM operating system advancement lies in the adaptation 
of CP/M 3.0.  Now that Caldera are   giving   away  the  source  to  
both  CP/M  2.2   and   3.0 (http://www.caldera.com), it is becoming 
tempting for me to think about porting CP/M 3.0 to the ADAM.  Why 
3.0 instead of 2.2?  For starters,  3.0  supports lots of the 
command  shell  enhancements that  the  TDOS users are accustomed 
to,  as well as  time/  date stamping  of files.  The biggest 
attraction for me,  however,  is that CP/M 3.0 was designed to 
accommodate a bank-switched  opera ting  system.  Some of the
crufty optimizations of TDOS (in order to  maximize the Transient 
Program  Area,  TPA,  effectively  the memory  used by programs) 
could go away if some of the  operating system  could be moved to 
XRAM.  I have not yet obtained the CP/M 3.0 source; but I'd like to, 
soon.   As  for  EOS,  I don't think that much can be  done  beyond 
 what already  has  been implemented as part of the HARDDISK shell 
 and its  ADAMserve variant.  There are just too many existing  
"must- have"  programs  which are not maintainable/modifiable  in  
their current state (such as PowerPaint and all the patches-to-
SmartBA SIC-type  "applications"),   and  the  requirements  of  
backward compatibility are too extreme.
I would, of course, like to hear other opinions on this topic. My 
views  are just that, mine,  and not necessarily correct or  the 
definitive word on the subject. 

See you next week! 
*Rich*                       