       
                    ======================================
                           T3 Dragon / CoCo Emulator
                                  Version 0.6
                      Copyright 1995-1997 by Paul Burgin
                    ======================================
                                                           
  1    Introduction
  
  Welcome to T3. T3 is a multi-tasking Dragon and Tandy CoCo II emulator for
  80386  PCs.  Used in conjunction with a ROM file from one  of  these  6809
  based  home computers, it enables you to run your old software on a modern
  PC.
  
  Note  that  a  ROM file is not included in the emulator distribution.  You
  must obtain one from elsewhere before you can use T3.
  
  2    What Is Emulated
  
  The following components are emulated by T3:
      6809 CPU;
      Automatically emulates Dragon 32, Dragon 64 or Tandy CoCo II
       compatible architecture depending on the ROM file provided;
      All machines are provided with 64K of RAM and a switchable BASIC ROM;
      SAM chip with high resolution graphics, realistic text and semi-
       graphics;
      Bi-directional cassette interface;
      Cartridge port;
      Digital joysticks;
      Interrupt driven counter/timer mechanism (not 100% accurate).
  
  T3 also has additional features such as:
      Multiple sessions within a single instance of T3;
      Pre-emptive multitasking;
      Image facility;
      Variable speed control.
  
  The following are not emulated by this version of T3 (some of the items in
  this list may be implemented at a later date, and others won't):
      Mid resolution (16 bytes/line) graphics modes;
      Disk drives;
      Sound;
      Serial port / parallel port;
      Joysticks via the PC joystick.
  
  3    System Requirements
  
  The minimum system specification is shown below. T3 will not start if your
  system does not meet these requirements:
      80386 processor;
      MS-DOS v4.00;
      VGA graphics adapter;
      197K of base memory (approx.).
  
  The following is the recommended system specification for running a single
  session with full speed and functionality:
      80386 SX-33 or above;
      MS-DOS v7.00 (Windows 95) or above;
      VGA or SVGA graphics adapter;
      197K of base memory (approx.).
  
  If  you have additional base memory available then you will be able use T3
  to  run  more  than one Dragon/CoCo session (task) at once.  Approximately
  133K  of  base memory is required for each additional task (subject  to  a
  maximum of four tasks).
  
  If  you  have additional processing power available then you can elect  to
  have  T3  execute  all of your tasks simultaneously. Tasks  then  continue
  running even when switched into the background. When T3 is used for multi-
  tasking smoother emulation should be obtained for faster CPUs.
  
  4    What Does T3 Mean?
  
  Well, it's nothing to do with that pop group, of that you can be sure!
  
  Although it still hasn't reached v1.00 and a wider distribution, T3 has in
  fact been around for nearly two years. The name T3 was originally intended
  to be only a working title, being an extreme contraction of "PC-Dragon III
  (386  Turbo  Edition)". This name was conceived at  a  time  when  T3  was
  expected  to  re-use code from PC-Dragon II. However, it turned  out  that
  this was not practical and as a result T3 has been written from scratch as
  a new emulator in it's own right.
  
  Nevertheless, the name has now become familiar and so it would be somewhat
  confusing to change it at this stage. It will therefore remain as T3 until
  such a time as I can think of something better!
  
  5    Files In The T3 ZIP File
  
  The following files are supplied in the ZIP file:
  
  WHATSNEW.006        Summary of changes for this release.
  README.TXT          Instructions (this file).
  T3.EXE              T3 executable.
  T3.DAT              T3 title page (can be deleted to save space).
  
  6    Getting Started
  
  To  begin  using the emulator you need to copy a ROM file  into  the  same
  directory as T3.EXE; having done so type T3 to start the emulator.
  
  T3  tries a variety of different names when it searches for a ROM file and
  will  use  the first file found. Valid names include T3, DRAGON,  DRAGROM,
  COCO,  TANDYROM, and D64ROM1. You can use files in either  DGN  format  or
  Jeff   Vavasour's  ROM  format;  T3  auto-detects  which  you  are   using
  irrespective of the file name.
  
  If  you want to use a particular ROM file you can specify the -r option on
  the command line when you start T3. E.g.
  
                                T3  -rCOCO.ROM
  
  Note  that  if  the ROM file name includes a space then you will  need  to
  enclose the entire option in double quotes. E.g.
  
                            T3 "-rD32 AND ALLDREAM"
  
  If  you are using T3 to emulate a Dragon 64 and want to use the 64K  BASIC
  mode, you will additionally need the 64K BASIC ROM, which should have file
  name D64ROM2.DGN.
  
  Once started press any key to proceed from the title page and T3 will boot
  your Dragon or CoCo. When you wish to quit the emulator press F12 followed
  by RETURN.
  
  7    Emulator Controls
  
  The  following  are  key combinations which can be  used  to  control  the
  emulator:
  
  F2                Cassette mode control.
  F3                Jump to Alldream.
  F4                Jump to Dreambug.
  F8                Load image (hold SHIFT for save image).
  F9                Previous task.
  F10               Next task.
  F11               Create new task.
  F12               Delete current task (hold SHIFT for auto-save image).
  
  Alt-A             Artifacting control.
  Alt-C             Cursor keys control.
  Alt-L             Lower case text toggle.
  Alt-P             Suspend task (i.e. pause).
  Alt-R             Resume task.
  Alt-S             Speed control.
  Alt-T             Text colour control.
  Alt-V             Display emulator version.
  Alt-X             Task type control.
  
  SCROLL LOCK       Freeze task.
  Ctrl-Alt-Delete   Warm reset (hold SHIFT for cold reset).
  
  Additionally, PGUP has the same function as F9, PGDN has the same function
  as  F10,  INSERT  has  the same function as F11 and DELETE  has  the  same
  function as F12.
  
  F7 has the same function as Ctrl-Alt-Delete. It is not needed when running
  T3  in MS-DOS, but should be used when running T3 in environments where it
  is  not  safe to press Ctrl-Alt-Delete (e.g. when running T3 in a DOS  box
  under MS-Windows).
  
  The  NUM LOCK key can be used instead of the Alt keys in order to  prevent
  joystick fire buttons being pressed.
  
  The following keys can be used in file name input dialogue boxes:
  
  F2             Paste Dragon/CoCo name.
  DEL            Backspace.
  HOME           Erase all.
  ESC            Quit.
  RETURN         Accept.
  
  Additionally Ctrl-Alt-Delete, F7 and F12 have the same function as ESC.
  
  The following keys can be used in selection boxes:
  
  LEFT           Previous option.
  RIGHT          Next option.
  UP             First option.
  DOWN           Last option.
  ESC            Quit.
  RETURN         Accept.
  
  Additionally  HOME has the same function as UP. END has the same  function
  as DOWN. Ctrl-Alt-Delete, F7 and F12 have the same function as ESC.
  
  8    Joysticks
  
  Joysticks are emulated using the PC cursor keys (but can be disabled using
  Alt-C).  Both of the left and right joysticks are operated simultaneously,
  but the fire buttons may be operated separately.
  
  Press  the  left Ctrl key or right Alt key to simulate the  left  joystick
  fire  button.  Press the left Alt key or right Ctrl key  to  simulate  the
  right  joystick fire button. Pressing the keypad 5 key will simulate  both
  fire buttons at once.
  
  9    Virtual Cassettes
  
  When the Dragon/CoCo requires access to cassettes you will be prompted for
  the name of an MS-DOS file to be used as a virtual cassette.
  
  Type  the  name  in  the box with or without a .CAS  extension  and  press
  RETURN.  Pressing F2 pastes the name of the file that the  Dragon/CoCo  is
  attempting  to access (if any) into the box, but you can only  enter  well
  formed names so some characters may be translated to underscores.
  
  If you are running T3 with MS-DOS v7.00 or above and IFSMGR loaded (i.e. a
  DOS  box  in Windows 95) then you can type up to 250 characters  including
  upper  case letters, lower case letters, numbers, special  characters  and
  spaces. If running T3 with an earlier version of MS-DOS or without  IFSMGR
  loaded  (i.e.  MS-DOS  mode in Windows 95) then  you  can  enter  only  75
  characters  which  may  include upper case letters,  numbers  and  special
  characters.  If  long file names are available then the  cursor  is  blue,
  otherwise it is grey.
  
  When  saving a cassette, should you enter the name of a file which already
  exists  then  T3 will display the message "FILE EXISTS" and allow  you  to
  choose  to  cancel the file name, append to the existing file, or  replace
  it.
  
  T3  does  not  impose a limit on the length of cassette  files.  They  are
  normally closed when the file mode changes or if you reset or quit a task,
  but  can also be closed manually by pressing F2 and selecting CLOSED.  You
  will need to do this to write separate programs consecutively to different
  MS-DOS files, to recover from an ?IO ERROR, or to enter a file name  after
  pressing Quit.
  
  Unlike  all  other  emulation performed by T3, the cassette  emulation  is
  implemented  at the operating system level rather than the hardware  level
  (ROM  breakpoints are installed at start-up). Cassette emulation therefore
  does  not  work for the (very small number of) programs which  access  the
  cassette mechanism at the hardware level.
  
  10   Cartridges
  
  To  load  a cartridge into T3 you must append it to your ROM file.  To  do
  this type an MS-DOS command such as the following:
  
                COPY  /B  DRAGON.DGN  +  CART.RAW  DRAGCART.DGN
                                T3  -rDRAGCART
  
  Note that your cartridge must be in a raw (pure data only) format.
  
  If  you  load the Alldream cartridge into the emulator then the F3 and  F4
  keys  can  be used to immediately jump to Alldream (F3) or Dreambug  (F4).
  The  exact  function performed by F3 is: push PC register onto the  stack,
  push  ($FFFE) onto the stack, push $C000 onto the stack, clear the I  flag
  in  the  condition code register, and finally execute jump to $A93A.  This
  has the effect of returning to text mode and then executing Alldream. When
  you  quit  Alldream a reset occurs. F4 performs the same  function  except
  that $D384 is pushed onto the stack rather than $C000.
  
  Remember  that  in order for Alldream/Dreambug to function correctly,  the
  CLEAR  command  should be used to set-up their workspace before  they  are
  executed.
  
  11   Images
  
  Images are copies of the entire workspace of a T3 task. Image support  was
  initially  implemented in order to aid debugging of the emulator  but  has
  now  been made available for general use. The use of images allows you  to
  save the context of a task to continue at a later date, or perhaps save  a
  position in a game for instant replay.
  
  To  save  an  image  simply press SHIFT + F8. The  current  task  is  then
  immediately saved to disk. It can be reloaded at any time by pressing  F8.
  All  task  settings and ROMs are saved in the image, so that the  reloaded
  task state is identical to the saved state.
  
  Note that T3 provides access to just one image file at a time. It does not
  prompt for a file name when you load or save an image. However you can use
  the -i command line option to change the image file name when you start T3
  (see notes on -r option for applicable syntax).
  
  Note  also that images should not considered to be snapshots because  they
  are  much  larger than snapshots need to be, and are non-portable  between
  emulators  (or  even T3 versions). A portable snapshot  facility  will  be
  included in a future version of T3.
  
  12   Automatic Images
  
  T3  can also create "automatic" images which are used slightly differently
  to  standard images. To save an automatic image hold down SHIFT  when  you
  delete a standard task and you will be given the option of auto-saving it.
  After  doing  so,  when  you  next start  T3  the  image  will  be  loaded
  automatically, creating an "automatic" task.
  
  Automatic  tasks behave slightly differently to standard tasks;  they  are
  automatically  saved  when deleted. Also, some T3  messages  are  slightly
  different,  and to protect the integrity of the task and the copyright  of
  the emulator some control keys and command line options are unavailable.
  
  Automatic  images can be saved and loaded at any time by pressing  F8  and
  SHIFT + F8 as usual.
  
  You  can  prevent T3 from loading automatic images by deleting them  (file
  name  T3.IMG),  or by using the -a command line option when  you  run  T3.
  This is the only permitted command line option for automatic tasks. Syntax
  as follows:
  
  -a0            Ignore any image.
  -a1            Load any image as an automatic task.
  -a             Automatic toggle (equivalent to -a0 or -a1 as appropriate).
  
  The following are the only valid control keys for automatic tasks:
  
  F8             Load image (hold SHIFT for save image).
  F9             Previous task.
  F10            Next task.
  F12            Auto-save image (hold SHIFT for delete task).
  
  Alt-P          Suspend task (i.e. pause).
  Alt-R          Resume task.
  Alt-S          Speed control.
  Alt-X          Task type control.
  
  SCROLL LOCK    Freeze task.
  
  Automatic images have one particularly specialised use; they can  be  used
  to  create  executable PC programs from Dragon/CoCo programs. To  do  this
  proceed as follows:
  
  1.    Run  T3  as normal, and load the Dragon/CoCo program from a  virtual
        cassette.
  
  2.    Use the emulator control keys to ensure that the cursor keys,  lower
        case, and text colour task settings are correct for the loaded
        program.
  
  3.    From  the title page of the program, press SHIFT + F12 to  auto-save
        an image of the program.
  
  4.    You  can  now create an executable Dragon/CoCo program on  a  floppy
        disk by typing:
  
                         COPY  T3.EXE  A:\PROGNAME.EXE
                               COPY  T3.IMG  A:\
                                       
  5.    PROGNAME.EXE can be run on any 80386 PC with MS-DOS v4.00  or  above
        and  a  VGA  graphics  adapter. It will start immediately  and  will
        have  persistent data each time it is run (thus  retaining  progress
        in  an  adventure game, or preserving hi-score tables in  an  arcade
        game, etc.).
  
  13   Multi-Tasking
  
  When  T3 is started it will emulate just one Dragon/CoCo. However, if  you
  have   spare   base  memory  available  then  you  can  create  additional
  Dragon/CoCo  sessions at any time by pressing the F11 key (or INSERT).  T3
  then  spawns and boots a new Dragon/CoCo session (or task) and  moves  the
  previously executing Dragon/CoCo task into the background.
  
  Each  new task is entirely independent of other tasks, receiving it's  own
  RAM,  ROMs  and  emulator  workspace (includes settings,  keyboard  state,
  cassette  buffer, text font etc.). The ROMs for the new  task  are  copied
  from  the  current  task  when the new task is created,  but  the  RAM  is
  cleared.
  
  Once  you have more that one task running under T3, you can switch between
  them at any time by pressing F10 (or PGDN) to switch to the next task, and
  F9  (or  PGUP)  to switch to the previous task. Unwanted tasks  should  be
  deleted  in  the  usual  way by pressing F12 (or  DELETE).  T3  will  then
  terminate the current task and switch to the next remaining task, if any.
  
  In  addition to allowing a variable number of tasks to be created,  T3  is
  also capable of executing the tasks simultaneously. It does so using a pre-
  emptive  multi-tasking  executive  which  switches  context  between   the
  available tasks up to 17 times per second (switching is synchronised  with
  Dragon/CoCo  interrupts in order to reduce game flicker and  is  therefore
  slower for slower PCs).
  
  By  default all tasks are timesliced in this manner, and receive an  equal
  share  of  processing  time  irrespective  of  whether  they  are  in  the
  foreground  or the background and irrespective of their target speeds.  If
  desired,  however,  the type of individual tasks may be  changed  so  that
  they do not share processing time with other tasks.
  
  Pressing  Alt-X when two or more tasks exist causes a task type  selection
  box  to  appear. The type of the current task can then be  set  to  either
  "timeslice"  or "exclusive". If set to "timeslice" then a task will  share
  processing time with any other "timeslice" tasks whenever any of them  are
  in  the  foreground.  By  contrast, if the  type  of  a  task  is  set  to
  "exclusive"  then it will not execute at all when it is in the background,
  and  will  not  allow  any other tasks to execute  whilst  it  is  in  the
  foreground.
  
  Any tasks which are suspended or frozen do not receive a timeslice even if
  they are in the foreground, thus suspending or freezing a "timeslice" task
  may  cause other "timeslice" tasks to execute more quickly (this  will  be
  the case if a task is currently executing slower than it's target speed).
  
  Note  that because tasks are independent, they each require a lot of  base
  memory  (133K  per  task). This limits the number of tasks  which  can  be
  created  by  T3  to  four for a minimally booted PC, or two/three  for  an
  average  PC  set-up.  Future versions of T3 may allow  more  tasks  to  be
  created (e.g. by allowing ROM sharing, or by swapping exclusive tasks into
  EMS/XMS),  but in the meantime it is of course possible to run  more  than
  four  Dragon/CoCo tasks by using an environment such as MS-Windows or  MS-
  DOS v5.00/v6.00 DOSSHELL in order to run more than one instance of T3.
  
  14   Target Speed
  
  Each  task has an independent target speed setting. T3 assesses the  speed
  of  each task relative to the target setting for every 25 Dragon/CoCo  IRQ
  periods executed (this equates to approximately every half a second if the
  target  speed is 100%). The average instruction execution speed  for  each
  task  is  then  adjusted, where necessary, in order to meet the  requested
  target speed as closely as possible.
  
  Note  that  the  dynamic execution speed adjustments  are  made  in  small
  increments  (or decrements). It therefore takes a few seconds  for  T3  to
  make  any necessary speed adjustments whenever tasks are created, deleted,
  suspended, frozen or resumed.
  
  If  the target speed for a task is set to MAX then the execution speed  of
  that  task  is not measured or adjusted. The task simply runs as  fast  as
  possible.
  
  15   Frequently Asked Questions
  
  People  ask me a lot of questions about T3 and the Dragon/CoCo  scene,  so
  please  check  to  see if the answer to your question is here  before  you
  write to me. Thanks.
  
  Q.   Where can I download T3 updates?
  
  A.    The  latest  version of T3 is held on my web site.  The  address  is
  "http://public.logica.com/~burginp/t3.html".  Please  feel  free  to  make
  links to this page, but do not link directly to the ZIP file because  your
  link will be invalidated when the ZIP is updated.
  
  Q.   Where on the Internet can I find the ROM files?
  
  A.   You can get the ROM files for the Dragon 32, Dragon 64 and Tandy CoCo
  II  from  at least one site on the Internet. Try Ross Hamilton's web  site
  and David Linsley's web site. You can also find links to these from my own
  web  site,  but for copyright reasons the files are not stored there.  Try
  address "http://public.logica.com/~burginp/emulators.html#roms".
  
  Q.   Why don't you include the ROM files?
  
  A.    I  don't  include them because I have no right to do  so.  They  are
  copyrighted,  and  as  much as we may dislike it, that  copyright  remains
  valid.  I  agree  that  it  is very unlikely that  I  would  be  sued  for
  infringing the copyright, but that is my risk and I choose not to take it.

  Also,  including the ROMs in the emulator ZIP would force  any  person  or
  site distributing the emulator to infringe the same copyright, which would
  be  unfair on them. Moreover, some archive sites (including SimTel)  would
  not  accept  T3  if  the ROMs were included. If you did receive  the  ROMs
  together with the emulator then please drop me a line at the address given
  at the end of these instructions.
  
  Q.   Why won't my ROM work?
  
  A.    This problem is almost always caused by your ROM file being corrupt.
  You  should  obtain  another  copy, ensuring that you  are  downloading in
  binary mode.
  
  Q.   Why won't the keyboard/joysticks work in <game>?
  
  A.    This problem is usually caused by the game taking exception  to  the
  fact that by default T3 allows the PC cursor keys (standard and keypad) to
  simultaneously emulate both the Dragon/CoCo joysticks and the  Dragon/CoCo
  cursor keys. The solution is to use the Alt-C control to set the PC cursor
  keys  to  emulate either the Dragon/CoCo joysticks only or the Dragon/CoCo
  cursor keys only.
  
  Q.   How do I load this *.CAS format software into T3?
  
  A.    If the program is machine code format, type "CLOADM". This will work
  for  most  software. If the OK prompt appears after loading then you  will
  need  to  type  "EXEC". Remember to always perform  a  cold  reset  before
  loading  each game into T3. If you still get unexpected results then  your
  *.CAS file is probably corrupt. For software written in BASIC type "CLOAD"
  and then "RUN".
  
  Q.   How do I load this *.PAK format software into T3?
  
  A.   You can't. This version of the emulator does not support snapshots.
  
  Q.   How can I load my old tapes into T3?
  
  A.    There are a few utilities around which enable tapes to be copied  to
  files  on  your  PC  by  using a SoundBlaster  card.  Download  the  older
  emulators  (PCDGN201.ZIP  and COCO2-14.ZIP)  and  read  the  documentation
  provided there.
  
  Q.   How can I load my old disks into T3?
  
  A.   You can't. T3 does not support disk drive emulation. Your only option
  is  to  transfer the software to another format (such as a cassette  file)
  and  use  that. This is only possible for a small number of programs.  You
  can transfer files from Dragon disks to PC disks using PC-CONVERT (contact
  NDUG), and from CoCo disks using COCO2-14.ZIP. Raw disk format files  held
  in  PC  format  can  be  converted  to  cassette  files  using  DC.EXE  in
  PCDGN201.ZIP.
  
  Q.   Where can I get a copy of <game>?
  
  A.    For Dragon games check Ross Hamilton's archive, a link to which  can
  be         found         on         my         web         site         at
  "http://public.logica.com/~burginp/dragon.html". If  you  can't  find  the
  game there you will have to convert it to PC format yourself. Please don't
  ask me to send it to you.
  
  Q.   Where can I buy hardware these days?
  
  A.    I  do not keep information about hardware suppliers, and cannot help
  with these types of enquiries.
  
  Q.   Please help me with OS9, or with my Tandy <machine>?
  
  A.    I  have  no  knowledge of these, sorry, and  cannot  help  with  any
  enquiries.
  
  16   Disclaimer
  
  If  you  choose  to use T3 then you do so entirely at your  own  risk.  No
  warranty either implied or otherwise is provided for this software.  Usage
  of T3 constitutes acceptance of these terms.
  
  17   Usage Restrictions
  
  T3  v0.6  is released to the public domain. It may be used and distributed
  without  charge,  but  MUST  NOT be uploaded to  FTP  sites/www  sites  or
  bulletin  boards. Eventually T3 v1.0 will be made available for widespread
  distribution,  but  until  then  I  would  like  it  to  reside  only   at
  "http://public.logica.com/~burginp/t3.html".
  
  18   Address For Comments And Bug Reports
  
  If  you  have  any  comments on T3 please do drop  me  a  message  at  the
  following address "BurginP@Logica.Com". If you are reporting a bug  please
  include as much information as possible (but do not send binaries).
  
  If  you  have  access to the world wide web please refer to the  notes  at
  "http://public.logica.com/~burginp/mail.html".
  
