
                       --=-=========================-=--
                            PC-DRAGON 6809 EMULATOR
                       --=-=========================-=--
                                                       
                                 Version 2.02
                               Source Code Notes
                               Copyright 1993-97
                                By PAUL BURGIN
                                                 
 Thankyou for using PC-Dragon, especially if you are a registered user. These
 notes  accompany the source code for the PC-Dragon. Instructions  for  using
 the  emulator  are  not  included here; for these  please  refer  to  either
 PCDRAGON.TXT  (plain  text  reference  manual)  or  PCDRAGON.PS  (postscript
 version of reference manual).
                                                   
 IMPORTANT:  Please note that the following restrictions apply to the  source
 code:
                                                   
  o   Redistribution of the freeware version of the emulator source  code  is
      permitted, but only as a complete and unmodified archive. Files in  the
      archive must not be altered in any way. Additionally, files must not be
      removed from or added to the archive.
                                                   
  o   Redistribution of the registered version of the emulator source code is
      not permitted, but copying for personal use only is acceptable.
                                                   
  o   Distribution of source code in modified and unmodified form (outside of
      the terms of these restrictions) may be permitted at the discretion  of
      (and by prior arrangement with) the author.
                                                   
  o   All  users  are granted permission to modify and recompile  the  source
      code for personal use.
                                                   
  o   Permission is also granted to distribute executables which are compiled
      from modified versions of the source code so long as this is done on  a
      non-profit  basis.  If you wish to distribute  derivative  versions  of
      PC-Dragon then you must clearly identify your version as such and  must
      not  remove  the authors original copyright messages. Please  take  all
      reasonable  steps to ensure that it is unlikely your modified  emulator
      distribution will be confused with the authorised freeware distribution
      of PC-Dragon.
                                                   
 The  above restrictions do not apply to KEY.H and KEY.ASM, which are  freely
 distributable.
                                                   
 The  following  notes  aim to annotate the source code.  It  has  been  made
 available  in  response  to  the requests that  I've  received  from  people
 interested  in  the workings of the emulator, and possible  ports  to  other
 machines.  I hope therefore that the public release of the source code  will
 help to answer the questions and increase your enjoyment of the emulator.
 
 The  source  code  is  written  in C and is suitable  for  compilation  with
 Turbo/Borland C. It has been developed under Turbo C++ IDE V3.1 running on a
 486DX-33  (in  this  configuration a full build  consists  of  approximately
 36,700 lines of code and takes about 75 seconds).
 
 PC-Dragon  also  makes use of a customised version of  a  freeware  keyboard
 handler  written  by  Lee Hamel. This package consists of  KEY.ASM  and  the
 header  file  KEY.H.  It is used to take control of INT9  when  `Real  Mode'
 keyboard emulation is selected. It is written in 8086 assembler suitable for
 Borland  Turbo Assembler. The associated object file KEY.OBJ (complied  with
 TASM  V2.02) is included here for the benefit of anyone without access to  a
 suitable assembler.
 
 The  emulator source code is composed of 9 header files and 15 code modules.
 I  should  point  out  that  it is no work of art.  PC-Dragon  started  life
 experimentally as a little something I "knocked up in my shed" and  went  on
 from there to become a big something I "knocked up in my shed". As such,  it
 has  been chopped, changed, designed, and redesigned etc. according to need.
 This colourful history may be evident in places in the source code, although
 I have always tried to make the components fit together as best I could.
 
 The source code contains quite a few comments to explain the implementation,
 although they are scattered more liberally in some modules than others.  All
 files require a TAB size of 4 characters.
 
 The  header files and code modules are listed below. Each module is  related
 to  a  peripheral which is emulated by PC-Dragon, or implements an  internal
 subsystem of the emulator.
 
 PC-Dragon Header Files
 ----------------------
 
 6809CPU.H  Definitions of 6809 instructions and addressing modes.
 6809REGS.H Declarations and definitions for 6809 registers.
 BUILD.H    Public definitions and build options.
 DOIO.H     Definitions used for the DOIO instruction.
 EXTERN.H   External function and variable prototypes.
 KEY.H      Keyboard interrupt and scan code definitions.
 MACROS.H   Common functions which are expanded in-line.
 SNAPSHOT.H PAK format definitions.
 TYPES.H    Miscellaneous type definitions.
 
 PC-Dragon Modules
 -----------------
 
 6809TAB    Table of data for 6809 instructions.
 CASSETTE   Cassette and cartridge emulation.
 DEBUGGER   Built-in debugger and disassembler.
 DIALOGUE   Functions for dialogue boxes, menus and info screen.
 DRAGON     Fetch-execute cycle, 6809 instructions, memory access.
 JOYSTICK   Functions for joystick emulation and mouse support.
 KEYBOARD   Functions for keyboard emulation and internal buffers.
 KEYWORDS   Tables of defaults for the programmable keys.
 MOTOROLA   Functions for reading S19 format files.
 SAMPIAS    SAM and PIA chip emulation.
 SERVICES   Functions which provide the emulator services.
 SNAPSHOT   Functions for reading and writing snapshots.
 TEXTVIEW   Stand-alone text viewer utility.
 TITLE      Functions to display the start-up and exit messages.
 VIDEO      Text and graphics screen emulation.
 KEY        Replacement handler for keyboard interrupt.
 
 The  original  project file DRAGON.PRJ is also included. This file  contains
 the compiler options required to rebuild the emulator. If you use another PC
 compiler or are otherwise unable to use this file then you must ensure  that
 you  compile the software for the MEDIUM memory model and enable support for
 the graphics library.
 
 In  order  to  protect the emulator copyright, module TITLE is  supplied  in
 object form only in the freeware version of the source code, but is supplied
 as source code in the registered version of the source code.
 
 To  link the object files you will also require a far segment version of the
 EGA/VGA graphics driver in object form. To create this file use the compiler
 supplied  utility  BINOBJ.EXE together with the /F  option  and  the  driver
 EGAVGA.BGI.  The  output from this conversion should be  EGAVGAF.OBJ,  which
 should be copied to your PC-Dragon source directory.
              
 The  fetch-execute section of DRAGON.C may seem quite erratic. It uses a lot
 of  embedded declare blocks and temporary register variables, but  there  is
 good  reason  for this. This particular section has been coded in  this  way
 which  appears to generate more efficient machine code. For this  and  other
 time-critical sections of the software I have studied the disassembly of the
 machine code generated by the compiler, and from this I have optimised the C
 source code as best I can. All suggestions for further optimisations are, of
 course, most welcome!



                                                                     08/06/97

